# CSV provider

The **CSV provider** collects metrics from CSV files and makes them available to Akamas. It offers a very versatile way to integrate custom data sources.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

This section provides the minimum requirements that you should match before using the CSV File telemetry provider.

### Network requirements <a href="#network-requirements" id="network-requirements"></a>

The following requirements should be met to enable the provider to gather CSV files from remote hosts:

* Port 22 (or a custom one) should be open from Akamas installation to the host where the files reside.
* The host where the files reside should support SCP or SFTP protocols.

### Permissions <a href="#permissions" id="permissions"></a>

* Read access to the CSV files target of the integration

## Akamas supported version <a href="#akamas-supported-version" id="akamas-supported-version"></a>

* Versions < 2.0.0 are compatibile with Akamas until version 1.8.0
* Versions >= 2.0.0 are compatible with Akamas from version 1.9.0

## Supported component types <a href="#supported-component-types" id="supported-component-types"></a>

The CSV File provider is generic and allows integration with any data source, therefore it does not come with support for a specific component type.

## Setup the data source <a href="#setup-the-data-source" id="setup-the-data-source"></a>

To operate properly, the CSV file provider expects the presence of four fields in each processed CSV file:

* A timestamp field used to identify the point in time a certain sample refers to.
* A component field used to identify the Akamas entity.
* A metric field used to identify the name of the metric.
* A value field used to store the actual value of the metric.

These fields can have custom names in the CSV file, you can specify them in the provider configuration.

The [Install CSV provider](https://docs.akamas.io/akamas-docs/integrating/integrating-telemetry-providers/csv-provider/install-csv-provider) page describes how to get this Telemetry Provider installed. Once installed, this provider is shared with all users of your Akamas installation and can be used to monitor many different systems, by configuring appropriate telemetry provider instances as described in the [Create a CSV provider instance](https://docs.akamas.io/akamas-docs/integrating/integrating-telemetry-providers/csv-provider/create-csv-provider-instances) page.

## Accepted Timestamp Formats

Akamas uses Java [DateTimeFormatter](https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/text/DateFormatter.html) to parse timestamps provided in the telemetry data. The format specified in the configuration must strictly follow the rules and symbols defined by [DateTimeFormatter](https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/text/DateFormatter.html). Misconfigured patterns will cause the system to fail during initialization.

### Timestamp Format Syntax

The timestamp format string must comply with the syntax provided by [DateTimeFormatter](https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/text/DateFormatter.html). Each character or group of characters in the pattern has a specific meaning. Below is a summary of the most commonly used symbols:

| **Symbol** | **Meaning**            | **Example**          |
| ---------- | ---------------------- | -------------------- |
| `y`        | Year of era            | `2024`               |
| `M`        | Month-of-year          | `06` (June)          |
| `d`        | Day-of-month           | `17`                 |
| `H`        | Hour-of-day (0-23)     | `15`                 |
| `m`        | Minute-of-hour         | `05`                 |
| `s`        | Second-of-minute       | `30`                 |
| `S`        | Fraction-of-second     | `008` (milliseconds) |
| `z`        | Time zone abbreviation | `UTC`                |

### Parsing Other Characters

Any **alphabetical character** not listed in the table above must be enclosed in **single quotes** to be parsed correctly. This includes literal characters like `'T'` in ISO-8601 formats.

For example:

* **Incorrect**: `yyyy-MM-ddTHH:mm:ss` → *Error: Unknown pattern letter T*
* **Correct**: `yyyy-MM-dd'T'HH:mm:ss`

This rule applies to any fixed characters you want to include in the format string.

### Common Timestamp Formats

Here are some examples of correctly formatted patterns:

1. **ISO 8601 Local DateTime (without time zone)**\
   Pattern: `yyyy-MM-dd'T'HH:mm:ss`\
   Example: `2024-06-17T15:05:30`
2. **ISO 8601 with Fractional Seconds**\
   Pattern: `yyyy-MM-dd'T'HH:mm:ss.SSS`\
   Example: `2024-06-17T15:05:30.008`
3. **Date and Time without Literal T**\
   Pattern: `yyyy-MM-dd HH:mm:ss`\
   Example: `2024-06-17 15:05:30`
4. **Custom Format with Zone**\
   Pattern: `yyyy/MM/dd HH:mm:ss z`\
   Example: `2024/06/17 15:05:30 UTC`