This guide presents troubleshooting strategies for common issues you may encounter while configuring and running the Akamai Distribution of the OpenTelemetry Collector for Akamai Cloud Pulse (the collector).

Configuration issues

• Collector fails to start because of an invalid configuration
• API server rejects a metric query because of an invalid or unsupported parameter in the metric configuration

API communication issues

• HTTP 429 (Too Many Requests)
• HTTP 403 (Forbidden)
• Context deadline exceeded (client timeout)
• No data points available for the requested metric or time range

📘

If your issue isn’t covered here, see the FAQs for answers to commonly asked questions.

Configuration issues

The following issues can occur when configuring the collector or when the Linode API validates the collector configuration at runtime.

Collector fails to start because of an invalid configuration

The collector validates its configuration at startup. If the configuration is invalid, collector startup fails and no metrics are collected.

To resolve this issue:

• Verify that the receiver, processor, and exporter names are spelled correctly.
• Verify that referenced component types are supported and included in your collector build.
• Ensure all required parameters are present in the receiver configuration.
• Check the collector configuration file for YAML syntax or indentation errors.
• Correct any configuration errors before restarting the collector.

API server rejects a metric query because of an invalid or unsupported parameter in the metric configuration

The collector starts successfully and the collector configuration file is syntactically valid. The Linode API validates the metric parameters at runtime and rejects the query if one or more parameter values are invalid, unsupported, or outside the accepted range for a given metric.

To resolve the issue:

• Review the error message to identify the offending parameter.
• Use the List metrics for a service type API operation to verify that the parameter value is supported for the configured metric and is within the accepted range.
• Correct the invalid parameter value in the collector configuration file.
• Redeploy the collector.

The following table lists common invalid parameter values and what to check when resolving the error.

API communication issues

The following issues can occur while the collector communicates with the Linode API.

HTTP 429 (Too Many Requests)

The Linode API rejected the request because the metrics request rate limit of 100 requests per minute, per service, per user was exceeded.

To resolve this issue, reduce the metrics request rate to stay within the API limit using one or more of the following methods:

• Reduce the thread_pool_size so that the collector processes requests sequentially rather than concurrently. For example, try reducing the thread pool size to 1 or 2.
• Increase the polling_interval to reduce the frequency of API requests. For example, increase the polling interval from 60 seconds to 5 minutes.
• Prioritize metrics so that the collector collects only what you need to monitor. For example, if you have hundreds of Object Storage buckets, configure the collector to collect and export only the most critical metrics, or only the metrics for the most critical regions.
• Distribute requests across multiple users by configuring multiple receivers that use personal access tokens (PATs) generated for different users under the same account.

HTTP 403 (Forbidden)

The Linode API understands the request but refused to authorize it. This can occur when the personal access token (PAT) doesn't have the required permissions, the receiver configuration uses multiple PATs in an unsupported way, or your account doesn't have access to the requested metrics or services.

To resolve the issue:

• Verify that the PAT includes the permissions required to access the requested metrics or services.
• Verify that PATs are configured correctly. Configuring multiple PATs within a single receiver block in an unsupported way can result in this error.
• Ensure your account has permission to access metrics for the requested service. During the limited availability (LA) release, some services require a specific tag on your account before metrics can be accessed. Contact support to request the required access.

Context deadline exceeded (client timeout)

The collector did not receive a response from the Linode API before the configured client timeout expired. This typically occurs when the server takes longer to respond than the client timeout allows, often because it is overloaded. It is often accompanied by HTTP 429 errors.

To resolve this issue:

• Follow the recommendations in HTTP 429 (Too Many Requests) to reduce the request rate and the number of concurrent requests.
• Retry the request after the server has had time to recover.

No data points available for the requested metric or time range

The Linode API returned a successful 200 OK response, but no metric data was available for the configured metric and time range. The collector is running, the configuration is valid, and the query parameters are correct. This is not an error. It indicates that the time series database (TSDB) has no data points available for the requested metric during the specified time range.

Missing metrics can occur for several reasons, including normal service behavior and collection timing. See Understanding missing metrics

To resolve this issue:

• Wait for the next collection cycle to allow time for metric data to be recorded.
• Keep the collector running continuously for the duration of the observability period.
• Increase the query time range to include more than one scrape interval.
• Generate activity on the monitored service so that the configured metric has data to record.