Skip to content

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

from_json(doc: Any) -> AgentInfo

Parse a decoded GET /info body (anything that is not an object gives defaults).

AsyncBaseTraceQueryClient

Async :class:BaseTraceQueryClient.

query_trace_id

query_trace_id(trace_id: str) -> str

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.

resources property

resources: ResourceRegistry

Background resources stopped by :meth:aclose.

spans property

spans: AsyncDatadogSpansQuery

The async SaaS spans query API (created on first use, closed by :meth:aclose).

aclose async

aclose() -> None

Flush and shut down the tracing handles (in a worker thread), close the query API and release connections (idempotent).

agent_info async

agent_info() -> AgentInfo

See :meth:DatadogApmClient.agent_info.

from_env classmethod

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> AsyncDatadogApmClient

Build an async client from the environment (see :meth:DatadogApmConfig.from_env).

health async

health() -> HealthStatus

See :meth:DatadogApmClient.health.

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).

ping async

ping() -> float

See :meth:DatadogApmClient.ping.

request async

request(req: Request) -> Response

Send a raw request to the Agent.

server_version async

server_version() -> str

See :meth:DatadogApmClient.server_version.

AsyncDatadogSpansQuery

Bases: AsyncBaseTraceQueryClient

Asynchronous :class:DatadogSpansQuery (same methods, awaited; :meth:search_spans is an async iterator). Cancel a call by cancelling its task.

aclose async

aclose() -> None

Release connections (idempotent).

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

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> AsyncDatadogSpansQuery

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

list_operations(service: str) -> list[str]

See :meth:DatadogSpansQuery.list_operations.

list_services async

list_services(*, env: str | None = None) -> list[str]

See :meth:DatadogSpansQuery.list_services.

ping async

ping() -> float

See :meth:DatadogSpansQuery.ping.

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

search_traces(query: TraceSearchQuery | None = None) -> list[TraceSummary]

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").

aclose async

aclose() -> None

Close the connection pool and abort backoff sleeps (idempotent).

request async

request(req: Request) -> Response

Send req with retries; return the response or raise the mapped error.

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.

from_env classmethod

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> _C

Build from the environment, then validate.

Precedence: explicit keyword > GROW_DATADOG_APM_<NAME> > vendor variables > default. env defaults to os.environ; pass a dict in tests.

known_secrets

known_secrets() -> list[str]

Revealed values of every :class:Secret field (used to redact error text).

validate

validate() -> _C

Check the common rules; raise :class:ConfigError. Returns self.

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

query_trace_id(trace_id: str) -> str

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.

cancel

cancel() -> None

Request cancellation (idempotent).

on_cancel

on_cancel(callback: Callable[[], None]) -> Callable[[], None]

Run callback on cancellation (now if already cancelled); returns an unregister.

wait

wait(timeout: float | None = None) -> bool

Block until cancelled or timeout; return whether the token is cancelled.

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

resources property

resources: ResourceRegistry

Background resources stopped by :meth:close.

spans property

spans: DatadogSpansQuery

The SaaS spans query API (created on first use, closed by :meth:close).

Raises :class:ConfigError when api_key or app_key is missing.

agent_info

agent_info(*, cancel: CancelToken | None = None) -> AgentInfo

GET /info of the Agent.

close

close() -> None

Flush and shut down every tracing handle started with :meth:init_tracing, close the query API and release connections (idempotent).

from_env classmethod

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> DatadogApmClient

Build a client from GROW_DATADOG_APM_* and DD_* variables (see :meth:DatadogApmConfig.from_env).

health

health(*, cancel: CancelToken | None = None) -> HealthStatus

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

ping(*, cancel: CancelToken | None = None) -> float

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

request(req: Request, *, cancel: CancelToken | None = None) -> Response

Send a raw request to the Agent (retries, hooks, redaction).

server_version

server_version(*, cancel: CancelToken | None = None) -> str

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

has_query_credentials: bool

True when both the API key and the application key are set.

otlp_traces_endpoint property

otlp_traces_endpoint: str

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

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> _C

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.

