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

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

Network requirements

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

• Read access to the CSV files target of the integration

Akamas supported version

• 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

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

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 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 page.

To install the CSV File provider, create a YAML file (called provider.yml in this example) with the specification of the provider:

# CSV File Telemetry Provider
name: CSV File
description: Telemetry Provider that enables to import of metrics from a remote CSV file
dockerImage: 485790562880.dkr.ecr.us-east-2.amazonaws.com/akamas/telemetry-providers/csv-file-provider:3.0.2

Then, you can then install the provider with the Akamas CLI:

akamas install telemetry-provider provider.yml

Install the Telemetry Provider

Skip this part if the Telemetry Provider is already installed.

To install the Dynatrace provider, create a YAML file (called provider.yml in this example) with the definition of the provider:

# Dynatrace Telemetry Provider
name: Dynatrace
description: Telemetry Provider that enables to import metrics from Dynatrace installations
dockerImage: 485790562880.dkr.ecr.us-east-2.amazonaws.com/akamas/telemetry-providers/dynatrace-provider:3.1.7

Then you can install the provider using the Akamas CLI:

akamas install telemetry-provider provider.yml

To create an instance of the CSV provider, build a YAML file (instance.yml in this example) with the definition of the instance:

# CSV Telemetry Provider Instance
provider: CSV File
config:
 address: host1.example.com
 authType: password
 username: akamas
 auth: akamas
 remoteFilePattern: /monitoring/result-*.csv
 componentColumn: COMPONENT
 timestampColumn: TS
 timestampFormat: YYYY-MM-dd'T'HH:mm:ss
metrics:
 - metric: cpu_util
   datasourceMetric: user%

Then you can create the instance for the system using the Akamas CLI:

akamas create telemetry-instance instance.yml system

timestampFormat format

Regarding the timestamp format, please notice that while the week-year format YYYY is compliant with the ISO-8601 specification, but you should replace it with the year-of-era format yyyy if you are specifying a timestampFormat different from the ISO one. For example:

• Correct: yyyy-MM-dd HH:mm:ss

• Wrong: YYYY-MM-dd HH:mm:ss

You can find detailed information on timestamp patterns in the Patterns for Formatting and Parsing section on the DateTimeFormatter (Java Platform SE 8) page.

Configuration options

When you create an instance of the CSV provider, you should specify some configuration information to allow the provider to correctly extract and process metrics from your CSV files.

You can specify configuration information within the config part of the YAML of the instance definition.

Required properties

• address - a URL or IP identifying the address of the host where CSV files reside

• username - the username used when connecting to the host

• authType - the type of authentication to use when connecting to the file host; either password or key

• auth - the authentication credential; either a password or a key according to authType. When using keys, the value can either be the value of the key or the path of the file to import from

• remoteFilePattern - a list of remote files to be imported

Optional properties

• protocol - the protocol to use to retrieve files; either scp or sftp. Default is scp

• fieldSeparator - the character used as a field separator in the csv files. Default is ,

• componentColumn - the header of the column containing the name of the component. Default is COMPONENT

• timestampColumn - the header of the column containing the timestamp. Default is TS

• timestampFormat - the format of the timestamp (e.g. yyyy-MM-dd HH:mm:ss zzz). Default is YYYY-MM-ddTHH:mm:ss

You should also specify the mapping between the metrics available in your CSV files and those provided by Akamas. This can be done in the metrics section of the telemetry instance configuration. To map a custom metric you should specify at least the following properties:

• metric - the name of a metric in Akamas

• datasourceMetric - the header of a column that contains the metric in the CSV file

The provider ignores any column not present as datasourceMetric in this section.

The sample configuration reported in this section would import the metric cpu_util from CSV files formatted as in the example below:

TS,                   COMPONENT,  user%
2020-04-17T09:46:30,  host,       20
2020-04-17T09:46:35,  host,       23
2020-04-17T09:46:40,  host,       32
2020-04-17T09:46:45,  host,       21

Telemetry instance reference

The following represents the complete configuration reference for the telemetry provider instance.

provider: CSV File            # this is an instance of the Csv provider
config:
 address: host1.example.com   # the adress of the host with the csv files
 port: 22                     # the port used to connect
 authType: password           # the authentication method
 username: akamas             # the username used to connect
 auth: akamas                 # the authentication credential
 protocol: scp                # the protocol used to retrieve the file
 fieldSeparator: ","          # the character used as field separator in the csv files
 remoteFilePattern: /monitoring/result-*.csv    # the path of the csv files to import
 componentColumn: COMPONENT                     # the header of the column with component names
 timestampColumn: TS                            # the header of the column with the time stamp
 timestampFormat: YYYY-mm-ddTHH:MM:ss         # the format of the timestamp
