Akamai Distribution of the OpenTelemetry Collector for Akamai Cloud Pulse is Akamai’s version of the Open Telemetry Collector, used under the Apache License, Version 2.0.

This collector (aclp-collector) facilitates the export of telemetry data from Akamai Cloud services to external observability tools that support the OpenTelemetry standard. This guide provides instructions for installing and using the collector, which is available as a precompiled binary, a Docker image, or via a Helm chart for Kubernetes environments.

📘

Currently, the collector supports Managed Databases (service_type: "dbaas"). Support for additional services will be added in future releases.

Supported platforms

Build artifacts for the collector are specifically compiled for AMD64 Linux platforms and should only be deployed to compatible Linux environments.

Akamai Distribution of the OpenTelemetry Collector for Akamai Cloud Pulse has been verified on Linux OS:

• Ubuntu 22.08+
• Debian 11+,
• AlmaLinux 8+
• Alpine 3.19+
• CentOS Stream 9
• Fedora 41
• Rocky Linux 8.

Step 1: Create your config.yaml file

To export your telemetry data, you'll need to create a configuration file. To get started, you can download a sample config.yaml containing a basic set of supported components. Modify the components and their associated parameters to suit your specific environment, and add your personal access token (PAT).

Supported components

The following components are available in the collector. You can customize them and their settings to suit your specific use case.

Receiver configuration

Akamai Cloud Pulse provides users with access to key operational metrics for core Akamai Cloud services. These metrics are exposed through the ACLP REST API and persisted in a Time Series Database (TSDB) managed by Akamai.

akamaicloudpulsereceiver queries the API, extracts relevant service metrics, and converts them into OpenTelemetry-compliant telemetry data for downstream processing and export.

This section outlines the configurable parameters for akamaicloudpulsereceiver. Customize these parameters in your config.yaml file.

Naming conventions

• When defining multiple receivers of the type akamaicloudpulsereceiver, add suffixes to the receiver names following the pattern akamaicloudpulsereceiver/1, akamaicloudpulsereceiver/2, akamaicloudpulsereceiver/3, and so on.
• When defining multiple services of the same type within a receiver block, add suffixes to the service names following the pattern dbaas/1, dbaas/2, and so on.

Example configuration

  akamaicloudpulsereceiver/1:
    polling_interval: "1m"
    refresh_interval: "30m"
    PAT: "<your-PAT-token>"
    thread_pool_size: 80
    services:
    	- service_type: "dbaas"
      	entity_ids: ["*"]
      	metric_names: ["memory_usage", "disk_usage"]
      	agg_function: "min"
      	query_delay: "2m"
      	group_by: ["entity_id"]
  akamaicloudpulsereceiver/2:
    services:
      - service_type: "dbaas/1"
        entity_ids : [123456, 7891011]
        metric_names: ["cpu_usage"]
        polling_interval: "1m"
        PAT : "<your-PAT-token>"
        agg_function: "avg"
        group_by: ["entity_id"]
      - service_type: "dbaas/2"
        regions : ["*"]
        metric_names: ["memory_usage"]
        polling_interval: "5m"
        PAT : "<your-PAT-token>"
        agg_function: "sum"
        refresh_interval: "20m"
        group_by: ["entity_id"]

Step 2: Run the collector

You can deploy the collector as a precompiled binary, as a Docker image, or via a Helm chart in Kubernetes.

Collector binary

Download the aclp-collector binary. Once downloaded, deploy and run the binary with the config.yaml file using:

chmod +x aclp-collector_v<binary_version>_linux_amd64
./aclp-collector_v<binary_version>_linux_amd64 --config=<path/to/config.yaml>

Docker image

Run the collector using the Docker image from Docker Hub along with a configured config.yaml file. Make sure the config.yaml file has been downloaded and customized before running the following commands:

docker run -d --name aclp-collector \
  -v <path/to/config.yaml>:/etc/aclp-collector/config.yaml \
  linode/aclp-collector:<tag-name> \
  --config /etc/aclp-collector/config.yaml

Helm chart

Run the collector on a Kubernetes cluster using the Helm chart from Docker Hub along with a configured config.yaml file. Make sure the config.yaml file has been downloaded and customized before running the following commands:

helm install aclp-collector oci://registry-1.docker.io/linode/aclp-collector \
  --version <chart-version> \
  --set-file config=<path/to/config.yaml>