validate

validate() -> _C

Common checks plus the Datadog rules; raises :class:ConfigError.

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.

export

export(spans: Sequence[ReadableSpan]) -> SpanExportResult

Add the Datadog error attributes and export with the wrapped exporter.

force_flush

force_flush(timeout_millis: int = 30000) -> bool

Flush the wrapped exporter.

shutdown

shutdown() -> None

Shut the wrapped exporter down.

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 traceparent is kept),
  • different trace id → the Datadog context wins and the W3C context is remembered in the returned context; :class:DatadogSpanLinkProcessor (installed by init_tracing) adds it to the next span as a link with reason=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.

fields property

fields: set[str]

Header names this propagator reads and writes.

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.

force_flush

force_flush(timeout_millis: int = 30000) -> bool

Nothing to do.

on_end

on_end(span: Any) -> None

Nothing to do.

on_start

on_start(span: Span, parent_context: Context | None = None) -> None

Add the terminated-context link when the span's remote parent won the conflict.

shutdown

shutdown() -> None

Nothing to do.

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

close

close() -> None

Release connections (idempotent).

from_env classmethod

from_env(env: Mapping[str, str] | None = None, **overrides: Any) -> DatadogSpansQuery

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

list_operations(service: str, *, cancel: CancelToken | None = None) -> list[str]

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

list_services(*, env: str | None = None, cancel: CancelToken | None = None) -> list[str]

GET /api/v2/apm/services?filter[env]=…: sorted names of the services that reported traces. env defaults to the configured environment, else * (all).

ping

ping(*, cancel: CancelToken | None = None) -> float

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

Bases: TracingHandle

A running Datadog tracing setup (:class:TracingHandle plus the OTLP endpoint).

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.

duration

duration(name: str, vendor_names: Iterable[str] = ()) -> builtins.float | None

Duration in seconds.

lookup

lookup(name: str, vendor_names: Iterable[str] = ()) -> tuple[str, str] | None

Return (variable_name, raw_value) for the first variable that is set.

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 (or None to keep the default). The mapped error is what Hooks.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").

close

close() -> None

Close the connection pool and abort backoff sleeps (idempotent).

request

request(req: Request, *, cancel: CancelToken | None = None) -> Response

Send req with retries; return the response or raise the mapped error.

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

register(item: Stoppable) -> None

Track item; when the registry is already closed the item is stopped now.

Response dataclass

A completed HTTP response (body fully read).

json

json() -> Any

Decode the body as JSON; :class:ValidationError when it is not valid JSON.

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.

max_attempts property

max_attempts: int

Total attempts including the first one.

backoff

backoff(retry: int) -> float

Full-jitter sleep in seconds before retry retry (0-based).

backoff_cap

backoff_cap(retry: int) -> float

Upper bound of the jittered sleep before retry retry (0-based).

Secret

Wraps a credential so it never shows up in str/repr/logs.

s = Secret("hunter2") str(s), s.reveal() ('[REDACTED]', 'hunter2')

reveal

reveal() -> str

Return the wrapped value.

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.

from_json classmethod

from_json(data: Mapping[str, Any]) -> Span

Parse the wire form; ValidationError for malformed input.

to_json

to_json() -> dict[str, Any]

Normalized wire form (camelCase, schema Span).

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.

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).

find

find(name: str) -> SpanNode | None

Depth-first search for a node by span name.

SpanStatus dataclass

from_json classmethod

from_json(data: Any) -> SpanStatus

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

matches(trace: Trace) -> bool

Client-side filter: a span must match service/operation/tags; duration and time bounds apply to the whole trace.

TraceSummary dataclass

Search result row; normalize_ids = False on a subclass keeps native ids.

from_trace classmethod

from_trace(trace: Trace) -> TraceSummary

Summary of a trace (root = earliest span without a known parent).

to_json

to_json() -> dict[str, Any]

Wire form (traceSummary in trace.schema.json).

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.

propagators_set property

propagators_set: bool

Whether propagators was given explicitly (False: the default applies).

protocol_set property

