Table of contents

Ingesting traces into Checkly with the OpenTelemetry collector

Using the OpenTelemetry collector is the best way to manage and route telemetry data from / to Checkly. It requires a little setting up, but it’s worth it.

In this guide we assume you already have an OTel collector running and configured. If you don’t, please reference the Open Telemetry Collector getting started documentation

Sending trace to Checkly is very simple with the OpenTelemetry collector. There are three sections you need to add to your collector configuration file:

1. Create a filter that will remove all spans that don’t have checkly=true in the trace state.
2. Create a new exporter with the Checkly API endpoint and API key as environment variables.
3. Hook the exporter and filter into a new trace pipeline.

receivers:
  otlp:
    protocols:
      http:

processors:
  batch:
  filter/checkly:
    error_mode: ignore
    traces:
      span:
        # remove all spans that the trace state doesn't have an object
        # which key is "tracetest" and value is "true"
        - 'trace_state["checkly"] != "true"'

exporters:
  otlp/checkly:
    endpoint: "${env:CHECKLY_OTEL_API_ENDPOINT}"
    headers:
      authorization: "Bearer ${env:CHECKLY_OTEL_API_KEY}"
      "Content-Type": "application/json"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [filter/checkly, batch]
      exporters: [otlp/checkly]

Grab your OTel API key in the Send traces section of the Open Telemetry Integration page in the Checkly app.
Now, export your API key in your shell by setting the CHECKLY_OTEL_API_KEY environment variable.

export CHECKLY_OTEL_API_KEY="<your-api-key>"

Next, export the endpoint for the region you want to use:

export CHECKLY_OTEL_API_ENDPOINT="https://otel.eu-west-1.checklyhq.com"

Now, restart your collector with the updated configuration file. If you are using a Dockerized version of the OTel collector, don’t forget to pass in the environment variables, e.g.

docker run \
-e CHECKLY_OTEL_API_KEY \
-e CHECKLY_OTEL_API_ENDPOINT \
...

You are done. Any traces ingested by your collector that are triggered by a Checkly synthetic check will now be sent to Checkly via the new pipeline.

Getting started with OpenTelemetry How Checkly tracing works under the hood

Last updated on May 14, 2024. You can contribute to this documentation by editing this page on Github