OpenTelemetry for CI/CD
CircleCI supports sending OpenTelemetry spans for your pipelines as they execute. CircleCI emits spans for pipelines, workflows, jobs, tasks, and steps allowing you to understand and visualise the behavior of your pipelines.
Configure OpenTelemetry export via the UI
Complete the following steps to configure CircleCI to send OpenTelemetry spans to the collector of your choice.
-
Log in to the CircleCI web app
-
Select your organization.
-
Open Org from the sidebar.
-
In the organization settings sidebar, click OpenTelemetry Configuration
-
Select Add exporter
-
Complete the fields.
-
Endpoint: The hostname and port for your OTLP collector, for example
otel.example.com:4317. -
Protocol: Either
grpcorhttp. -
Use insecure connection: Only enable this switch if your collector is incapable of TLS.
-
Additional Headers: If your collector needs additional headers with each request add it here. For example, for Honeycomb you must add an
x-honeycomb-teamheader with your Honeycomb API key as the value.
-
-
Select Add exporter to save the new exporter.
Configure OpenTelemetry export via the API
The API has the following endpoints. All endpoints require organization admin privileges.
-
GET /api/v2/otel/exporters?org-id=…- List the exporter configurations for the given organization ID. -
POST /api/v2/otel/exporters- Add an exporter configuration. -
DELETE /api/v2/otel/exporters/:id- Delete an exporter configuration.
Example setup for exporting to Honeycomb
You need three things:
-
A CircleCI personal API token belonging to an organization admin.
-
The CircleCI organization ID.
-
A Honeycomb API token.
Then run this command, substituting your own values:
$ curl -sH "Circle-Token: <CircleCI Token>" -X POST -d '{"org_id": "<CircleCI org ID>", "endpoint": "api.honeycomb.io:443", "protocol": "grpc", "headers": {"x-honeycomb-team": "<Honeycomb API token>"}}' 'https://circleci.com/api/v2/otel/exporters'|
Enterprise and IP-restricted endpoints If your OpenTelemetry endpoint restricts IP access (Grafana and Prometheus are
common examples), you need to allow-list CircleCI’s core service IP ranges.
CircleCI sends spans from its core services, not from job executors, so you do
not need to enable the See IP Ranges for the full list and more details. |
Mapping of CircleCI primitives to OpenTelemetry spans
The following describes the span data emitted for each CircleCI primitive. Span data follows OpenTelemetry semantic conventions where possible.
Pipeline
The span name is Pipeline: {cicd.pipeline.name}. This deviates from the
OpenTelemetry semantic conventions that specify
{cicd.pipeline.action.name} {cicd.pipeline.name}.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
The value is always |
|
Integration |
The name of the pipeline. GitHub OAuth pipelines use the project name. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
executing |
The value is always |
|
https://app.circleci.com/pipeline/f74a9582-9dd4-4b89-8801-4357de39ca5f |
A URL that redirects to the pipeline page in the web UI. |
|
cb53b18d-7379-42ff-915f-29b6f3b86187 |
The ID of the CircleCI organization in which this ran. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The
CircleCI pipeline ID. This is the same value as |
|
42 |
The CircleCI pipeline number. |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
CircleCI Pipelines |
Always |
|
42 |
The GitHub pull request number. Only present for pipelines triggered by a pull request. |
|
open |
The state of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
Fix the thing |
The title of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
|
This shows the Git repo provider in cases
where the pipeline relates to a Git event. Possible values are |
|
main |
For PR pipelines, this is the name of the ref the PR is merging into. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines, this is the name of the ref the PR is merging from. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
2fe3ff8ff80a45f9cbd8bcc14c774a1d3ac588e4 |
The Git SHA for the head ref. |
|
branch |
Either |
|
my-repo |
The name of the VCS repository, derived from the last path segment of the repository URL. |
|
The URL for the VCS repository. |
Workflow
The span name is Workflow: {workflow name}, deviating from the
OpenTelemetry semantic conventions that specify
{cicd.pipeline.action.name} {cicd.pipeline.name}.
In OpenTelemetry semantic conventions, the workflow maps to a “pipeline run”.
As a result, cicd.pipeline.run.id and cicd.pipeline.run.url.full contain
the workflow ID and URL, not the pipeline ID.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
The value is always |
|
build-and-test |
The name of the workflow. |
|
success |
The result of the workflow according to
OpenTelemetry semantic conventions. Possible values are |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
executing |
The value is always |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL that redirects to the workflow page in the web UI. |
|
cb53b18d-7379-42ff-915f-29b6f3b86187 |
The ID of the CircleCI organization in which this ran. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
3 |
The CircleCI pipeline number. |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
false |
Whether this workflow is a rerun of a previous workflow. True for auto-reruns and manual reruns. |
|
auto-rerun |
The reason for a rerun. Only
present when |
|
false |
Whether this is a setup workflow. |
|
success |
The status of the workflow in CircleCI. |
|
failed |
The workflow status when it represents an error
condition. Only present for statuses that map to a |
|
CircleCI Pipelines |
Always |
|
42 |
The GitHub pull request number. Only present for pipelines triggered by a pull request. |
|
open |
The state of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
Fix the thing |
The title of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
|
This shows the Git repo provider in cases
where the pipeline relates to a Git event. Possible values are |
|
main |
For PR pipelines, this is the name of the ref the PR is merging into. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines, this is the name of the ref the PR is merging from. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
2fe3ff8ff80a45f9cbd8bcc14c774a1d3ac588e4 |
The Git SHA for the head ref. |
|
branch |
Either |
|
my-repo |
The name of the VCS repository, derived from the last path segment of the repository URL. |
|
The URL for the VCS repository. |
Job
The span name is Job: {job name}, deviating from the OpenTelemetry
semantic conventions that specify {cicd.pipeline.action.name}
{cicd.pipeline.name}.
In OpenTelemetry semantic conventions, the job maps to a “pipeline task” and
the containing workflow maps to the “pipeline run”. As a result,
cicd.pipeline.name and cicd.pipeline.run.id contain the workflow name and
ID respectively.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
The value is always |
|
build-and-test |
The name of the workflow that contains this job. |
|
success |
The result of the workflow according to
OpenTelemetry semantic conventions. Possible values are |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
executing |
The value is always |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL that redirects to the workflow page in the web UI. |
|
build |
The name of the job. |
|
cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
The CircleCI job ID. |
|
success |
The result of the job according
to OpenTelemetry semantic conventions. Possible values are |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f/job/cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
A URL that redirects to the job page in the web UI. |
|
build |
The CircleCI job type, for example |
|
cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
The CircleCI job ID. |
|
build |
The name of the job. |
|
123 |
The CircleCI job number. |
|
success |
The status of the job in CircleCI. |
|
build |
The CircleCI job type, for example |
|
cb53b18d-7379-42ff-915f-29b6f3b86187 |
The ID of the CircleCI organization in which this ran. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
build-and-test |
The name of the workflow that contains this job. |
|
success |
The status of the workflow in CircleCI. |
|
failed |
The job status when it represents an error
condition. Only present for statuses that map to a |
|
CircleCI Pipelines |
Always |
|
42 |
The GitHub pull request number. Only present for pipelines triggered by a pull request. |
|
open |
The state of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
Fix the thing |
The title of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
|
This shows the Git repo provider in cases
where the pipeline relates to a Git event. Possible values are |
|
main |
For PR pipelines, this is the name of the ref the PR is merging into. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines, this is the name of the ref the PR is merging from. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
2fe3ff8ff80a45f9cbd8bcc14c774a1d3ac588e4 |
The Git SHA for the head ref. |
|
branch |
Either |
|
my-repo |
The name of the VCS repository, derived from the last path segment of the repository URL. |
|
The URL for the VCS repository. |
Task
A task is one parallel run within a job. For jobs with parallelism=1, there is a single task with index 0.
The span name is Task: {job name} - {task index} (for example, Task:
build - 0), deviating from the OpenTelemetry semantic conventions that specify
{cicd.pipeline.action.name} {cicd.pipeline.task.name}.
In OpenTelemetry semantic conventions, the task maps to a “pipeline task” and
the containing workflow maps to the “pipeline run”. As a result,
cicd.pipeline.name and cicd.pipeline.run.id contain the workflow name and
ID respectively.
The cicd.pipeline.task.run.id is a synthetic UUID derived from the job ID
and task index, not a first-class CircleCI identifier.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
The value is always |
|
build-and-test |
The name of the workflow that contains this task. |
|
success |
The result of the workflow according to
OpenTelemetry semantic conventions. Possible values are |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
executing |
The value is always |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL that redirects to the workflow page in the web UI. |
|
build - 0 |
The name of the task, in the form
|
|
3c4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f80 |
An ID for the task. Note this is not the internal CircleCI ID for the task. |
|
success |
The result of the task
according to OpenTelemetry semantic conventions. Possible values are
|
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f/job/3c4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f80 |
A URL for the job page for the job containing this task. |
|
build |
The CircleCI job type. For tasks, this is
always |
|
cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
The CircleCI job ID. |
|
build |
The name of the job. |
|
123 |
The CircleCI job number. |
|
success |
The status of the job in CircleCI. |
|
build |
The CircleCI job type. For tasks, this is
always |
|
cb53b18d-7379-42ff-915f-29b6f3b86187 |
The ID of the CircleCI organization in which this ran. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
medium |
The resource class used. |
|
2 |
The number of vCPUs allocated. |
|
|
The executor type. |
|
|
The Docker image used, if applicable. |
|
Medium |
The human-readable name of the resource class. |
|
4096 |
The amount of RAM allocated in MB. |
|
0 |
The zero-based index of this task within its parallel job. |
|
SUCCEEDED |
The raw result string from the task runner. Only present when the task has completed. |
|
COMPLETED |
The raw state string from the task runner. |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
build-and-test |
The name of the workflow that contains this task. |
|
success |
The status of the workflow in CircleCI. |
|
FAILED |
The task result when it represents an error
condition. Only present for results that map to a |
|
CircleCI Pipelines |
Always |
|
42 |
The GitHub pull request number. Only present for pipelines triggered by a pull request. |
|
open |
The state of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
Fix the thing |
The title of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
|
This shows the Git repo provider in cases
where the pipeline relates to a Git event. Possible values are |
|
main |
For PR pipelines, this is the name of the ref the PR is merging into. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines, this is the name of the ref the PR is merging from. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
2fe3ff8ff80a45f9cbd8bcc14c774a1d3ac588e4 |
The Git SHA for the head ref. |
|
branch |
Either |
|
my-repo |
The name of the VCS repository, derived from the last path segment of the repository URL. |
|
The URL for the VCS repository. |
Step
A step is one step within a task. Each task may contain multiple steps.
The span name is Step: {step name} (for example, Step: Checkout code),
deviating from the OpenTelemetry semantic conventions that specify
{cicd.pipeline.action.name} {cicd.pipeline.name}.
In OpenTelemetry semantic conventions, the step maps to a “pipeline task” and
the containing workflow maps to the “pipeline run”. As a result,
cicd.pipeline.name and cicd.pipeline.run.id contain the workflow name and
ID respectively. The cicd.pipeline.task.run.id is the job ID rather than a
step-specific identifier.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
The value is always |
|
build-and-test |
The name of the workflow that contains this step. |
|
success |
The result of the workflow according to
OpenTelemetry semantic conventions. Possible values are |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
executing |
The value is always |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL that redirects to the workflow page in the web UI. |
|
Checkout code |
The name of the step. |
|
cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
The CircleCI job ID. |
|
success |
The result of the step
according to OpenTelemetry semantic conventions. Possible values are
|
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f/job/cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
A URL that redirects to the job page in the web UI. |
|
checkout |
The step type, for example
|
|
cbf6a4ea-a078-4d72-8641-cb5ec149fc35 |
The CircleCI job ID. |
|
build |
The name of the job that contains this step. |
|
123 |
The CircleCI job number. |
|
success |
The status of the job in CircleCI. |
|
build |
The CircleCI job type, for example
|
|
cb53b18d-7379-42ff-915f-29b6f3b86187 |
The ID of the CircleCI organization in which this ran. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
medium |
The resource class used. |
|
2 |
The number of vCPUs allocated. |
|
|
The executor type. |
|
cimg/base:2024.01 |
The Docker image used, if applicable. |
|
Medium |
The human-readable name of the resource class. |
|
4096 |
The amount of RAM allocated in MB. |
|
0 |
The number of seconds to wait before auto-rerunning this step. Zero if auto-rerun is not configured. |
|
0 |
The current auto-rerun attempt number for this step. Zero if auto-rerun is not configured for this step. |
|
false |
Whether this step runs in the background. For example, this is true for steps used to spin up secondary service containers. |
|
echo hello |
The command run by the step, if applicable. |
|
0 |
The exit code of the step command. |
|
false |
Steps marked as insignificant do not affect the success of the job. |
|
0 |
The maximum number of auto-reruns configured for this step. Zero if auto-rerun is not configured. |
|
false |
Whether this step runs in parallel with other steps in the job. |
|
0 |
The zero-based index of the task this step belongs to. |
|
SUCCEEDED |
The raw result string of the containing task. |
|
COMPLETED |
The raw state string of the containing task. |
|
ff87d6e9-6f8c-40d8-aa37-4be96218709f |
The CircleCI workflow ID. |
|
build-and-test |
The name of the workflow that contains this step. |
|
success |
The status of the workflow in CircleCI. |
|
FAILED |
The task result when it represents an error
condition. Only present for steps that have a result of |
|
CircleCI Pipelines |
Always |
|
42 |
The GitHub pull request number. Only present for pipelines triggered by a pull request. |
|
open |
The state of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
Fix the thing |
The title of the GitHub pull request. Only present for pipelines triggered by a pull request. |
|
|
This shows the Git repo provider in cases
where the pipeline relates to a Git event. Possible values are |
|
main |
For PR pipelines, this is the name of the ref the PR is merging into. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines, this is the name of the ref the PR is merging from. For branch pipelines, this is the branch name. For tag pipelines, this is the tag name. |
|
2fe3ff8ff80a45f9cbd8bcc14c774a1d3ac588e4 |
The Git SHA for the head ref. |
|
branch |
Either |
|
my-repo |
The name of the VCS repository, derived from the last path segment of the repository URL. |
|
The URL for the VCS repository. |