This guide walks you through configuring and deploying the Akamai Distribution of the OpenTelemetry Collector for Akamai Cloud Pulse (the collector) and verifying that metrics are being collected and exported successfully.

Follow these instructions to export metrics to observability platforms that support OpenTelemetry, such as Prometheus and Grafana.

Step 1: Generate a personal access token (PAT)

Generate a personal access token (PAT) using Cloud Manager or the Linode API. The collector uses the PAT to authenticate requests to the API.

Ensure your PAT includes:

• Read access for Monitor
• Read access for the service for which metrics are being collected. For example, Object Storage metrics require an object_storage:read scope.

Store your PAT securely—You’ll need it when you configure the receiver in your configuration file (config.yaml).

📘

API requests made using the PAT are subject to user-level API rate limits. For more information, see API rate limits and request batching.

Step 2: Create the collector configuration file

Create a collector configuration file (config.yaml). You can download a sample configuration file as a starting point. The sample configuration includes a basic set of supported components. Modify these components and their associated parameters to match your environment. For more information, see Receiver configuration.

When creating your initial configuration:

• Start with a single service, metric, and region
• Use conservative polling intervals

Example:

receivers:
  akamaicloudpulsereceiver:
    PAT: "<PAT>"  
    services:  
     - service_type: "objectstorage"  
       metric_names: ["obj_requests_num"]  
       entity_regions: ["us-lax"]  
       polling_interval: "1m"  
       agg_function: "sum"  
       query_delay: "2m"  
       group_by: ["entity_id"]

Gradually expand the configuration to include additional services based on your monitoring requirements.

Step 3: Run the collector

Run the collector as a Linux binary, Docker image, or Helm chart for Kubernetes environments. For more information about these deployment options and related instructions, see Deployment methods.

📘

Continuous collection

For production deployment, run the collector continuously rather than as short-lived scheduled processes. Continuous operation helps ensure complete metric coverage, particularly for metrics with longer scrape intervals and workloads that generate metric data infrequently.

Step 4: Verify collector health

After deploying the collector, verify that it’s running and healthy. The OpenTelemetry Collector includes a health check extension that exposes a health check endpoint for monitoring collector liveness and readiness. This endpoint is especially useful in containerized or orchestrated environments like Docker and Kubernetes.

Add the health check extension to the extensions section of your configuration file:

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

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

curl http://localhost:8888/health

A healthy collector returns am HTTP 200 OK {"status": "healthy"} response.

If the collector is not ready or has encountered an error, the health check endpoint returns an HTTP 500 response. You can troubleshoot this response by:

• Confirming the collector process is running
• Verifying that the health_check extension is configured correctly
• Verifying that the configured port is not blocked by a firewall
• Verifying that the configured port is not already in use by another process

Step 5: Verify metrics collection and export

After verifying the collector is healthy, use the following methods to confirm that metrics are being collected and exported successfully.

Review collector logs

By default, the collector writes logs to standard output (stdout). The collector configuration doesn’t include a setting for specifying a log file path. To save logs for later analysis, redirect stdout to a file:

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

Configure the collector's telemetry logs by adding the telemetry section to the collector configuration file:

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

Use the debug exporter

Use the debug exporter to print metrics directly to the collector’s console logs. This method is useful for validating collector behavior and troubleshooting pipeline issues without sending data to an external backend.

Add the debug exporter to the exporters section of your configuration file:

exporters:  
  debug:  
    verbosity: detailed

Use the Prometheus exporter

Use the Prometheus exporter to expose metrics on an HTTP endpoint that can be scraped by Prometheus or visualized in Grafana.

Add the Prometheus exporter to the exporters section of your configuration file:

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

After the collector is running, view the raw exported metrics in a browser by visiting the endpoint in a browser or by using curl:

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

Step 6: Visualize metrics

To visualize and analyze metrics, connect your observability platform to the endpoint configured for your OTLP/HTTP or Prometheus exporter.

For example, metrics exposed by the Prometheus exporter can be scraped by Prometheus and visualized in Grafana.

For more information about supported exporters, see Supported components.

📘

Understanding missing metrics

The absence of metrics does not necessarily indicate a collection failure. Missing, delayed, or sparse metrics are often caused by normal service behavior or collection timing. For more information see Understanding missing metrics.