metrics:
 - metric: cpu_util                             # the name of the Akamas metric
   datasourceMetric: user%                      # the header of the column with the original metric
   staticLabels:
    mode: user                                  # (optional) additional labels to add to the metric

The following table reports the configuration reference for the config section

The following table reports the configuration reference for the metrics section

Use cases

Here you can find common use cases addressed by this provider.

Linux SAR

In this use case, you are going to import some metrics coming from SAR, a popular UNIX tool to monitor system resources. SAR can export CSV files in the following format.

hostname, interval,     timestamp, 		        %user,	%system,      %memory
machine1, 600,		2018-08-07 06:45:01 UTC,	30.01,	20.77,		96.21
machine1, 600,		2018-08-07 06:55:01 UTC,	40.07,	13.00,		84.55
machine1, 600,		2018-08-07 07:05:01 UTC,	5.00,	90.55,		89.23

Note that the metrics are percentages (between 1 and 100), while Akamas accepts percentages as values between 0 and 1, therefore each metric in this configuration has a scale factor of 0.001.

You can import the two CPU metrics and the memory metric from a SAR log using the following telemetry instance configuration.

provider: CSV File
config:
  remoteFilePattern: /csv/sar.csv
  address: 127.0.0.1
  port: 22
  username: user123
  auth: password123
  authType: password
  protocol: scp
  componentColumn: hostname
  timestampColumn: timestamp
  timestampFormat: yyyy-MM-dd HH:mm:ss zzz
metrics:
- metric: cpu_util
  datasourceMetric: %user
  scale: 0.001
  staticLabels:
    mode: user
- metric: cpu_util
  datasourceMetric: %system
  scale: 0.001
  staticLabels:
    mode: system
- metric: mem_util
  scale: 0.001
  datasourceMetric: %memory

Using the configured instance, the CSV File provider will perform the following operations to import the metrics:

1. Retrieve the file "/csv/sar.csv" from the server "127.0.0.1" using the SCP protocol authenticating with the provided password.

2. Use the column hostname to lookup components by name.

3. Use the column timestamp to find the timestamps of the samples (that is expected to be in the format specified by timestampFormat).

4. Collect the metrics (two with the same name, but different labels, and one with a different name):

   • cpu_util: in the CSV file is in the column %user and attach to its samples the label "mode" with value "user".

   • cpu_util: in the CSV file is in the column %system and attach to its samples the label "mode" with value "system".

   • mem_util: in the CSV file is in the column %memory.

Akamas provides the following areas of integration with your ecosystem, which may apply or not depending on whether you are running live optimization studies or offline optimization studies:

• Telemetry Providers tools providing time series for metrics of interest for the system to be optimized (see also Telemetry Providers) - this integration applies to both offline and live optimization studies;

• Configuration Management tools providing the ability to set tunable parameters for the system to be optimized - this integration applies to both offline and live optimization studies;

• Value Stream Delivery tools to implement a continuous optimization process as part of a CI/CD pipeline - this integration applies to both offline and live optimization studies;

• Load Testing tools used to reproduce a synthetic workload on the system to be optimized; notice that these tools may also act as Telemetry Providers (e.g. for end-user metrics) - this integration only applies to offline optimization studies.

These integrations may require some setup on both the tool and the Akamas side and may also involve defining workflows and making use of workflow operators.

To install the Prometheus provider, create a YAML file (provider.yml in this example) with the definition of the provider:

Then you can install the provider using the Akamas CLI:

The installed provider is shared with all users of your Akamas installation and can monitor many different systems, by configuring appropriate telemetry provider instances.

To create an instance of the Prometheus provider, edit a YAML file (instance.yml in this example) with the definition of the instance:

Then you can create the instance for the system using the Akamas CLI:

Configuration options

When you create an instance of the Prometheus provider, you should specify some configuration information to allow the provider to extract and process metrics from Prometheus correctly.

You can specify configuration information within the config part of the YAML of the instance definition.

Required properties

• address, a URL or IP identifying the address of the host where Prometheus is installed

• port, the port exposed by Prometheus

Optional properties

• user, the username for the Prometheus service

• password, the user password for the Prometheus service

• job, a string to specify the scraping job name. The default is ".*" for all scraping jobs

• logLevel, set this to "DETAILED" for some extra logs when searching for metrics (default value is "INFO")

• headers, to specify additional custom headers e.g: headers: "custom_key": "custom_value"

• namespace, a string to specify the namespace

• duration, integer to determine the duration in seconds for data collection (use a number between 1 and 3600)

• enableHttps, boolean to enable HTTPS in Prometheus (since 3.2.6)

• ignoreCertificates, boolean to ignore SSL certificates

• disableConnectionCheck, boolean to disable initial connection check to Prometheus

Custom queries

The Prometheus provider allows defining additional queries to populate custom metrics or redefine the default ones according to your use case. You can configure additional metrics using the metrics field as shown in the configuration below:

In this example, the telemetry instance will populate cust_metric with the results of the query specified in datasource, maintaining the value of the labels listed under labels.

Akamas placeholders

Akamas pre-processes the queries before running them, replacing special-purpose placeholders with the fields provided in the components. For example, given the following component definition:

the query sum(jvm_memory_used_bytes{instance=~"$INSTANCE$", job=~"$JOB$"}) will be expanded for this component into sum(jvm_memory_used_bytes{instance=~"service01", job=~"jmx"}). This provides greater flexibility through the templatization of the queries, allowing the same query to select the correct datasources for different components.

The following is the list of available placeholders:

Example 1

Example 2

Use cases

This section reports common use cases addressed by this provider.

Collect Java metrics

The command will expose on localhost on port 9100 Java metrics of youJar.jar __ which can be scraped by Prometheus.

config.yaml is a configuration file useful for the activity of this exporter. It is suggested to use this configuration for an optimal experience with the Prometheus provider:

As a next step, add a new scraping target in the configuration of the Prometheus used by the provider:

You can then create a YAML file with the definition of a telemetry instance (prom_instance.yml) of the Prometheus provider:

And you can create the telemetry instance using the Akamas CLI:

Finally, to bind the extracted metrics to the related component, you should add the following field to the properties of the component’s definition:

Collect system metrics

Here’s the manifest of the node_exporter service:

The service will expose on localhost on port 9100 system metrics __ which can be scraped by Prometheus.

As a final step, add a new scraping target in the configuration of the Prometheus used by the provider:

You can then create a YAML file with the definition of a telemetry instance (prom_instance.yml) of the Prometheus provider:

And you can create the telemetry instance using the Akamas CLI:

Finally, to bind the extracted metrics to the related component, you should add the following field to the properties of the component’s definition:

Akamas supports the integration with virtually any telemetry and observability tool.

Supported Telemetry Providers

The following table describes the supported Telemetry Providers, which are created automatically at installation time.

Notice that Telemetry Providers are shared across all the workspaces within the same Akamas installation, and only users with administrative privileges can manage them.

Supported versions

• Dynatrace SaaS or Managed version 1.187 or later

  • Versions < 2.0.0 are compatible with Akamas until version 1.8.0

  • Versions >= 2.0.0 are compatible with Akamas from version 1.9.0

Supported component types

• Linux

  • Ubuntu-16.04, Rhel-7.6

• JVM

  • java-openjdk-8, java-openjdk-11

  • java-ibm-j9vm-6, java-ibm-j9vm-8, java-eclipse-openj9-11

• Web Application

• Kubernetes and Docker

Refer to to see how component-types metrics are extracted by this provider.

Prerequisites

• a valid Dynatrace license

• Dynatrace OneAgent installed on the servers where the Dynatrace entities to be monitored are running

• Connectivity between:

  • Akamas server and Dynatrace server over port 443 (if Dynatrace is deployed on-premises)

  • Akamas server and internet (over https) if Dynatrace is managed as a SaaS platform

• URL (+ port if it is not the default one) of your Dynatrace server (SaaS or Managed)

• API token from your Dynatrace server (Saas or Managed) with the rights to "Access problems and event feed, metrics, and topology" - see more details

• A Dynatrace user belonging to the group "Monitoring viewer", which allows access to the environment in read-only mode, without being able to change settings, download or install OneAgent

Permissions

The Dynatrace provider needs a Dynatrace API token with the following privileges:

• metrics.read (Read entities)

• entities.read (Read metrics)

• DataExport (Access problem and event feed, metrics, and topology)

• DataImport (Data ingest, e.g.: metrics and events)

• ReadSyntheticData (Read synthetic monitors, locations, and nodes)