Step 3: Visualize metrics

Assuming you have configured the otlphttp or Prometheus exporter sink, connect a visualization tool to the sink endpoint to visualize telemetry data from the collector. See opentelemetry-collector and opentelemetry-collector-contrib to learn more about configuring and using the supported exporters.

Debugging

You can use the following exporters to verify the collector pipeline and inspect the telemetry data it emits.

Collector logs

By default, the collector sends its logs to standard output (stdout). If you want to save these logs to a file to debug later, the collector's config file doesn't include a path setting for log files. Instead, you can redirect stdout to a file using a pipe:

./aclp-collector --config=<path/to/config.yaml> > aclp-collector.log 2>&1

You can configure the collector's telemetry logs by adding the telemetry section to the collector's config file:

telemetry:
  logs:
    level: "debug"           # Available: debug, info, warn, error, DPanic, panic, fatal
    encoding: "console"      # Options: "json" or "console"

Debug Exporter

You can use the debug exporter to print telemetry data (metrics, in this case) directly to the collector’s console logs. This is useful for troubleshooting without sending data to an external backend.

To use the Debug exporter, add the following to the exporters section of your config.yaml:

exporters:
  debug:
    verbosity: detailed

Prometheus Exporter

The Prometheus exporter exposes metrics on an HTTP endpoint that can be scraped by Prometheus or visualized in Grafana.

To use the Prometheus exporter, add the following to the exporters section of your config.yaml:

exporters:  
  prometheus:  
    endpoint: "<bind_address>:<port>"

You can view the raw exported metrics in a browser by visiting http://<bind_address>:<port>/metrics, or by using curl:

curl http://<bind_address>:<port>/metrics

Health check

OpenTelemetry Collector provides a built-in health check endpoint to monitor its liveness and readiness. This is especially useful in containerized or orchestrated environments like Docker and Kubernetes.

Health Check Extension

The health check extension exposes a simple HTTP endpoint that returns "200 OK" when the collector is healthy or "500" if the collector isn't ready or has failed.

To use health check, add the extension to the extensions section of your config.yaml:

extensions:  
  health_check:  
    endpoint: "<bind_address>:<port>"

Once the collector is running, you can test the health check endpoint using:

curl http://<bind_address>:<port>/health

Performance optimization

If you observe issues like delayed metrics or missed data in the visualization or debug logs, you can fine tune the configuration for better performance.

For example, you might want to consider increasing the value of thread_pool_size to improve parallelism.

Hot reloading the collector with configuration updates

The collector supports hot-reloading of its configuration using signals such as SIGHUP. This means configuration adjustments can be applied in production environments without stopping and restarting the collector, minimizing downtime.

It is strongly recommended that you validate configuration changes before issuing a SIGHUP. Invalid configurations may cause errors or data loss. To validate a configuration, download the collector binary
and run the following command:

./aclp-collector_v<binary-version>\_linux_amd64 validate --config=\<path/to/config.yaml>

If any issues are present, the validation command will report them in advance.

Assuming the configuration is validated and the collector is already running, you can apply the updated configuration using SIGHUP. The process differs slightly depending on the deployment method.

Hot reload in binary mode

Modify the configuration file.

Find the process ID (PID) of the running collector:

ps aux | grep aclp-collector_v<binary-version>\_linux_amd64

Send a SIGHUP signal to the collector process:

kill -HUP <collector-pid>

Hot reload in Docker

Modify the configuration file.

Send a SIGHUP signal to the running container:

docker kill --signal=SIGHUP <container-name>

Hot reload in Kubernetes

Retrieve the running pods:

kubectl get pods

Inspect the collector process inside the pod to confirm the PID:

kubectl exec -it <pod-name> -n <namespace> -- sh
> ps aux | grep aclp-collector
> exit

📘

In Kubernetes, configuration changes can't be directly applied via SIGHUP. You must first update the ConfigMap and reapply it.

Update and apply the ConfigMap:

kubectl create configmap <configmap-name> --from-file=config.yaml=config.yaml -o yaml --dry-run=client | 
kubectl apply -f -

Once the updated ConfigMap is applied, send a SIGHUP to the collector process:

kubectl exec -n <namespace> <pod-name> -- kill -HUP <pid>