protocol_set: bool

Whether protocol was given explicitly (False: the default applies).

validate

validate() -> None

Raise ConfigError for invalid settings (never echoing values).

with_changes

with_changes(**changes: Any) -> TracingConfig

Copy with some fields replaced (unset protocol/propagators stay unset).

TracingHandle

Result of :func:init_tracing_with: provider, propagator, flush and shutdown.

force_flush

force_flush(timeout_s: float | timedelta | None = None) -> None

Export every finished span now; TimeoutError when it does not finish in time.

shutdown

shutdown() -> None

Flush and stop the provider and its exporter; idempotent.

tracer

tracer(name: str, version: str | None = None) -> otel_trace.Tracer

A tracer from this handle's provider (works with set_global=False too).

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_event(name: str, attributes: Attributes = None) -> None

Add an event to the active span (no-op without one).

api_url_for_site

api_url_for_site(site: str = DEFAULT_SITE) -> str

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

build_resource(config: TracingConfig) -> 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

build_sampler(name: str, ratio: float = 1.0) -> Sampler

OpenTelemetry sampler for a TracingConfig.sampler name.

build_tree

build_tree(spans: Iterable[Span]) -> list[SpanNode]

Parent/child forest; spans whose parent is missing become roots.

current_span

current_span() -> otel_trace.Span

The active span (a non-recording invalid span when none is active).

current_span_id

current_span_id() -> str | None

16-char lower-hex span id of the active span, or None.

current_trace_id

current_trace_id() -> str | None

32-char lower-hex trace id of the active span, or None.

datadog_error_attributes

datadog_error_attributes(error: BaseException | str | object) -> dict[str, str]

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

datadog_exporter_factory(config: TracingConfig) -> SpanExporter

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_kind(value: Any) -> SpanKindName

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

datadog_search_span_to_span(item: RawDatadogSpan) -> 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

datadog_trace_id_string(trace_id_hex: str) -> str

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

datadog_trace_span_to_span(raw: RawDatadogSpan) -> 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

datetime_to_micros(value: datetime) -> int

Microseconds since the epoch (naive datetimes are UTC).

default_tracer

default_tracer() -> otel_trace.Tracer

Tracer of this package from the global provider.

dependencies_from_spans

dependencies_from_spans(spans: Iterable[Span]) -> list[DependencyLink]

Service dependency links (parent service → child service, different services only).

error_for_code

error_for_code(code: ErrorCode | str) -> type[DatadogApmError]

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

extract_datadog_context(carrier: Any, getter: Getter[Any] = default_getter) -> SpanContext | None

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

from_datadog_span_id(decimal: str) -> str

Datadog unsigned decimal span id → 16 lower-case hex characters.

from_datadog_trace_id

from_datadog_trace_id(low64_decimal: str, high64_hex: str | None = None) -> str

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

get_logger() -> logging.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/protobuf to http://<agent>:4318/v1/traces by default, or grpc to http://<agent>:4317 (the Agent needs its OTLP receiver enabled);
  • unified service tagging: service_name / service_version / environment → resource service.name / service.version / deployment.environment.name (Datadog service, version, env), plus DD_TAGS as resource attributes;
  • propagators datadog, tracecontext, baggage by 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.

is_datadog_site

is_datadog_site(site: str) -> bool

True when site is one of :data:DATADOG_SITES.

mark_span_error

mark_span_error(span: Span, error: BaseException | str) -> None

Set ERROR status on span and record the exception (when error is one).

micros_to_datetime

micros_to_datetime(micros: int) -> datetime

Exact UTC datetime for microseconds since the epoch.

new_idempotency_key

new_idempotency_key() -> str

A random key for the Idempotency-Key header.

normalize_datadog_span_id

normalize_datadog_span_id(value: str | int | None) -> str | None

Datadog decimal span id → 16 hex characters; None for an empty or zero id.

normalize_datadog_trace_id

normalize_datadog_trace_id(value: str | int) -> str

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

normalize_headers(headers: HeaderSource) -> dict[str, list[str]]