Component configuration

To map metrics collected from Dynatrace to Akamas component, the Dynatrace provider looks up some properties in the components of a system grouped under dynatrace.

These properties give you access to different strategies to map Akamas components onto Dynatrace entities:

• Map by id

• Map by name

• Map by tags

Map by id

You can map a component to a Dynatrace entity by leveraging the unique id of the entity, which you should put under the id property in the component:

You can find the id of a Dynatrace entity by looking at the URL of a Dynatrace dashboard relative to the entity. Watch out that the "host" key is valid only for Linux components, other components (e.g. the JVM) require to drill down into the host entities to get the PROCESS_GROUP_INSTANCE or PROCESS_GROUP id

Map by name

You can map a component to a Dynatrace entity by leveraging the entity’s display name which you should put under the name property in the component definition:

Map by tags

You can map a component to a Dynatrace entity by leveraging Dynatrace tags that match the entity, tags which you should put under the tags property in the component definition. If multiple tags are specified all instances matching any of the specified tags will be selected.

In the case of a key-only tag, the example above would be:

Improve component mapping with type

You can improve the matching of components with Dynatrace by adding a type property in the component definition, this property will help the Provider match only those Dynatrace entities of the given type.

The type of an entity can be retrieved from the URL of the entity’s dashboard

Available entities types can be retrieved, from your Dynatrace instance, with the following command:

Kubernetes specific properties

A set of Kubernetes-specific properties can be used to allow users to retrieve data related to the monitored Kubernetes clusters.

Please note, that the property type is required to retrieve Kubernetes entities. Currently, the supported types in Dynatrace are the following

The following Kubernetes object can be retrieved from Dynatrace.

Container

The following properties are supported for containers:

Example

Pod

The following properties are supported for pods

Example

The installed provider is shared with all users of your Akamas installation and can monitor many different systems, by configuring appropriate telemetry provider instances.

To create an instance of the Dynatrace provider, build a YAML file (instance.yml in this example) with the definition of the instance:

Then you can create the instance for the system using the Akamas CLI:

Configuration options

When you create an instance of the Dynatrace provider, you should specify some configuration information to allow the provider to correctly extract and process metrics from Dynatrace.

You can specify configuration information within the config part of the YAML of the instance definition.

Required properties

• url - URL of the Dynatrace installation API (see to retrieve the URL of your installation)

• token - A Dynatrace API Token with the

Collect additional metrics

You can collect additional metrics with the Dynatrace provider by using the metrics field:

Configure a proxy for Dynatrace

In the case in which Akamas cannot reach directly your Dynatrace installation, you can configure an HTTP proxy by using the proxy field:

Telemetry instance reference

This section reports the complete reference for the definition of a telemetry instance.

This table shows the reference for the config section within the definition of the Dynatrace provider instance:

Proxy options reference

This table reports the reference for the config → proxy section within the definition of the Dynatrace provider instance:

Metrics options reference

This table reports the reference for the metrics section within the definition of the Dynatrace provider instance. The section contains a collection of objects with the following properties:

Use cases

This section reports common use cases addressed by this provider.

Collect system metrics

Check the Linux optimization pack for a list of all the system metrics available in Akamas.

As a second step, choose a strategy to map your Linux component (MyLinuxComponent) with the corresponding Dyntrace entity.

Let’s assume you want to map by id your Dynatrace entity, you can find the id in the URL bar of a Dyntrace dashboard of the entity:

Grab the id and add it to the Linux component definition:

You can leverage the name of the entity as well:

As a third and final step, once the component is all set, you can create an instance of the Dynatrace provider and then build your first studies:

The Prometheus provider collects metrics from a Prometheus instance and makes them available to Akamas.

This provider includes support for several technologies. In any case, you can specify your own queries to gather any metric you want.

Prerequisites

This section provides the minimum requirements that you should match before using the Prometheus provider.

Supported versions

• Prometheus 1.x and 2.x.

Network requirements

• Prometheus is reachable at a provided URL or IP address and port (the default Prometheus port is 9090)

Supported Prometheus exporters

• (Linux system metrics)

• (Java metrics)

• (Docker container metrics)

• exporter (AWS resources metrics)

• (Web application metrics)

Akamas supported version

• Versions < 2.0.0 are compatibile with Akamas untill version 1.8.0

• Versions >= 2.0.0 are compatible with Akamas from version 1.9.0

Supported component types

• Ubuntu-16.04, Rhel-7.6

