OpenTelemetry for CI/CD
CircleCI supports sending OpenTelemetry spans for your pipelines as they execute. Spans are emitted for pipelines, workflows, jobs, tasks, and steps allowing you to understand and visualise the behavior of your pipelines.
Configure OpenTelemetry export via the API
The API has the following endpoints, all of which 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'Mapping of CircleCI primitives to OpenTelemetry spans
The following is a description of the span data emitted for each of the following CircleCI primitives. Where possible we have tried to make this compatible with the OpenTelemetry semantic conventions but this has not always been possible.
Pipeline
The name of the span will be Pipeline: {cicd.pipeline.name} which is a
deviation from the OpenTelemetry semantic conventions which specifies
{cicd.pipeline.action.name} {cicd.pipeline.name}.
The span attributes are as follows:
| Trace Attribute | Example Value | Description |
|---|---|---|
|
RUN |
It will always be |
|
Integration |
The name of the pipeline. For GitHub OAuth pipelines this will be the name of the project. |
|
f74a9582-9dd4-4b89-8801-4357de39ca5f |
The CircleCI pipeline ID. |
|
executing |
It will always be |
|
https://app.circleci.com/pipeline/f74a9582-9dd4-4b89-8801-4357de39ca5f |
A URL which will redirect you to the page in the web UI for the pipeline. |
|
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 |
|
96781ce1-9288-4d06-89e6-62fc620117db |
The ID of the CircleCI project in which this ran. |
|
CircleCI Pipelines |
This will always be
|
|
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. |
|
|
If the pipeline was generated in connection
with a Git repo this shows the provider of the Git repo. Possible values
are |
|
main |
For PR pipelines this will be the name of the ref the PR is merging into. For branch pipelines this will be the branch name. For tag pipelines this will be the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines this will be the name of the ref the PR is merging from. For branch pipelines this will be the branch name. For tag pipelines this will be 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. |
|
https://github.com/my-org/my-repo |
The URL for the VCS repository. |
Workflow
The name of the span will be Workflow: {workflow name} which is a
deviation from the OpenTelemetry semantic conventions which specifies
{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 |
It will always be |
|
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 |
This will always be |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL which will redirect you to the page in the web UI for the workflow. |
|
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. |
|
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 |
This will always be
|
|
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. |
|
|
If the pipeline was generated in connection
with a Git repo this shows the provider of the Git repo. Possible values
are |
|
main |
For PR pipelines this will be the name of the ref the PR is merging into. For branch pipelines this will be the branch name. For tag pipelines this will be the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines this will be the name of the ref the PR is merging from. For branch pipelines this will be the branch name. For tag pipelines this will be 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. |
|
https://github.com/my-org/my-repo |
The URL for the VCS repository. |
Job
The name of the span will be Job: {job name} which is a deviation from
the OpenTelemetry semantic conventions which specifies
{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 |
It will always be |
|
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 |
It will always be |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL which will redirect you to the page in the web UI for the workflow that contains this job. |
|
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 which will redirect you to the page in the web UI for the job. |
|
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 |
This will always be
|
|
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. |
|
|
If the pipeline was generated in connection
with a Git repo this shows the provider of the Git repo. Possible values
are |
|
main |
For PR pipelines this will be the name of the ref the PR is merging into. For branch pipelines this will be the branch name. For tag pipelines this will be the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines this will be the name of the ref the PR is merging from. For branch pipelines this will be the branch name. For tag pipelines this will be 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. |
|
https://github.com/my-org/my-repo |
The URL for the VCS repository. |
Task
A task is one parallel run within a job. For jobs with parallelism=1 there will be a single task with index 0.
The name of the span will be Task: {job name} - {task index} (for
example, Task: build - 0) which is a deviation from the OpenTelemetry
semantic conventions which specifies {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 |
It will always be |
|
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 |
It will always be |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL which will redirect you to the page in the web UI for the workflow that contains this task. |
|
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. This will always
be |
|
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. This will always be
|
|
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 |
This will always be
|
|
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. |
|
|
If the pipeline was generated in connection
with a Git repo this shows the provider of the Git repo. Possible values
are |
|
main |
For PR pipelines this will be the name of the ref the PR is merging into. For branch pipelines this will be the branch name. For tag pipelines this will be the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines this will be the name of the ref the PR is merging from. For branch pipelines this will be the branch name. For tag pipelines this will be 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. |
|
https://github.com/my-org/my-repo |
The URL for the VCS repository. |
Step
A step is one step within a task. Each task may contain multiple steps.
The name of the span will be Step: {step name} (for example, Step:
Checkout code) which is a deviation from the OpenTelemetry semantic
conventions which specifies {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 |
It will always be |
|
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 |
It will always be |
|
https://app.circleci.com/workflow/ff87d6e9-6f8c-40d8-aa37-4be96218709f |
A URL which will redirect you to the page in the web UI for the workflow that contains this step. |
|
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 which will redirect you to the page in the web UI for the job containing this step. |
|
checkout |
The type of the step, 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. |
|
echo hello |
The command run by the step, if applicable. |
|
0 |
The exit code of the step command. |
|
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 |
This will always be
|
|
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. |
|
|
If the pipeline was generated in connection
with a Git repo this shows the provider of the Git repo. Possible values
are |
|
main |
For PR pipelines this will be the name of the ref the PR is merging into. For branch pipelines this will be the branch name. For tag pipelines this will be the tag name. |
|
14c29a1b2454ae4dd966f27e3b46aec7680d8c14 |
The Git SHA for the base ref. |
|
my-feature-branch |
For PR pipelines this will be the name of the ref the PR is merging from. For branch pipelines this will be the branch name. For tag pipelines this will be 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. |
|
https://github.com/my-org/my-repo |
The URL for the VCS repository. |