Lower-cased header names → values; accepts mappings and (name, value) pairs incl. bytes.

normalize_site

normalize_site(site: str) -> str

Lower-case and trim a site name.

normalize_span_id

normalize_span_id(value: str | int | bytes) -> str

16-char lower-hex span id (left-padded); raises ValidationError when invalid.

normalize_trace_id

normalize_trace_id(value: str | int | bytes) -> str

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

order_propagators(names: Sequence[str]) -> list[str]

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

otlp_traces_url(protocol: str, endpoint: str) -> str

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_bool(text: str) -> bool

Parse true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.

parse_datadog_tags

parse_datadog_tags(raw: str) -> dict[str, str]

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_duration(text: str) -> float

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(value: str | None, *, now: Callable[[], float] = time.time) -> float | None

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_query_value(value: str) -> str

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_exception(error: BaseException, attributes: Attributes = None) -> None

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

redact_fields(value: Any, extra_keys: Iterable[str] = ()) -> Any

Recursively redact values whose key looks sensitive in nested mappings and lists.

redact_headers

redact_headers(headers: Mapping[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]

Copy of headers with sensitive values replaced by [REDACTED].

redact_text

redact_text(text: str, known_secrets: Iterable[str | Secret | None] = ()) -> str

Replace every known secret value (length >= 4) in text with [REDACTED].

redact_url

redact_url(url: str) -> str

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

set_error(error: BaseException | str) -> None

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_attributes(error: BaseException | str | object, span: Span | None = None) -> None

Set error.type, error.message and error.stack for error on span (default: the active span). No-op without a recording span.

sort_spans

sort_spans(spans: Iterable[Span]) -> list[Span]

Spans sorted by start time, then span id.

span_from_readable

span_from_readable(span: ReadableSpan) -> Span

Convert a finished OpenTelemetry SDK span (e.g. from an in-memory exporter).

span_kind

span_kind(kind: SpanKindLike) -> SpanKind

SpanKind from an enum member or a name ("server"); None → INTERNAL.

terminated_context

terminated_context(context: Context | None = None) -> TerminatedContext | None

The W3C context that lost against Datadog headers during extract, if any.

terminated_context_links(context: Context | None = None) -> list[Link]

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

to_datadog_span_id(span_id_hex: str) -> str

OpenTelemetry span id (up to 16 hex characters) → Datadog unsigned decimal.

to_datadog_trace_id

to_datadog_trace_id(trace_id_hex: str) -> DatadogTraceId

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

to_seconds(value: float | timedelta) -> float

Normalise a duration given as float seconds or :class:datetime.timedelta.

trace_fields

trace_fields() -> dict[str, str]

{"trace_id": …, "span_id": …} of the active span for log fields; {} without one.

trace_id_for_path

trace_id_for_path(trace_id_hex: str) -> str

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

trace_search_query_string(query: TraceSearchQuery) -> str

Datadog query string for a SPEC :class:TraceSearchQuery: service:, resource_name:, @<tag>: and @duration:>= / <= (nanoseconds). Empty → *.

traced

traced(fn: Callable[P, R]) -> Callable[P, R]
traced(name: str | None = None, /, *, attributes: Attributes = None, kind: SpanKindLike = None, tracer: Tracer | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]
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: str, limit: int = 300) -> str

Truncate text to limit characters (adds an ellipsis when cut).

user_agent

user_agent(suffix: str | None = None) -> str

grow-codes-<key>/<version> (python) plus <suffix> when given.

validate_site

validate_site(site: str) -> str

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

with_datadog_error_attributes(span: ReadableSpan) -> ReadableSpan

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: None = None, *, attributes: Attributes = None, kind: SpanKindLike = None, links: Sequence[Link | SpanContext] | None = None, tracer: Tracer | None = None) -> AbstractContextManager[otel_trace.Span]
with_span(name: str, fn: Callable[[Span], R], *, attributes: Attributes = None, kind: SpanKindLike = None, links: Sequence[Link | SpanContext] | None = None, tracer: Tracer | None = None) -> R
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).