• java-openjdk-8, java-openjdk-11

• java-ibm-j9vm-6, java-ibm-j9vm-8, java-eclipse-openj9-11

• Container

• ec2

• Web Application

Setup the data source

The Prometheus provider does not require a specific configuration of the Prometheus instance it uses, except for the need for setting the value of the instance label of each data point so that it matches the value of the instance property in a component; in this way, the Prometheus provider can know which data point refers to which component in a system.

Here’s an example configuration for Prometheus that sets the instance label:

Component configuration

Akamas reasons in terms of a system to be optimized and in terms of parameters and metrics of components of that system. To understand which metrics collected from Prometheus should refer to which component, the Prometheus provider looks up some properties in the components of a system grouped under prometheus property. These properties are:

• instance, which tells the provider "where" a component is

• job (optional), which filters the imported metrics by exporter identifier, useful when different components run on the same instance. If not provided, this value defaults to the one configured globally in the telemetry-instance definition.

Nested under this property you can also include any additional field your use case may require to further filter the imported metrics. These fields will be appended in queries to the list of label matches in the form field_name=~'field_value', and can specify either exact values or patterns.

It is important that you add instance and, optionally, the job properties to the components of a system so that the Prometheus provider can gather metrics from them:

This page describes how to set up an OracleDB exporter in order to gather metrics regarding an Oracle Database instance through the Prometheus provider.

Installation

The OracleDB exporter repository is available on the . The suggested deploy mode is through a , since the Prometheus instance can easily access the running container through the Akamas network.

Use the following command line to run the container, where cust-metrics.toml is your configuration file defining the queries for additional custom metrics (see paragraph below) and DATA_SOURCE_NAME an environment variable containing the Oracle EasyConnect string:

You can refer to the for more details or alternative deployment modes.

Custom queries

It is possible to define additional queries to expose custom metrics using any data in the database instance that is readable by the monitoring user (see for more details about the syntax).

Custom Configuration file

The following is an example of exporting system metrics from the Dynamic Performance (V$) Views used by the Prometheus provider default queries for the :

This page describes how to set up a CloudWatch exporter in order to gather AWS metrics through the Prometheus provider. This is especially useful to monitor system metrics when you don’t have direct SSH access to AWS resources like EC2 Instances or if you want to gather AWS-specific metrics not available in the guest OS.

AWS policies

In order to fetch metrics fromCloudWatch, the exporter requires an IAM user or role with the following privileges:

• cloudwatch:GetMetricData

• cloudwatch:GetMetricStatistics

• cloudwatch:ListMetrics

• tag:GetResources

You can assign AWS-managed policies CloudWatchReadOnlyAccess and ResourceGroupsandTagEditorReadOnlyAccess to the desired user to enable these permissions.

Exporter configuration

The CloudWatch exporter repository is available on the . It requires a minimal configuration to fetch metrics from the desired AWS instances. Below is a short list of the parameters needed for a minimal configuration:

• region: AWS region of the monitored resource

• metrics: a list of objects containing filters for the exported metrics

  • aws_namespace: the namespace of the monitored resource

  • aws_metric_name: the name of the AWS metric to fetch

  • aws_dimensions: the dimension to expose as labels

  • aws_dimension_select: the dimension to filter over

  • aws_statistics: the list of metric statistics to expose

  • aws_tag_select: optional tags to filter on

    • tag_selections: map containing the list of values to select for each tag

    • resource_type_selection: resource type to fetch the tags from (see: )

    • resource_id_dimension: dimension to use for the resource id (see: )

Notice: AWS bills CloudWatch usage in batches of 1 million requests, where every metric counts as a single request. To avoid unnecessary expenses configure only the metrics you need.

Prometheus configuration

Notice: AWS bills CloudWatch usage in batches of 1 million requests, where every metric counts as a single request. To avoid unnecessary expenses configure an appropriate scraping interval.

Additional workflow task

Once you configured the exporter in the Prometheus configuration you can start to fetch metrics using the Prometheus provider. The following sections describe some scripts you can add as tasks in your workflow.

Wait for metrics

Start/stop the exporter as needed

Since Amazon bills your CloudWatch queries is wise to run the exporter only when needed. The following script allows you to manage the exporter from the workflow by adding the following tasks:

• start the container right before the beginning of the load test (command: bash script.sh start)

Custom Configuration file

The example below is the Akamas-supported configuration, fetching metrics of EC2 instances named server1 and server2.