26751910360

Committed 01 Jun 2026 11:24AM UTC coverage: 52.046% (-40.7%) from 92.792%

Build # 26751910360

Build Type

Pull #23395

github

Committed by

web-flow

Commit Message

Merge 41608d741 into c8127c1f4

Pull Request Pull Request #23395: Bump the gha-deps group with 8 updates

Coverage Stats

31994 of 61473 relevant lines covered (52.05%)

1.04 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/src/python/pants/backend/observability/opentelemetry/subsystem.py

# Copyright 2026 Pants project contributors (see CONTRIBUTORS.md).
# Licensed under the Apache License, Version 2.0 (see LICENSE).

import enum

from pants.option.option_types import (
    BoolOption,
    DictOption,
    EnumOption,
    FloatOption,
    IntOption,
    StrOption,
)
from pants.option.subsystem import Subsystem
from pants.util.strutil import softwrap


class TracingExporterId(enum.Enum):
    OTLP = "otlp"
    JSON_FILE = "json-file"


class OtelCompression(enum.Enum):
    GZIP = "gzip"
    DEFLATE = "deflate"
    NONE = "none"


class TelemetrySubsystem(Subsystem):
    options_scope = "opentelemetry"
    help = "OpenTelemetry backend"

    enabled = BoolOption(default=False, help="Whether to enable emitting OpenTelemetry spans.")

    exporter = EnumOption(
        default=TracingExporterId.OTLP,
        help=softwrap(
            f"""
            Set the exporter to use when exporting workunits to external tracing systems. Choices are
            `{TracingExporterId.OTLP.value}` (OpenTelemetry OTLP over HTTP),
            `{TracingExporterId.JSON_FILE.value}` (Write OpenTelemetry-style debug output to a file).
            Default is `{TracingExporterId.OTLP.value}`.
            """
        ),
    )

    finish_timeout = FloatOption(
        default=2.0,
        help=softwrap(
            """
            The number of seconds to wait at the end of a session for export of all tracing spans to OpenTelemetry
            to complete.
            """
        ),
    )

    parse_traceparent = BoolOption(
        default=True,
        help=softwrap(
            """
            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
            """
        ),
    )

    async_completion = BoolOption(
        default=False,
        help=softwrap(
            """
            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`.
            """
        ),
    )

    json_file = StrOption(
        default="dist/otel-json-trace.jsonl",
        help=softwrap(
            f"""
            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 `{TracingExporterId.JSON_FILE.value}`.
            """
        ),
    )

    trace_link_template = StrOption(
        default=None,
        help=softwrap(
            """
            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
            """
        ),
    )

    exporter_endpoint = StrOption(
        default=None,
        help=softwrap(
            """
            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.
            """
        ),
    )

    exporter_traces_endpoint = StrOption(
        default=None,
        advanced=True,
        help=softwrap(
            """
            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`.
            """
        ),
    )

    exporter_certificate_file = StrOption(
        default=None,
        advanced=True,
        help=softwrap(
            """
            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_key_file = StrOption(
        default=None,
        advanced=True,
        help=softwrap(
            """
            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_client_certificate_file = StrOption(
        default=None,
        advanced=True,
        help=softwrap(
            """
            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_headers = DictOption[str](
        advanced=True,
        help=softwrap(
            """
            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 = IntOption(
        default=None,
        advanced=True,
        help=softwrap(
            """
            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_compression = EnumOption(
        default=OtelCompression.NONE,
        advanced=True,
        help=softwrap(
            """
            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.
            """
        ),
    )

1	# Copyright 2026 Pants project contributors (see CONTRIBUTORS.md).
2	# Licensed under the Apache License, Version 2.0 (see LICENSE).
3
4	import enum	×
5
6	from pants.option.option_types import (	×
7	BoolOption,
8	DictOption,
9	EnumOption,
10	FloatOption,
11	IntOption,
12	StrOption,
13	)
14	from pants.option.subsystem import Subsystem	×
15	from pants.util.strutil import softwrap	×
16
17
18	class TracingExporterId(enum.Enum):	×
19	OTLP = "otlp"	×
20	JSON_FILE = "json-file"	×
21
22
23	class OtelCompression(enum.Enum):	×
24	GZIP = "gzip"	×
25	DEFLATE = "deflate"	×
26	NONE = "none"	×
27
28
29	class TelemetrySubsystem(Subsystem):	×
30	options_scope = "opentelemetry"	×
31	help = "OpenTelemetry backend"	×
32
33	enabled = BoolOption(default=False, help="Whether to enable emitting OpenTelemetry spans.")	×
34
35	exporter = EnumOption(	×
36	default=TracingExporterId.OTLP,
37	help=softwrap(
38	f"""
39	Set the exporter to use when exporting workunits to external tracing systems. Choices are
40	`{TracingExporterId.OTLP.value}` (OpenTelemetry OTLP over HTTP),
41	`{TracingExporterId.JSON_FILE.value}` (Write OpenTelemetry-style debug output to a file).
42	Default is `{TracingExporterId.OTLP.value}`.
43	"""
44	),
45	)
46
47	finish_timeout = FloatOption(	×
48	default=2.0,
49	help=softwrap(
50	"""
51	The number of seconds to wait at the end of a session for export of all tracing spans to OpenTelemetry
52	to complete.
53	"""
54	),
55	)
56
57	parse_traceparent = BoolOption(	×
58	default=True,
59	help=softwrap(
60	"""
61	If `True`, then parse the `TRACEPARENT` environment variable if it is present in the environment.
62	`TRACEPARENT` contains the parent trace ID and parent span ID to which to link any trace generated by
63	this plugin. This is useful for linking Pants-related traces together with the trace for the CI job.
64
65	The format of the `TRACEPARENT` environment variable is defined in the W3C Trace Context specification:
66	https://www.w3.org/TR/trace-context/#traceparent-header
67	"""
68	),
69	)
70
71	async_completion = BoolOption(	×
72	default=False,
73	help=softwrap(
74	"""
75	If `True`, allows the plugin to finish asynchronously when Pants is shutting down. This can result in
76	faster Pants exit times but may lead to some spans not being exported if the export process is slow.
77	If `False`, forces synchronous completion, ensuring all spans are exported before Pants exits but
78	potentially slowing down the shutdown process. Defaults to `False`.
79	"""
80	),
81	)
82
83	json_file = StrOption(	×
84	default="dist/otel-json-trace.jsonl",
85	help=softwrap(
86	f"""
87	If set, Pants will write OpenTelemetry tracing spans to a local file for easier debugging. Each line
88	will be a tracing span in OpenTelemetry's JSON format. The filename is relative to the build root. Export
89	will only occur if the `--opentelemetry-exporter` is set to `{TracingExporterId.JSON_FILE.value}`.
90	"""
91	),
92	)
93
94	trace_link_template = StrOption(	×
95	default=None,
96	help=softwrap(
97	"""
98	Log a link to the URL at which the trace will be available in a trace management system. The following
99	replacement variables are available:
100
101	- `{trace_id}` - The OpenTelemetry trace ID
102
103	- `{root_span_id}` - The span ID of the root span of the trace
104
105	- `{trace_start_ms}` - Start time of the root span in milliseconds since the UNIX epoch
106
107	- `{trace_end_ms}` - End time of the root span in milliseconds since the UNIX epoch
108	"""
109	),
110	)
111
112	exporter_endpoint = StrOption(	×
113	default=None,
114	help=softwrap(
115	"""
116	The target to which the exporter is going to send traces, metrics, or logs. The endpoint MUST be a valid URL host,
117	and MAY contain a scheme (http or https), port and path. The plugin will construct a "signal-specific" URL for
118	sending traces by appending the applicable URL path if the signal-specific `[opentelemetry].exporter_traces_endpoint`
119	option is not already set to override this option.
120
121	Corresponds to the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable.
122	"""
123	),
124	)
125
126	exporter_traces_endpoint = StrOption(	×
127	default=None,
128	advanced=True,
129	help=softwrap(
130	"""
131	The target to which the exporter is going to send traces. The endpoint MUST be a valid URL host,
132	and MAY contain a scheme (http or https), port and path. If this option is set, then the
133	`[opentelemetry].exporter_endpoint` option will not be used. The URL is not modified
134	at all since it is specific to the traces endpoint to use.
135
136	You should not normally need to set this option. Prefer using the `[opentelemetry].exporter_endpoint`
137	option instead.
138
139	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`.
140	"""
141	),
142	)
143
144	exporter_certificate_file = StrOption(	×
145	default=None,
146	advanced=True,
147	help=softwrap(
148	"""
149	The path to the certificate file for TLS credentials of gRPC client for traces.
150	Should only be used for a secure connection for tracing.
151
152	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY` and `OTEL_EXPORTER_OTLP_CERTIFICATE`
153	environment variables.
154	"""
155	),
156	)
157
158	exporter_client_key_file = StrOption(	×
159	default=None,
160	advanced=True,
161	help=softwrap(
162	"""
163	The path to the client private key to use in mTLS communication in PEM format for traces.
164
165	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY` and `OTEL_EXPORTER_OTLP_CLIENT_KEY`
166	environment variables.
167	"""
168	),
169	)
170
171	exporter_client_certificate_file = StrOption(	×
172	default=None,
173	advanced=True,
174	help=softwrap(
175	"""
176	The path to the client certificate/chain trust for clients private key to use in mTLS
177	communication in PEM format for traces.
178
179	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE` and
180	`OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` environment variables.
181	"""
182	),
183	)
184
185	exporter_headers = DictOption[str](	×
186	advanced=True,
187	help=softwrap(
188	"""
189	The key-value pairs to be used as headers for spans associated with gRPC or HTTP requests.
190
191	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_HEADERS` and `OTEL_EXPORTER_OTLP_HEADERS`
192	environment variables.
193	"""
194	),
195	)
196
197	exporter_timeout = IntOption(	×
198	default=None,
199	advanced=True,
200	help=softwrap(
201	"""
202	The maximum time the OTLP exporter will wait for each batch export for spans.
203
204	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` and `OTEL_EXPORTER_OTLP_TIMEOUT`
205	environment variables.
206	"""
207	),
208	)
209
210	exporter_compression = EnumOption(	×
211	default=OtelCompression.NONE,
212	advanced=True,
213	help=softwrap(
214	"""
215	Specifies a gRPC compression method to be used in the OTLP exporters. Possible values are `gzip`,
216	`deflate`, and `none`.
217
218	Corresponds to the `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` and `OTEL_EXPORTER_OTLP_COMPRESSION`
219	environment variables.
220	"""
221	),
222	)

pantsbuild / pants / 26751910360

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous