Skip to main content
Version: 2.33 (prerelease)

opentelemetry

OpenTelemetry backend

Backend: pants.backend.observability.opentelemetry

Config section: [opentelemetry]

Basic options​

async_completion​

--[no-]opentelemetry-async-completion
PANTS_OPENTELEMETRY_ASYNC_COMPLETION
pants.toml
[opentelemetry]
async_completion = <bool>
default: False

If True, allows the plugin to finish asynchronously when Pants is shutting down. This can result in faster Pants exit times but may lead to some spans not being exported if the export process is slow. If False, forces synchronous completion, ensuring all spans are exported before Pants exits but potentially slowing down the shutdown process. Defaults to False.

enabled​

--[no-]opentelemetry-enabled
PANTS_OPENTELEMETRY_ENABLED
pants.toml
[opentelemetry]
enabled = <bool>
default: False

Whether to enable emitting OpenTelemetry spans.

exporter​

--opentelemetry-exporter=<TracingExporterId>
PANTS_OPENTELEMETRY_EXPORTER
pants.toml
[opentelemetry]
exporter = <TracingExporterId>
one of: otlp, json-file
default: otlp

Set the exporter to use when exporting workunits to external tracing systems. Choices are otlp (OpenTelemetry OTLP over HTTP), json-file (Write OpenTelemetry-style debug output to a file). Default is otlp.

exporter_endpoint​

--opentelemetry-exporter-endpoint=<str>
PANTS_OPENTELEMETRY_EXPORTER_ENDPOINT
pants.toml
[opentelemetry]
exporter_endpoint = <str>
default: None

The target to which the exporter is going to send traces, metrics, or logs. The endpoint MUST be a valid URL host, and MAY contain a scheme (http or https), port and path. The plugin will construct a "signal-specific" URL for sending traces by appending the applicable URL path if the signal-specific [opentelemetry].exporter_traces_endpoint option is not already set to override this option.

Corresponds to the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

finish_timeout​

--opentelemetry-finish-timeout=<float>
PANTS_OPENTELEMETRY_FINISH_TIMEOUT
pants.toml
[opentelemetry]
finish_timeout = <float>
default: 2.0

The number of seconds to wait at the end of a session for export of all tracing spans to OpenTelemetry to complete.

json_file​

--opentelemetry-json-file=<str>
PANTS_OPENTELEMETRY_JSON_FILE
pants.toml
[opentelemetry]
json_file = <str>
default: dist/otel-json-trace.jsonl

If set, Pants will write OpenTelemetry tracing spans to a local file for easier debugging. Each line will be a tracing span in OpenTelemetry's JSON format. The filename is relative to the build root. Export will only occur if the --opentelemetry-exporter is set to json-file.

parse_traceparent​

--[no-]opentelemetry-parse-traceparent
PANTS_OPENTELEMETRY_PARSE_TRACEPARENT
pants.toml
[opentelemetry]
parse_traceparent = <bool>
default: True

If True, then parse the TRACEPARENT environment variable if it is present in the environment. TRACEPARENT contains the parent trace ID and parent span ID to which to link any trace generated by this plugin. This is useful for linking Pants-related traces together with the trace for the CI job.

The format of the TRACEPARENT environment variable is defined in the W3C Trace Context specification: https://www.w3.org/TR/trace-context/#traceparent-header

--opentelemetry-trace-link-template=<str>
PANTS_OPENTELEMETRY_TRACE_LINK_TEMPLATE
pants.toml
[opentelemetry]
trace_link_template = <str>
default: None

Log a link to the URL at which the trace will be available in a trace management system. The following replacement variables are available:

  • {trace_id} - The OpenTelemetry trace ID

  • {root_span_id} - The span ID of the root span of the trace

  • {trace_start_ms} - Start time of the root span in milliseconds since the UNIX epoch

  • {trace_end_ms} - End time of the root span in milliseconds since the UNIX epoch

Advanced options​

exporter_certificate_file​

--opentelemetry-exporter-certificate-file=<str>
PANTS_OPENTELEMETRY_EXPORTER_CERTIFICATE_FILE
pants.toml
[opentelemetry]
exporter_certificate_file = <str>
default: None

The path to the certificate file for TLS credentials of gRPC client for traces. Should only be used for a secure connection for tracing.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY and OTEL_EXPORTER_OTLP_CERTIFICATE environment variables.

exporter_client_certificate_file​

--opentelemetry-exporter-client-certificate-file=<str>
PANTS_OPENTELEMETRY_EXPORTER_CLIENT_CERTIFICATE_FILE
pants.toml
[opentelemetry]
exporter_client_certificate_file = <str>
default: None

The path to the client certificate/chain trust for clients private key to use in mTLS communication in PEM format for traces.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE and OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE environment variables.

exporter_client_key_file​

--opentelemetry-exporter-client-key-file=<str>
PANTS_OPENTELEMETRY_EXPORTER_CLIENT_KEY_FILE
pants.toml
[opentelemetry]
exporter_client_key_file = <str>
default: None

The path to the client private key to use in mTLS communication in PEM format for traces.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY and OTEL_EXPORTER_OTLP_CLIENT_KEY environment variables.

exporter_compression​

--opentelemetry-exporter-compression=<OtelCompression>
PANTS_OPENTELEMETRY_EXPORTER_COMPRESSION
pants.toml
[opentelemetry]
exporter_compression = <OtelCompression>
one of: gzip, deflate, none
default: none

Specifies a gRPC compression method to be used in the OTLP exporters. Possible values are gzip, deflate, and none.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_COMPRESSION and OTEL_EXPORTER_OTLP_COMPRESSION environment variables.

exporter_headers​

--opentelemetry-exporter-headers="{'key1': val1, 'key2': val2, ...}"
PANTS_OPENTELEMETRY_EXPORTER_HEADERS
pants.toml
[opentelemetry.exporter_headers]
key1 = val1
key2 = val2
...
default: {}

The key-value pairs to be used as headers for spans associated with gRPC or HTTP requests.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_HEADERS and OTEL_EXPORTER_OTLP_HEADERS environment variables.

exporter_timeout​

--opentelemetry-exporter-timeout=<int>
PANTS_OPENTELEMETRY_EXPORTER_TIMEOUT
pants.toml
[opentelemetry]
exporter_timeout = <int>
default: None

The maximum time the OTLP exporter will wait for each batch export for spans.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_TIMEOUT and OTEL_EXPORTER_OTLP_TIMEOUT environment variables.

exporter_traces_endpoint​

--opentelemetry-exporter-traces-endpoint=<str>
PANTS_OPENTELEMETRY_EXPORTER_TRACES_ENDPOINT
pants.toml
[opentelemetry]
exporter_traces_endpoint = <str>
default: None

The target to which the exporter is going to send traces. The endpoint MUST be a valid URL host, and MAY contain a scheme (http or https), port and path. If this option is set, then the [opentelemetry].exporter_endpoint option will not be used. The URL is not modified at all since it is specific to the traces endpoint to use.

You should not normally need to set this option. Prefer using the [opentelemetry].exporter_endpoint option instead.

Corresponds to the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT.

Deprecated options​

None

None