API reference¶
Generated reference documentation for each package. The pages are rebuilt and published with this
site from main.
| Language | Reference | Generated by |
|---|---|---|
| TypeScript | TypeScript API | TypeDoc |
| Rust | Rust API · docs.rs | rustdoc |
| Go | pkg.go.dev | Go doc comments |
| Python | below | mkdocstrings |
| Java | Java API | Javadoc |
Build them locally with make docs (per language: make -C <lang> docs).
Python¶
Grow Codes SDK for Datadog APM.
Tracing exports OTLP to the Datadog Agent with the OpenTelemetry SDK (:func:init_tracing); the
Datadog propagator, id helpers, log correlation and error attributes make the spans look native in
Datadog; :class:DatadogSpansQuery reads spans back through the Datadog SaaS Spans API.
from grow_datadog_apm import DatadogApmClient, init_tracing client = DatadogApmClient.from_env() # doctest: +SKIP handle = init_tracing(service_name="checkout") # doctest: +SKIP
AgentInfo
dataclass
¶
The Agent's GET /info document (fields this package reads).
from_json
classmethod
¶
Parse a decoded GET /info body (anything that is not an object gives defaults).
AsyncBaseTraceQueryClient ¶
Async :class:BaseTraceQueryClient.
query_trace_id ¶
The id wait_for_trace passes to get_trace; override to keep native ids.
AsyncDatadogApmClient ¶
Asynchronous Datadog APM client; use async with or call :meth:aclose.
Cancel a call by cancelling its task: the SDK raises :class:CancelledError, which is also
an :class:asyncio.CancelledError.
spans
property
¶
The async SaaS spans query API (created on first use, closed by :meth:aclose).
aclose
async
¶
Flush and shut down the tracing handles (in a worker thread), close the query API and release connections (idempotent).
from_env
classmethod
¶
Build an async client from the environment (see :meth:DatadogApmConfig.from_env).
init_tracing ¶
init_tracing(config: TracingConfig | Mapping[str, Any] | None = None, *, span_processors: Sequence[SpanProcessor] = (), **fields: Any) -> DatadogTracingHandle
See :meth:DatadogApmClient.init_tracing (no I/O, so not a coroutine).
AsyncDatadogSpansQuery ¶
Bases: AsyncBaseTraceQueryClient
Asynchronous :class:DatadogSpansQuery (same methods, awaited; :meth:search_spans is an
async iterator). Cancel a call by cancelling its task.
aggregate_spans
async
¶
aggregate_spans(compute: Sequence[SpanCompute | Mapping[str, Any]], group_by: Sequence[SpanGroupBy | Mapping[str, Any]] | None = None, *, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, timezone: str | None = None) -> SpanAggregateResult
See :meth:DatadogSpansQuery.aggregate_spans.
from_env
classmethod
¶
Async query client from the environment (see :meth:DatadogApmConfig.from_env).
get_dependencies
async
¶
get_dependencies(*, start: datetime | None = None, end: datetime | None = None) -> list[DependencyLink]
Always :class:UnsupportedError.
get_trace
async
¶
get_trace(trace_id: str, *, preview: bool = False, from_: DatadogTime | None = None, to: DatadogTime | None = None) -> Trace | None
See :meth:DatadogSpansQuery.get_trace.
list_operations
async
¶
See :meth:DatadogSpansQuery.list_operations.
list_services
async
¶
See :meth:DatadogSpansQuery.list_services.
search_spans
async
¶
search_spans(*, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: SpanSort | None = None, cursor: str | None = None, timezone: str | None = None) -> AsyncIterator[DatadogSpan]
See :meth:DatadogSpansQuery.search_spans (async for).
search_spans_page
async
¶
search_spans_page(*, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: SpanSort | None = None, cursor: str | None = None, timezone: str | None = None) -> DatadogSpansPage
See :meth:DatadogSpansQuery.search_spans_page.
search_traces
async
¶
See :meth:DatadogSpansQuery.search_traces.
wait_for_trace
async
¶
wait_for_trace(trace_id: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = DATADOG_WAIT_INTERVAL_S, min_spans: int = 1) -> Trace
See :meth:DatadogSpansQuery.wait_for_trace.
AsyncHttpTransport ¶
Asynchronous transport (one per async client); options as for :class:HttpTransport.
Cancelling the calling task raises :class:CancelledError (an asyncio.CancelledError
subclass) so asyncio's cancellation machinery keeps working. Every call after
:meth:aclose raises :class:CancelledError ("client is closed").
AsyncTraceQueryClient ¶
Bases: Protocol
Asynchronous trace query API (same methods, awaited).
AuthenticationError ¶
Bases: DatadogApmError
Credentials missing or rejected (HTTP 401).
BaseConfig
dataclass
¶
Common, immutable client settings. Durations are float seconds (timedelta accepted).
Service configs subclass this (@dataclass(frozen=True, repr=False)), override url
with the service default, add their own fields (Secret for credentials), extend
:meth:_env_values and :meth:validate, and list vendor variables in ENV_VENDOR.
BaseTraceQueryClient ¶
Base for service query clients; every method raises UnsupportedError until overridden
(wait_for_trace uses :func:wait_for_trace on top of get_trace, passing the id
through :meth:query_trace_id).
query_trace_id ¶
The id wait_for_trace passes to get_trace; override to keep native ids.
CancelToken ¶
Thread-safe cancellation flag passed to sync calls as cancel=.
Cancelling interrupts an in-flight request (the call returns immediately with
:class:CancelledError; the abandoned HTTP exchange finishes in the background) and any
retry backoff sleep.
CancelledError ¶
Bases: DatadogApmError, CancelledError
The caller cancelled the operation (task cancel, :class:CancelToken, client close).
Also an :class:asyncio.CancelledError so asyncio keeps treating the task as cancelled.
ConfigError ¶
Bases: DatadogApmError
Invalid or missing configuration.
ConflictError ¶
Bases: DatadogApmError
Conflict or failed precondition (HTTP 409, 412, CAS mismatch).
DatadogApmClient ¶
Synchronous Datadog APM client. Thread-safe; use as a context manager or call
:meth:close.
:meth:health, :meth:ping and :meth:server_version use the Datadog Agent's
GET /info; :meth:init_tracing sets up OpenTelemetry exporting to the Agent;
:attr:spans is the SaaS query API (needs api_key + app_key). Every I/O method
accepts cancel= (a :class:CancelToken) to abort from another thread.
client = DatadogApmClient.from_env() # doctest: +SKIP handle = client.init_tracing(service_name="checkout") # doctest: +SKIP client.server_version() # doctest: +SKIP '7.85.4' client.close() # flushes and shuts down the tracing it started # doctest: +SKIP
spans
property
¶
The SaaS spans query API (created on first use, closed by :meth:close).
Raises :class:ConfigError when api_key or app_key is missing.
close ¶
Flush and shut down every tracing handle started with :meth:init_tracing, close the
query API and release connections (idempotent).
from_env
classmethod
¶
Build a client from GROW_DATADOG_APM_* and DD_* variables (see
:meth:DatadogApmConfig.from_env).
health ¶
Agent liveness via GET /info.
healthy with status ok and details version, git_commit when the Agent
answers; unreachable on network errors, unhealthy on HTTP errors (details
httpStatus, error). Raises only :class:CancelledError and
:class:ConfigError.
init_tracing ¶
init_tracing(config: TracingConfig | Mapping[str, Any] | None = None, *, span_processors: Sequence[SpanProcessor] = (), **fields: Any) -> DatadogTracingHandle
:func:~grow_datadog_apm.init_tracing with this client's configuration as the
defaults (Agent host, OTLP endpoint and protocol, service/env/version, tags).
:meth:close shuts the handle down.
ping ¶
Round trip to the Agent (GET /info); returns the latency in milliseconds.
The Agent has no authentication; to check Datadog API credentials use
client.spans.ping().
request ¶
Send a raw request to the Agent (retries, hooks, redaction).
server_version ¶
Datadog Agent version from GET /info (e.g. 7.85.4); :class:UnsupportedError
when the Agent reports none.
DatadogApmConfig
dataclass
¶
Bases: BaseConfig
Immutable settings for :class:~grow_datadog_apm.DatadogApmClient,
:func:~grow_datadog_apm.init_tracing and :class:~grow_datadog_apm.DatadogSpansQuery.
Common fields (url, timeouts, retry, tls, proxy, headers,
user_agent_suffix, hooks, logger) come from :class:BaseConfig; url is the
Datadog Agent's trace intake (GET /info, default http://127.0.0.1:8126). Durations
are float seconds; datetime.timedelta is accepted. api_key / app_key accept a
str and are stored as :class:Secret; repr() never shows them.
The Agent needs no key: the SDK sends OTLP to the Agent, which holds DD_API_KEY.
api_key + app_key are only needed by the SaaS query API
(:class:~grow_datadog_apm.DatadogSpansQuery).
Environment (:meth:from_env; explicit value > GROW_DATADOG_APM_<NAME> > vendor
variables > default):
================ ==========================================================
Field GROW_DATADOG_APM_* → vendor variables
================ ==========================================================
url URL → DD_TRACE_AGENT_URL, else
http://$DD_AGENT_HOST:$DD_TRACE_AGENT_PORT
otlp_endpoint OTLP_HTTP_ENDPOINT / OTLP_GRPC_ENDPOINT (by protocol),
OTLP_ENDPOINT → OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
OTEL_EXPORTER_OTLP_ENDPOINT (+ /v1/traces for HTTP)
protocol OTLP_PROTOCOL → OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
OTEL_EXPORTER_OTLP_PROTOCOL
service_name SERVICE → DD_SERVICE, OTEL_SERVICE_NAME
service_version VERSION → DD_VERSION
environment ENV → DD_ENV
tags TAGS → DD_TAGS (explicit tags are merged over them)
api_key API_KEY → DD_API_KEY
app_key APP_KEY → DD_APP_KEY, DD_APPLICATION_KEY
site SITE → DD_SITE
api_url API_URL
================ ==========================================================
plus the common CONNECT_TIMEOUT, REQUEST_TIMEOUT, TOTAL_TIMEOUT, MAX_RETRIES,
CA_CERT, CLIENT_CERT, CLIENT_KEY, INSECURE_SKIP_VERIFY and PROXY.
api_url defaults to https://api.<site> (computed on construction; pass it again when
you change site with :func:dataclasses.replace).
has_query_credentials
property
¶
True when both the API key and the application key are set.
otlp_traces_endpoint
property
¶
Resolved OTLP traces URL for :attr:protocol (see :func:otlp_traces_url):
:attr:otlp_endpoint when set, else the host of :attr:url with port 4318 +
/v1/traces (HTTP) or port 4317 (gRPC).
from_env
classmethod
¶
Build from the environment (table above), then validate.
env defaults to os.environ; pass a dict in tests. Keyword overrides win over the
environment (None means "not given"); explicit tags are merged over DD_TAGS.
DatadogErrorExporter ¶
Bases: SpanExporter
Wraps a span exporter and fills the Datadog error attributes of every exported span that
has none yet: from its last exception event (exception.type, exception.message,
exception.stacktrace) or, for an ERROR status without an event, error.message from
the status description.
It covers with_span, traced, the HTTP adapters and plain OpenTelemetry
record_exception calls. init_tracing installs it.
DatadogPropagator ¶
Bases: TextMapPropagator
Injects and extracts x-datadog-trace-id (low 64 bits, decimal), x-datadog-parent-id
(decimal), x-datadog-sampling-priority (1/0) and, for 128-bit ids,
x-datadog-tags: _dd.p.tid=<high 64 bits hex>.
Conflict rules on extract (ddtrace's behaviour with style order datadog,tracecontext):
when the carrier also holds a valid traceparent,
- same trace id → the W3C parent id wins (the context from
traceparentis kept), - different trace id → the Datadog context wins and the W3C context is remembered in the
returned context; :class:
DatadogSpanLinkProcessor(installed byinit_tracing) adds it to the next span as a link withreason=terminated_context(see :func:terminated_context_links).
The rules apply whatever position datadog has in the propagator list; put
tracecontext before it (:func:~grow_datadog_apm.order_propagators) so an existing
tracestate is kept.
extract ¶
extract(carrier: CarrierT, context: Context | None = None, getter: Getter[CarrierT] = default_getter) -> otel_context.Context
Read the Datadog headers (with the conflict rules above) into context.
inject ¶
inject(carrier: CarrierT, context: Context | None = None, setter: Setter[CarrierT] = default_setter) -> None
Write the Datadog headers of the span in context; no-op without a valid span.
DatadogQueryWarning
dataclass
¶
A warning attached to a partial query result.
DatadogSpan
dataclass
¶
One span returned by the spans search API.
DatadogSpanLinkProcessor ¶
Bases: SpanProcessor
Adds the :func:terminated_context_links link to the first span started from an extracted
context whose W3C context lost against Datadog headers. init_tracing installs it.
on_start ¶
Add the terminated-context link when the span's remote parent won the conflict.
DatadogSpansPage
dataclass
¶
One page of :meth:DatadogSpansQuery.search_spans_page.
DatadogSpansQuery ¶
Bases: BaseTraceQueryClient
Datadog spans query client (SaaS API at https://api.<site>, headers DD-API-KEY and
DD-APPLICATION-KEY).
Implements the SPEC :class:~grow_datadog_apm.TraceQueryClient on top of the spans search
and aggregate APIs, plus the Datadog-specific :meth:search_spans, :meth:aggregate_spans
and :meth:ping. Thread-safe; use as a context manager or call :meth:close. It raises
:class:ConfigError unless both api_key and app_key are configured.
query = DatadogSpansQuery.from_env() # doctest: +SKIP for item in query.search_spans(query="service:checkout @grow.run:abc"): # doctest: +SKIP ... print(item.span.name, item.span.duration_micros)
aggregate_spans ¶
aggregate_spans(compute: Sequence[SpanCompute | Mapping[str, Any]], group_by: Sequence[SpanGroupBy | Mapping[str, Any]] | None = None, *, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, timezone: str | None = None, cancel: CancelToken | None = None) -> SpanAggregateResult
POST /api/v2/spans/analytics/aggregate: compute (results keyed c0,
c1, …) per group of group_by.
query.aggregate_spans([SpanCompute("pc90", "@duration")], [SpanGroupBy("service")]) ... # doctest: +SKIP
from_env
classmethod
¶
Query client from DD_API_KEY, DD_APP_KEY, DD_SITE, … (see
:meth:DatadogApmConfig.from_env).
get_dependencies ¶
get_dependencies(*, start: datetime | None = None, end: datetime | None = None) -> list[DependencyLink]
Always :class:UnsupportedError: Datadog's public API has no dependency graph.
get_trace ¶
get_trace(trace_id: str, *, preview: bool = False, from_: DatadogTime | None = None, to: DatadogTime | None = None, cancel: CancelToken | None = None) -> Trace | None
Read a trace; None when nothing is found.
Default: search the indexed spans with trace_id:<id> over the last 24 hours
(from_/to change the window; all pages, merged by span id) — only spans kept by
retention filters, so the trace may be partial. preview=True uses the preview
trace-by-id endpoint GET /api/v2/trace/{id} (full trace, x-unstable, 60
requests/minute).
list_operations ¶
Distinct span names (Datadog resource_name) of service in the last 24 hours,
via :meth:aggregate_spans grouped by resource_name (up to 1000), sorted.
list_services ¶
GET /api/v2/apm/services?filter[env]=…: sorted names of the services that reported
traces. env defaults to the configured environment, else * (all).
ping ¶
Authenticated round trip GET /api/v2/validate_keys (API key + application key);
returns the latency in milliseconds. Invalid keys → :class:AuthenticationError
(Datadog answers 401 or 403).
search_spans ¶
search_spans(*, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: SpanSort | None = None, cursor: str | None = None, timezone: str | None = None, cancel: CancelToken | None = None) -> Iterator[DatadogSpan]
Iterate over every matching span, following the cursor page by page.
Arguments as :meth:search_spans_page; the window is fixed (absolute) for all pages.
A Datadog query that timed out without spans raises :class:TimeoutError (never a
silently empty result).
search_spans_page ¶
search_spans_page(*, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: SpanSort | None = None, cursor: str | None = None, timezone: str | None = None, cancel: CancelToken | None = None) -> DatadogSpansPage
One page of POST /api/v2/spans/events/search.
query defaults to *, from_/to to the last 15 minutes, limit to 10
(max 1000), sort to timestamp (oldest first; -timestamp = newest first),
timezone to UTC. Pass next_cursor back as cursor with the same absolute
window for the next page. Status timeout or warnings mark a partial result.
search_traces ¶
search_traces(query: TraceSearchQuery | None = None, *, cancel: CancelToken | None = None) -> list[TraceSummary]
Traces with spans matching query (service, span name, @tag values, duration)
in start..end (default: the last 15 minutes), newest first, up to limit
(default 20) distinct trace ids. Summaries are built from the matching spans only.
wait_for_trace ¶
wait_for_trace(trace_id: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = DATADOG_WAIT_INTERVAL_S, min_spans: int = 1) -> Trace
Poll :meth:get_trace until the trace has min_spans spans (default interval 2 s,
because Datadog allows 50 searches per minute); :class:TimeoutError otherwise.
DatadogTraceId
dataclass
¶
A trace id split the way Datadog stores it.
DatadogTracingHandle ¶
EnvReader ¶
Reads GROW_<KEY_UPPER>_<NAME> and vendor variables from an injectable mapping.
Every getter returns None when no variable is set (empty strings count as unset). A
present but invalid value raises :class:ConfigError that names the variable, never its
value.
ErrorCode ¶
Bases: str, Enum
Canonical error codes; the value is the wire form used by the conformance suite.
ErrorInfo
dataclass
¶
Passed to Hooks.on_error; error is the (redacted) SDK error.
HealthStatus
dataclass
¶
Result of health(); status is ok/degraded/unhealthy/unreachable or a vendor word.
Hooks
dataclass
¶
Optional callbacks invoked on every attempt. Exceptions raised by hooks are ignored.
HttpTransport ¶
Synchronous transport (one per client).
Service options (all optional):
request_id_headers: vendor request id headers, checked before :data:REQUEST_ID_HEADERS.retry_after_headers: headers read (in order) for the delay a 429/503 response asks for; default("retry-after",), e.g.("retry-after", "x-ratelimit-reset"). See :func:retry_after_from_headers.error_mapper:mapper(error, response)returns a service-specific error for an HTTP error response (orNoneto keep the default). The mapped error is whatHooks.on_error, the retry planner (retry_after) and the caller see; whether a status is retried stays the SPEC rule. Exceptions raised by the mapper are logged and ignored.
Every call after :meth:close raises :class:CancelledError ("client is closed").
LoggerLike ¶
Bases: Protocol
Structured logger interface accepted in configuration (SPEC Logger).
NotFoundError ¶
Bases: DatadogApmError
Missing record (HTTP 404).
PermissionDeniedError ¶
Bases: DatadogApmError
Authenticated but not allowed (HTTP 403).
RateLimitError ¶
Bases: DatadogApmError
Too many requests (HTTP 429); retry_after holds the requested delay when known.
Request
dataclass
¶
One logical API call (possibly several attempts).
path is joined to the base URL ({name} style values must already be encoded; use
:func:urllib.parse.quote); an absolute http:///https:// URL is used as is (for
pagination links the service returns; the default headers, config.headers included,
are sent there too, so only pass URLs of the same service). json is encoded when not
None; content sends raw bytes. idempotent overrides the method rule; an
idempotency_key sends the Idempotency-Key header and marks the request idempotent.
raise_for_status=False returns error responses instead of raising (retries still
apply). Statuses in allow_status are expected answers (a 404 that carries data, a
health endpoint's 503): the response is returned at once, like a success, without retries
or on_error.
RequestInfo
dataclass
¶
Passed to Hooks.on_request; url and headers are redacted.
ResourceRegistry ¶
Holds :class:Stoppable objects; :meth:stop_all stops each once, ignoring errors.
register ¶
Track item; when the registry is already closed the item is stopped now.
Response
dataclass
¶
A completed HTTP response (body fully read).
ResponseInfo
dataclass
¶
Passed to Hooks.on_response; headers are the redacted response headers (rate
limit headers and the like stay readable).
RetryPolicy
dataclass
¶
Retry settings. Durations are seconds (datetime.timedelta is accepted).
Backoff for retry n (0-based) is full jitter:
random(0, min(max_backoff, initial_backoff * multiplier ** n)).
random returns a float in [0, 1); inject it in tests for deterministic sleeps.
Secret ¶
Wraps a credential so it never shows up in str/repr/logs.
s = Secret("hunter2") str(s), s.reveal() ('[REDACTED]', 'hunter2')
Span
dataclass
¶
A finished span as returned by a query API.
Ids are normalized on construction (an all-zero or empty parent_span_id becomes
None); a negative duration_micros (the default) is computed from start and end.
A subclass with normalize_ids = False keeps native ids verbatim (an empty
parent_span_id still becomes None); link_class is used by :meth:from_json.
SpanAggregateBucket
dataclass
¶
One bucket of an aggregation.
SpanAggregateResult
dataclass
¶
The result of :meth:DatadogSpansQuery.aggregate_spans.
SpanBatchOptions
dataclass
¶
BatchSpanProcessor settings; durations are float seconds (timedelta accepted).
SpanCompute
dataclass
¶
One computation of :meth:DatadogSpansQuery.aggregate_spans.
SpanGroupBy
dataclass
¶
One group-by facet of :meth:DatadogSpansQuery.aggregate_spans.
SpanGroupBySort
dataclass
¶
Order of the groups of a :class:SpanGroupBy.
SpanHistogram
dataclass
¶
Buckets for a numeric facet.
SpanLink
dataclass
¶
A link to another span. Set normalize_ids = False on a subclass for native ids.
SpanNode
dataclass
¶
A span with its children (sorted like :func:sort_spans).
SpanStatus
dataclass
¶
from_json
classmethod
¶
Parse {"code", "message"?} (a bare code string is accepted too).
SpanTimeseriesPoint
dataclass
¶
A point of a timeseries compute.
TerminatedContext
dataclass
¶
A W3C context that lost against Datadog headers in :meth:DatadogPropagator.extract.
TimeoutError ¶
Bases: DatadogApmError
A connect, request or total deadline was exceeded (also HTTP 408, 504).
TlsConfig
dataclass
¶
TLS settings. insecure_skip_verify is for tests only and logs a warning once.
Trace
dataclass
¶
All spans of one trace, sorted by start time then span id.
A subclass with normalize_ids = False keeps a native trace id verbatim; span_class
is used by :meth:from_json.
TraceQueryClient ¶
Bases: Protocol
Synchronous trace query API.
TraceSearchQuery
dataclass
¶
matches ¶
Client-side filter: a span must match service/operation/tags; duration and time bounds apply to the whole trace.
TraceSummary
dataclass
¶
TracingASGIMiddleware ¶
ASGI middleware: one SERVER span per HTTP request, parent taken from request headers.
Non-HTTP scopes (lifespan, websocket) and excluded_paths pass through untraced.
TracingConfig
dataclass
¶
Settings for :func:init_tracing_with. repr redacts credential headers.
protocol and endpoint are interpreted by the service's exporter factory; the
template default protocol is http/protobuf. propagators beyond tracecontext,
baggage, b3 and b3multi need a factory from the service package.
protocol and propagators remember whether the caller set them: left out (or passed
as None) they read as :data:DEFAULT_TRACE_PROTOCOL / :data:DEFAULT_TRACE_PROPAGATORS
exactly as before, and :attr:protocol_set / :attr:propagators_set are False so a
service default can apply instead. The marker travels with the value, so
:meth:with_changes, dataclasses.replace and TracingConfig(**fields) keep an unset
field unset; passing the default value explicitly counts as set.
TracingHandle ¶
TracingWSGIMiddleware ¶
WSGI middleware: one SERVER span per request; ends when the response is closed.
UnavailableError ¶
Bases: DatadogApmError
Network error or server unavailable (HTTP 500, 502, 503).
UnsupportedError ¶
Bases: DatadogApmError
The service or deployment does not offer this capability (HTTP 501, missing API).
ValidationError ¶
Bases: DatadogApmError
Bad input (HTTP 400, 413, 422, other 4xx, client-side validation).
add_event ¶
Add an event to the active span (no-op without one).
api_url_for_site ¶
API base URL of a site: https://api.<site> (an empty site means the default).
api_url_for_site("datadoghq.eu") 'https://api.datadoghq.eu'
apoll_until
async
¶
apoll_until(fn: Callable[[], Awaitable[T | None]], *, timeout_s: float = 30.0, interval_s: float = 1.0, predicate: Callable[[T], bool] | None = None, operation: str = 'poll', clock: Callable[[], float] = time.monotonic) -> T
Async :func:poll_until; fn is an async callable.
async_httpx_event_hooks ¶
async_httpx_event_hooks(*, tracer: Tracer | None = None, propagator: TextMapPropagator | None = None) -> dict[str, list[Callable[..., Any]]]
event_hooks for httpx.AsyncClient (same behaviour as :func:httpx_event_hooks).
async_wait_for_trace
async
¶
async_wait_for_trace(client: AsyncTraceQueryClient, trace_id: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = 1.0, min_spans: int = 1, normalize: Callable[[str], str] | None = normalize_trace_id) -> Trace
Async form of :func:wait_for_trace.
build_propagator ¶
build_propagator(names: Sequence[str], factories: Mapping[str, PropagatorFactory] | None = None) -> TextMapPropagator
Composite propagator for names; factories adds or overrides propagators by name.
build_resource ¶
Resource with service.name/service.version/deployment.environment and extras.
The environment is written both as deployment.environment.name (current semantic
conventions) and as the older deployment.environment. Merged on top of the SDK default
resource (telemetry.sdk.*, OTEL_RESOURCE_ATTRIBUTES); explicit config values win.
build_sampler ¶
OpenTelemetry sampler for a TracingConfig.sampler name.
build_tree ¶
Parent/child forest; spans whose parent is missing become roots.
current_span ¶
The active span (a non-recording invalid span when none is active).
current_span_id ¶
16-char lower-hex span id of the active span, or None.
current_trace_id ¶
32-char lower-hex trace id of the active span, or None.
datadog_error_attributes ¶
The Datadog error attributes for an exception (or any other value).
Exceptions give error.type (class name), error.message (str(error)) and
error.stack (formatted traceback); a string gives type Error and the string as
message; other values are JSON-encoded (or repr) into the message.
datadog_exporter_factory ¶
The exporter factory of this package (init_tracing_with): OTLP http/protobuf or
grpc to config.endpoint (default: the local Agent), wrapped in a
:class:~grow_datadog_apm.DatadogErrorExporter.
Headers, compression, export timeout and TLS files come from the config;
tls.insecure_skip_verify is not supported by the OpenTelemetry OTLP exporters and is
ignored. native raises :class:ConfigError (the package exports OTLP only).
datadog_kind ¶
Datadog span.kind (or OpenTelemetry kind name) → SPEC kind; unknown → unspecified.
datadog_log_fields ¶
datadog_log_fields(*, service: str | None = None, env: str | None = None, version: str | None = None) -> dict[str, str]
Datadog log correlation fields for the active span, ready to merge into a log record.
Keys: dd.trace_id, dd.span_id, dd.service, dd.env, dd.version. Service,
env and version come from the arguments, else the active span's resource (service.name,
deployment.environment.name, service.version), else the last init_tracing config.
Without an active span only the service fields are returned; keys are absent when unknown.
logger.info("checkout done", extra=datadog_log_fields()) # doctest: +SKIP
datadog_search_span_to_span ¶
Map one span of the spans search API (data[i] of POST /api/v2/spans/events/search,
or its attributes) to a SPEC :class:~grow_datadog_apm.Span.
Nested span attributes (attributes, custom) are flattened to dotted keys; tags
(key:value) are added as attributes. name = resource_name, kind from
span.kind, status error when status is error or error is set; duration
from the duration attribute (nanoseconds) when present, else end - start.
datadog_trace_id_string ¶
The trace id as Datadog's log correlation (dd.trace_id) and search API use it:
32 lower-case hex characters for a 128-bit id, the low 64 bits in decimal for a 64-bit id.
datadog_trace_span_to_span ¶
Map a Datadog trace span to a SPEC :class:~grow_datadog_apm.Span.
Accepts the Agent's format (trace_id, span_id, parent_id, start,
duration, meta, metrics) and the trace-by-id API format (traceID,
traceIDFull, spanID, parentID, startTime, endTime, duration).
The full trace id comes from traceIDFull / trace_id_hex / meta otel.trace_id, else
the decimal low 64 bits plus meta _dd.p.tid. name = Datadog resource (the OTel span
name for OTLP spans), kind = meta span.kind, status = error flag (message from
error.message, error.msg or otel.status_description) or meta
otel.status_code. Events come from meta events and span_events, links from meta
_dd.span_links and span_links. Attributes are the remaining meta (strings) and
metrics (numbers), plus operation_name, resource_name and span.type. Invalid ids
raise :class:ValidationError.
datetime_to_micros ¶
Microseconds since the epoch (naive datetimes are UTC).
default_tracer ¶
Tracer of this package from the global provider.
dependencies_from_spans ¶
Service dependency links (parent service → child service, different services only).
error_for_code ¶
Return the error class for a code (ErrorCode member or wire value).
error_from_status ¶
error_from_status(status: int, operation: str, *, content: bytes = b'', headers: Headers | None = None, known_secrets: list[str] | None = None, retry_after: float | None = None, request_id_headers: Sequence[str] = ()) -> ServiceError
Map an HTTP error status to the SPEC 2.1 error with a redacted, truncated message.
request_id_headers are checked before the default :data:REQUEST_ID_HEADERS.
extract ¶
extract(carrier: Mapping[str, str], *, context: Context | None = None, propagator: TextMapPropagator | None = None) -> otel_context.Context
Read a context from carrier (exact key match; use :func:extract_headers for HTTP).
extract_datadog_context ¶
Read the Datadog headers of a carrier into a remote span context.
Returns None when they are missing or invalid. A missing sampling priority counts as
sampled.
extract_headers ¶
extract_headers(headers: HeaderSource, *, context: Context | None = None, propagator: TextMapPropagator | None = None) -> otel_context.Context
Read a context from HTTP headers (case-insensitive; mapping or ASGI-style byte pairs).
from_datadog_span_id ¶
Datadog unsigned decimal span id → 16 lower-case hex characters.
from_datadog_trace_id ¶
Join a Datadog trace id (decimal low 64 bits, optional _dd.p.tid high half in hex)
into a 32-character OpenTelemetry trace id. None/empty high64_hex = zero high half.
from_datadog_trace_id("1", "ffffffffffffffff") 'ffffffffffffffff0000000000000001' from_datadog_trace_id("42") '0000000000000000000000000000002a'
get_logger ¶
The package logger (LOGGER_NAME), silent by default (NullHandler).
httpx_event_hooks ¶
httpx_event_hooks(*, tracer: Tracer | None = None, propagator: TextMapPropagator | None = None) -> dict[str, list[Callable[..., Any]]]
event_hooks for httpx.Client: a CLIENT span per request with injected headers.
A request that fails before a response arrives (connection error) never reaches the
response hook, so its span is not exported; use :func:instrument_requests_session style
wrapping or with_span around the call when such failures must be traced.
init_tracing ¶
init_tracing(config: TracingConfig | Mapping[str, Any] | None = None, *, apm_config: DatadogApmConfig | None = None, env: Mapping[str, str] | None = None, ignore_env: bool = False, span_processors: Sequence[SpanProcessor] = (), **fields: Any) -> DatadogTracingHandle
Set up OpenTelemetry tracing that exports to the Datadog Agent (SPEC §5).
- OTLP
http/protobuftohttp://<agent>:4318/v1/tracesby default, orgrpctohttp://<agent>:4317(the Agent needs its OTLP receiver enabled); - unified service tagging:
service_name/service_version/environment→ resourceservice.name/service.version/deployment.environment.name(Datadogservice,version,env), plusDD_TAGSas resource attributes; - propagators
datadog,tracecontext,baggageby default (Datadog headers win on conflict); - the Datadog error attributes (:class:
DatadogErrorExporter) and the terminated-context link (:class:DatadogSpanLinkProcessor).
Tracing options are any :class:TracingConfig field, given as a TracingConfig, a mapping
or keyword arguments (keywords win). Unset fields come from apm_config or
:meth:DatadogApmConfig.from_env (DD_SERVICE, DD_VERSION, DD_ENV, DD_TAGS,
DD_AGENT_HOST, GROW_DATADOG_APM_*, OTEL_EXPORTER_OTLP_*); env replaces
os.environ and ignore_env=True reads no environment. In a TracingConfig instance
a field equal to its default counts as unset. span_processors are added after the Datadog
ones.
handle = init_tracing(service_name="checkout", environment="prod") # doctest: +SKIP with with_span("charge"): # doctest: +SKIP ... ... handle.shutdown() # doctest: +SKIP
init_tracing_with ¶
init_tracing_with(config: TracingConfig, exporter_factory: ExporterFactory, *, propagator_factories: Mapping[str, PropagatorFactory] | None = None, span_processors: Sequence[SpanProcessor] = (), id_generator: IdGenerator | None = None, sampler: Sampler | None = None) -> TracingHandle
Build a TracerProvider for config with a BatchSpanProcessor around the exporter.
Services wrap this in their init_tracing(config). propagator_factories lets a
service add datadog/sw8 style propagators; span_processors (extra processors,
e.g. a second exporter) are added after the batch processor; sampler replaces the one
built from config.sampler/sampler_ratio (remote or vendor samplers). With
config.set_global the provider and propagator become the
OpenTelemetry globals (the API allows one global provider per process: is_global on
the handle tells whether it took effect).
inject ¶
inject(carrier: MutableMapping[str, str] | None = None, *, context: Context | None = None, propagator: TextMapPropagator | None = None) -> MutableMapping[str, str]
Write the current (or given) context into carrier and return it.
Uses propagator or the global propagator (set by init_tracing_with).
inject_headers ¶
inject_headers(headers: MutableMapping[str, str] | None = None, *, context: Context | None = None, propagator: TextMapPropagator | None = None) -> MutableMapping[str, str]
Add propagation headers (traceparent, baggage …) to headers and return them.
instrument_requests_session ¶
instrument_requests_session(session: Session, *, tracer: Tracer | None = None, propagator: TextMapPropagator | None = None) -> requests.Session
Trace every request sent through session (CLIENT span, headers injected).
Wraps session.send once; calling it again on the same session is a no-op.
mark_span_error ¶
Set ERROR status on span and record the exception (when error is one).
micros_to_datetime ¶
Exact UTC datetime for microseconds since the epoch.
normalize_datadog_span_id ¶
Datadog decimal span id → 16 hex characters; None for an empty or zero id.
normalize_datadog_trace_id ¶
Normalize any trace id Datadog returns to 32 lower-case hex characters.
A 32-character value is hex, a shorter all-digit value (at most 20 digits) or an int is
the 64-bit decimal form, anything else is hex.
normalize_headers ¶
Lower-cased header names → values; accepts mappings and (name, value) pairs incl. bytes.
normalize_span_id ¶
16-char lower-hex span id (left-padded); raises ValidationError when invalid.
normalize_trace_id ¶
32-char lower-hex trace id; 64-bit ids (16 hex chars, ints, 8 bytes) are left-padded.
Raises ValidationError for non-hex, too long or all-zero ids.
order_propagators ¶
Put tracecontext before datadog so the Datadog propagator sees the W3C result and
applies the conflict rules (Datadog wins); every other name keeps its position. Names are
trimmed and lower-cased.
order_propagators(["datadog", "tracecontext", "baggage"]) ['tracecontext', 'datadog', 'baggage']
otlp_traces_url ¶
Exporter URL for a protocol and an OTLP endpoint.
For http/protobuf an endpoint without a path gets /v1/traces; gRPC endpoints are used
as they are.
otlp_traces_url("http/protobuf", "http://agent:4318") 'http://agent:4318/v1/traces'
parse_bool ¶
Parse true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.
parse_datadog_tags ¶
Parse Datadog tags (DD_TAGS): key:value pairs separated by commas and/or spaces.
Entries without a : or with an empty key are ignored.
parse_datadog_tags("team:sdk, tier:web")
parse_duration ¶
Parse a duration into seconds.
Accepts integer milliseconds ("1500" → 1.5) or Go-style units ("500ms", "10s",
"2m", "1h", "1m30s"). Raises :class:ValueError for anything else.
parse_retry_after ¶
Parse Retry-After as delta seconds or an HTTP-date; return seconds (>= 0) or None.
poll_until ¶
poll_until(fn: Callable[[], T | None], *, timeout_s: float = 30.0, interval_s: float = 1.0, predicate: Callable[[T], bool] | None = None, operation: str = 'poll', sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic) -> T
Call fn every interval_s until it returns a ready value; return that value.
A value is ready when it is not None and predicate(value) is true (without a
predicate: not an empty container). Retryable SDK errors raised by fn are remembered
and polling continues; other errors propagate. Raises :class:TimeoutError after timeout_s.
quote_query_value ¶
Quote a value for the Datadog query syntax when it contains spaces or special characters.
quote_query_value("GET /api/v1/users") '"GET /api/v1/users"'
record_exception ¶
Record error as an exception event on the active span and set the Datadog error
attributes. The span status is unchanged. No-op without an active span.
redact_fields ¶
Recursively redact values whose key looks sensitive in nested mappings and lists.
redact_headers ¶
Copy of headers with sensitive values replaced by [REDACTED].
redact_text ¶
Replace every known secret value (length >= 4) in text with [REDACTED].
redact_url ¶
Redact user info and every query value (all values, not only sensitive ones).
Query names are kept so the URL stays useful in logs.
retry_after_from_headers ¶
retry_after_from_headers(headers: Headers | Mapping[str, str], names: Sequence[str] = RETRY_AFTER_HEADERS, *, now: Callable[[], float] = time.time) -> float | None
Server requested delay in seconds from the first of names that parses.
Retry-After is delta seconds or an HTTP-date. Other headers (X-RateLimit-Reset,
RateLimit-Reset …) may be delta seconds or a Unix timestamp in seconds or milliseconds;
timestamps are turned into the remaining delay.
set_datadog_log_defaults ¶
set_datadog_log_defaults(*, service: str | None = None, env: str | None = None, version: str | None = None) -> None
Set the service/env/version :func:datadog_log_fields uses when the active span carries
no resource (called by init_tracing; call without arguments to clear).
set_error ¶
Mark the active span as failed (ERROR status, exception event for exceptions) and set the Datadog error attributes. No-op without an active span.
set_error_attributes ¶
Set error.type, error.message and error.stack for error on span
(default: the active span). No-op without a recording span.
sort_spans ¶
Spans sorted by start time, then span id.
span_from_readable ¶
Convert a finished OpenTelemetry SDK span (e.g. from an in-memory exporter).
span_kind ¶
SpanKind from an enum member or a name ("server"); None → INTERNAL.
terminated_context ¶
The W3C context that lost against Datadog headers during extract, if any.
terminated_context_links ¶
Span links for a span started from an extracted context.
One link to the terminated W3C context (reason=terminated_context,
context_headers=tracecontext), or none. Pass them as links= when you start spans
without init_tracing's processor.
to_datadog_span_id ¶
OpenTelemetry span id (up to 16 hex characters) → Datadog unsigned decimal.
to_datadog_trace_id ¶
Split an OpenTelemetry trace id (up to 32 hex characters, left-padded) into Datadog's form.
Invalid or all-zero ids raise :class:ValidationError.
to_datadog_trace_id("a3ce929d0e0e47364bf92f3577b34da6").low64_decimal '5474458728733560230'
to_seconds ¶
Normalise a duration given as float seconds or :class:datetime.timedelta.
trace_fields ¶
{"trace_id": …, "span_id": …} of the active span for log fields; {} without one.
trace_id_for_path ¶
The id to put in a GET /api/v2/trace/{id} path.
Datadog reads an all-digit id as decimal, so a hex id without a letter is sent as its full decimal value; otherwise lower-case hex.
trace_search_query_string ¶
Datadog query string for a SPEC :class:TraceSearchQuery: service:,
resource_name:, @<tag>: and @duration:>= / <= (nanoseconds). Empty → *.
traced ¶
traced(name_or_fn: str | Callable[P, R] | None = None, /, *, attributes: Attributes = None, kind: SpanKindLike = None, tracer: Tracer | None = None) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]
Decorator that runs a function (sync or async def) inside a span.
@traced, @traced() and @traced("name") all work; the default span name is the
function's qualified name. Async generators are not supported (the span would end before
iteration).
truncate ¶
Truncate text to limit characters (adds an ellipsis when cut).
user_agent ¶
grow-codes-<key>/<version> (python) plus <suffix> when given.
validate_site ¶
Validate a site name and return it normalized.
A value with a scheme, port, path or other non-host characters (for example
"https://app.datadoghq.com") raises :class:ConfigError.
wait_for_trace ¶
wait_for_trace(client: TraceQueryClient, trace_id: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = 1.0, min_spans: int = 1, normalize: Callable[[str], str] | None = normalize_trace_id) -> Trace
Poll get_trace until the trace has min_spans spans; TimeoutError otherwise.
NotFoundError and retryable errors count as "not there yet". normalize turns
trace_id into the id passed to get_trace (default: 32-char lower hex); None
passes native ids verbatim.
with_datadog_error_attributes ¶
span with the Datadog error attributes derived from its last exception event or
ERROR status (see :class:DatadogErrorExporter), or span itself when it already has them
or has no error.
with_span ¶
with_span(name: str, fn: Callable[[Span], R] | None = None, *, attributes: Attributes = None, kind: SpanKindLike = None, links: Sequence[Link | SpanContext] | None = None, tracer: Tracer | None = None) -> R | AbstractContextManager[otel_trace.Span]
Run fn(span) inside a new current span, or return a context manager without fn.
The span always ends. An exception is recorded, sets ERROR status and is re-raised
(cancellation, asyncio.CancelledError or the SDK CancelledError, is not). The
context-manager form also works inside async code (context is kept in contextvars).