Akamai Cloud Pulse collects operational metrics for supported Akamai Cloud services and persists them in an Akamai-managed time-series database (TSDB). The Akamai Cloud Pulse receiver (akamaicloudpulsereceiver) queries the API to retrieve these metrics and converts them into OpenTelemetry-compliant metric data for downstream processing and export.

Configure this receiver using the naming conventions and parameters described in the following sections.

Naming conventions

When configuring multiple receiver or service instances, use the following naming conventions. Appending a numeric suffix helps distinguish instances while maintaining a consistent naming pattern.

Receiver names

When defining multiple receivers of the type akamaicloudpulsereceiver, append a numeric suffix to the receiver name, for example, akamaicloudpulsereceiver/1, akamaicloudpulsereceiver/2, akamaicloudpulsereceiver/3, and so on.

Service names

When defining multiple services of the same type within a receiver configuration, append a numeric suffix ti the service name, for example, dbaas/1, dbaas/2, nodebalancer/1, nodebalancer/2, and so on.

Receiver parameters

Configure akamaicloudpulsereceiver in the collector configuration file (config.yaml). You can find sample configuration files for common metrics export scenarios in the GitHub repository.

The following table describes each akamaicloudpulsereceiver parameter, indicates whether it’s required, and identifies whether a service-level override applies.

Parameters marked "Yes" in the "Service-level override" column can be defined at both the receiver and service levels. When a parameter value is defined at both levels, the service-level value overrides the receiver-level value. Parameters marked "No" can only be defined at the receiver level. "N/A" indicates that service-level override doesn’t apply to the parameter.

Parameter considerations

This section provides additional usage guidance for select parameters.

entity_ids and entity_regions

When configuring entity_ids and entity_regions, keep in mind:

• These parameters correspond to different attributes. Use entity_ids to specify the entities for which metrics are collected. Use entity_regions to specify the regions associated with the Object Storage buckets from which metrics are collected.
• Wildcards (*) should be used carefully. You can set entity_ids to “*” to collect metrics for all entities associated with the service rather than a specific set of entities, However, if there are a large number of entities, this can significantly increase the amount of data collected and processed.

polling_interval

When configuring polling_interval, keep in mind that this parameter:

• Controls query frequency. This parameter controls how often the receiver queries the API for metric data.
• Doesn't control metric freshness. A short polling interval does not necessarily result in fresher data. Metric data becomes available according to the backend scrape cadence for each metric, which is independent of the polling interval.
• Can increase API request volume. A short polling interval increases the number of API requests made by the receiver. Depending on the number of metrics and services being collected, aggressive polling can increase the likelihood of encountering rate limits and HTTP 429 errors.
• Should consider API rate limits. Whenever possible, configure global or service-level polling intervals to 300 seconds or greater. Longer polling intervals allow the API rate limit window to reset between collection cycles and can reduce the likelihood of HTTP 429 errors.
• Should consider metric scrape cadence. A short polling interval may result in duplicate data points due to the same data point being retrieved multiple times. Configure polling_interval to match or be a reasonable multiple of the metric scrape cadence.

The backend scrape cadence for a metric is represented by its scrape_interval value. This value indicates how frequently the backend collects data for that metric and cannot be overridden by the receiver. Polling more frequently than the metric’s scrape interval does not result in new data becoming available more quickly.

Some metrics are also inherently sparse. For example, certain Object Storage metrics generate data only when relevant operations occur. As a result, data may not be available for every query interval, even when the receiver is polling successfully.

PAT

When configuring PAT, keep in mind:

• The PAT must include the required permissions. The PAT must be created with the read permission for both Monitor and each supported service being monitored. Missing permissions may prevent the receiver from accessing metric data associated with those services.
• Multiple PATs for the same user don't increase rate-limit capacity. API rate limits apply at the user level, not the token level. Creating or using multiple PATs for the same user does not increase available request capacity or help to avoid HTTP 429 errors. All PATs belonging to the same user share the same rate limit allocation.
• PATs for separate users can increase rate limit capacity. Each user has their own rate-limit allocation. If additional request capacity is required, consider distributing metric collection across multiple PATs belonging to different users within the same account. This can be achieved by configuring multiple receiver instances, each using a PAT from a different user, and partitioning resources across them. Doing so helps balance API traffic and reduces the likelihood of hitting rate limits.

Example:

  akamaicloudpulsereceiver/1:  
    polling_interval: "1m"  
    refresh_interval: "30m"  
    PAT: "<user1-PAT-token>"  
    services:
     - service_type: "dbaas"  
       regions: ["us-iad"]  
       metric_names: ["disk_usage"]  
       agg_function: "min"  
       group_by: ["entity_id"]  
  akamaicloudpulsereceiver/2:  
    services:
      - service_type: "dbaas"  
        PAT: "<user2-PAT-token>"  
        regions : ["us-ord"]  
        metric_names: ["memory_usage"]  
        polling_interval: "1m"  
        agg_function: "min"  
        group_by: ["entity_id"]

query_delay

When configuring query_delay, keep in mind that this parameter:

• Helps avoid missing data in recent query intervals. Metric data is not immediately available after it’s collected. As a result, queries that include the most recent minute may return incomplete results or no data. Query_delay helps account for this latency by shifting the query window backward in time, which allows data to become available before it is queried. For example, if query_delay is set to two minutes, a query that runs at 12:10 retrieves data for a window ending at 12:08.

• Can increase apparent data delay. Larger query_delay values increase the time between when data is collected and when it comes visible through the receiver.

• Requires balancing freshness and completeness. Reducing query_delay can bring data closer to real time, but values that are too low may result in incomplete or missing data if ingestion has not completed.

• Should consider metric scrape intervals. Each metric has a predefined scrape_interval, which can be retrieved using the Linode API.

  Within the receiver, the scrape interval for a metric request is computed as follows:

  If the current time is x and the query delay is set to two minutes, then:

  endTime = x - 2 minutes
  startTime = endTime - polling_interval
  scrape interval = endTime - startTime

  The computed scrape interval is then passed to the Linode API request.

  Ensure that your query_delay and polling_interval values are configured such that the computed scrape interval is greater than or equal to the metric’s predefined scrape_interval. For example, for a metric such as obj_bucket_size, which has a scrape_interval of one hour, configure your polling_interval and query_delay such that the value of the computed scrape interval is greater than or equal to one hour.

thread_pool_size

When configuring thread_pool_size, keep in mind that this parameter:

• Controls concurrent metric collection. This parameter determines how many worker threads can collect metrics simultaneously.
• Requires balancing of collection performance and rate-limit risk. Increasing thread pool size allows more metrics requests to be processed in parallel, which can improve collection performance (throughput). However, large thread pools can also cause more requests to be sent within a short period of time (burstiness), increasing the likelihood of encountering rate limits and HTTP 429 errors.
• Should be sized appropriately for the deployment. Setting the thread pool size higher than what’s needed can generate many concurrent requests and increase the risk of hitting rate limits, without providing meaningful performance benefits.The optimal thread pool size depends on the number of metrics being collected and the rate limits applied to your environment. To help avoid HTTP 429 errors, start with a lower value (1-4) and gradually increase, watching for errors, until you find an appropriate balance between collection performance and rate limit behavior.

group_by

When configuring group_by, keep in mind that this parameter:

• Controls how metric data is grouped. This parameter determines how metric data is grouped before it’s returned. Each additional grouping dimension creates a more detailed view of the data.

• Creates additional metric series. Each unique combination of grouping dimensions produces a separate metric series. Adding more dimensions can significantly increase the number of series returned.

  For example, the following configuration groups metrics by entity_id only and produces one metric series for each entity:
  group_by: ["entity_id"]

  Whereas the following configuration groups metrics by entity_id, request_type, and response_type, and produces a separate metric series for each unique combination of these dimensions.

  YAML

  group_by:
    - "entity_id"
    - "request_type"
    - "response_type" 

  As additional dimensions are added, the number of metric series can increase significantly.

• Can increase memory and storage requirements. Additional metric series require additional memory and storage throughout the pipeline, including the collector and downstream monitoring systems such as Prometheus.

• Can increase processing overhead. A large number of metric series increases the amount of data that must be transferred, processed, and stored. This can increase resource consumption in downstream systems.

• Should be limited to required dimensions. Include only the dimensions needed for monitoring and analysis. Adding unnecessary dimensions can increase the number of metric series without providing additional operational value.

Example configuration

  akamaicloudpulsereceiver/1:
    polling_interval: "1m"
    refresh_interval: "30m"
    PAT: "<your-PAT-token>"
    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"
        regions : ["*"]
        metric_names: ["cpu_usage"]
        polling_interval: "1m"
        PAT : "<your-PAT-token>"
        agg_function: "avg"
        group_by: ["entity_id"]
      - service_type: "nodebalancer"
        metric_names: ["nb_ingress_traffic_rate"]
        polling_interval: "1m"
        refresh_interval: "30m"
        PAT : "<your-PAT-token>"
        agg_function: "sum"
        entity_ids: [12345]
        query_delay: "5m"
        group_by: ["entity_id"]
      - service_type: "objectstorage"
        metric_names: ["obj_requests_rps"]
        polling_interval: "1m"
        refresh_interval: "30m"
        agg_function: "sum"
        PAT : "<your-PAT-token>"
        query_delay: "2m"
        group_by: ["entity_id"]
        filters:
          - dimension_label: "request_type"
            operator: "in"
            value: "list"
        entity_regions : ["us-lax"]
      - service_type: "logs"
        PAT: "<your-PAT-token>"
        entity_ids: ["*"]
        metric_names: ["success_upload_count"]
        agg_function: "sum"
        query_delay: "2m"
        polling_interval: "1m"
        group_by: ["entity_id"]