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 Log Management.

from grow_datadog_logs import DatadogLogsClient, DatadogLogsConfig client = DatadogLogsClient.from_env() # doctest: +SKIP

AttrValue module-attribute

AttrValue: TypeAlias = str | int | float | bool | Sequence['AttrValue'] | Mapping[str, 'AttrValue']

Attribute value: scalar, list of values or nested mapping (OTel AnyValue without bytes).

AsyncBaseLogQueryClient

Async :class:BaseLogQueryClient.

AsyncBatchProcessor

Bases: _BatchCore

Batches records for an :class:AsyncLogExporter on an asyncio task.

The task starts on the running loop at the first :meth:add (or :meth:flush). :meth:add may be called from other threads; it wakes the worker thread-safely. Exports are bounded by export_timeout_s with :func:asyncio.wait_for.

add

add(record: LogRecord) -> bool

Queue without blocking; False when dropped (block acts as drop_newest here).

add_wait async

add_wait(record: LogRecord) -> bool

Queue a record, waiting for queue space with drop_policy="block".

flush async

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

Export everything queued now; raises TimeoutError when timeout_s passes first.

shutdown async

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

Drain (bounded by timeout_s), stop the task, shut the exporter down; idempotent.

AsyncBatchingLogClient

Bases: _ClientBase

:class:AsyncLogClient over an :class:AsyncLogExporter + :class:AsyncBatchProcessor.

close async

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

Flush and shut down; idempotent.

send_wait async

send_wait(record: LogRecord | LogInput) -> bool

Like :meth:send but waits for queue space with drop_policy="block".

AsyncDatadogLogClient

Bases: AsyncBatchingLogClient

Async :class:DatadogLogClient; create it with :meth:AsyncDatadogLogsClient.log_client.

AsyncDatadogLogExporter

Bases: _ExporterBase

:class:AsyncLogExporter twin of :class:DatadogLogExporter.

export async

export(records: Sequence[LogRecord], *, gzip: bool = True, timeout_s: float = 30.0) -> ExportResult

Send the records; never raises for service errors (see the sync exporter).

send_payload async

send_payload(body: str, *, gzip: bool = True, timeout_s: float | None = None) -> int

Post one JSON array body to the intake; returns the transport retries used.

shutdown async

shutdown() -> None

Nothing to release; the client owns the transport.

AsyncDatadogLogsClient

Asynchronous :class:DatadogLogsClient; 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.

exporter property

exporter: AsyncDatadogLogExporter

The intake exporter (one per client, Datadog limits).

resources property

resources: ResourceRegistry

Background resources stopped by :meth:aclose.

aclose async

aclose() -> None

Flush and close every log client, stop tails and release connections (idempotent).

from_env classmethod

from_env(environ: Mapping[str, str] | None = None, /, **overrides: Any) -> AsyncDatadogLogsClient

Build a client from the environment (see :meth:DatadogLogsConfig.from_env).

health async

health() -> HealthStatus

Reachability through GET /api/v1/validate (see :meth:DatadogLogsClient.health).

log_client

log_client(options: BatchOptions | None = None, *, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True, exporter: AsyncDatadogLogExporter | None = None) -> AsyncDatadogLogClient

A batching :class:AsyncDatadogLogClient (see :meth:DatadogLogsClient.log_client).

new_exporter

new_exporter(*, max_entries_per_request: int | None = None, max_payload_bytes: int | None = None, max_log_bytes: int | None = None) -> AsyncDatadogLogExporter

An intake exporter with smaller request limits (values above Datadog's are capped).

ping async

ping() -> float

Authenticated round trip GET /api/v1/validate; returns the latency in ms.

query

query() -> AsyncDatadogLogsQuery

The query client. :class:ConfigError without app_key.

server_version async

server_version() -> str

Always raises :class:UnsupportedError (Datadog reports no server version).

validate_api_key async

validate_api_key() -> bool

True for {"valid": true}, False for 403; other failures raise.

AsyncDatadogLogsQuery

Bases: _QueryBase, AsyncBaseLogQueryClient

Async :class:DatadogLogsQuery; create it with :meth:AsyncDatadogLogsClient.query.

aggregate_logs async

aggregate_logs(compute: DatadogCompute | Mapping[str, Any] | Sequence[DatadogCompute | Mapping[str, Any]], group_by: Sequence[DatadogGroupBy | Mapping[str, Any]] = (), *, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None) -> DatadogAggregateResult

POST /api/v2/logs/analytics/aggregate (see the sync client).

iterate_logs async

iterate_logs(query: str | None = None, *, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, page_size: int | None = None, sort: LogsSort | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None) -> AsyncIterator[DatadogLogEvent]

Async iterator over every matching event across pages (see the sync client).

list_indexes async

list_indexes() -> list[DatadogLogIndex]

Log indexes from GET /api/v1/logs/config/indexes (needs logs_read_config).

list_labels async

list_labels() -> list[str]

Always raises :class:UnsupportedError (no Datadog API lists log attributes).

list_streams async

list_streams() -> list[str]

Index names (see :meth:list_indexes).

search async

search(query: str, *, start: datetime | None = None, end: datetime | None = None, limit: int = 100, order: SearchOrder = 'desc', cursor: str | None = None) -> DatadogLogSearchResult

Category search: one page of :meth:search_logs.

search_logs async

search_logs(query: str | None = None, *, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: LogsSort | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None) -> DatadogLogsPage

One page of POST /api/v2/logs/events/search (see the sync client).

stop_tails async

stop_tails() -> None

Stop every tail started by this client (called by the client's aclose).

tail async

tail(query: str, on_record: Callable[[LogRecord], None], *, interval_s: float | timedelta = DEFAULT_POLL_INTERVAL_S, start: datetime | None = None, on_error: Callable[[Exception], None] | None = None) -> AsyncPollingTail

Polling tail over :meth:search on the running loop (default interval 5 s).

Records from start (default: now). :meth:AsyncDatadogLogsClient.aclose stops it.

wait_for_log async

wait_for_log(query: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = DEFAULT_POLL_INTERVAL_S, predicate: Callable[[LogRecord], bool] | None = None) -> LogRecord

Poll :meth:search until a record matches (default interval 5 s, timeout 30 s).

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.

AsyncLogClient

Bases: Protocol

Asynchronous log client: send stays synchronous, flush/close are awaited.

AsyncLogExporter

Bases: Protocol

Asynchronous exporter, awaited by :class:AsyncBatchProcessor on the caller's event loop.

AsyncLogQueryClient

Bases: Protocol

Asynchronous query API (same methods, awaited).

AsyncPollingTail

Async :class:PollingTail; the polling task runs on the current event loop.

AuthenticationError

Bases: DatadogLogsError

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

BaseLogQueryClient

Base for service query clients: implement :meth:search, override what the service has.

tail defaults to :class:PollingTail; list_streams/list_labels raise UnsupportedError; wait_for_log uses :func:wait_for_log.

BatchOptions dataclass

Batching options; durations are float seconds (timedelta accepted).

max_export_retries/retry_backoff_s: a batch whose export failed with a retryable SDK error (raised, or returned with nothing accepted) is exported again up to max_export_retries times, waiting retry_backoff_s * 2**n before retry n. Partial acceptance is final.

from_mapping classmethod

from_mapping(data: Mapping[str, Any]) -> BatchOptions

Build from the camelCase form used by conformance scenarios (flushIntervalMs …).

BatchProcessor

Bases: _BatchCore

Batches records for a synchronous :class:LogExporter on a daemon worker thread.

The worker starts with the first record. It exports when a batch is full, when flush_interval_s passed since the first queued record, on :meth:flush and on :meth:shutdown. Processors with a started worker are shut down at interpreter exit.

add

add(record: LogRecord) -> bool

Queue a record; False when it was dropped. Blocks only with drop_policy="block".

flush

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

Export everything queued now; raises TimeoutError when timeout_s passes first.

shutdown

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

Drain the queue (bounded by timeout_s), stop the worker and shut the exporter down.

Idempotent. Records still queued when the timeout passes are dropped with reason shutdown; later :meth:add calls are dropped the same way.

BatchStats dataclass

Counters of a batch processor (see the module docs for their meaning).

BatchingLogClient

Bases: _ClientBase

:class:LogClient over a synchronous :class:LogExporter and a :class:BatchProcessor.

redaction defaults to RedactionProcessor(); pass None to disable it. correlate adds the active span's ids to records without a trace id.

close

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

Flush and shut down; idempotent.

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: DatadogLogsError, 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: DatadogLogsError

Invalid or missing configuration.

ConflictError

Bases: DatadogLogsError

Conflict or failed precondition (HTTP 409, 412, CAS mismatch).

DatadogAggregateResult dataclass

Result of aggregate_logs.

DatadogBucket dataclass

One bucket of an aggregation.

number

number(key: str) -> float | None

The numeric value of compute key (None when missing or not a number).

timeseries

timeseries(key: str) -> list[DatadogTimeseriesPoint]

The timeseries of compute key ([] when missing or not a timeseries).

DatadogCompute dataclass

One computation of aggregate_logs; results are keyed c0, c1 … in order.

DatadogGroupBy dataclass

One group-by facet of aggregate_logs.

DatadogGroupBySort dataclass

Sort of a group-by.

DatadogLogClient

Bases: BatchingLogClient

:class:LogClient that ships records to the Datadog logs intake.

Records go through a :class:DatadogLogExporter and a background :class:BatchProcessor. Create it with :meth:DatadogLogsClient.log_client.

DatadogLogEvent dataclass

One log event returned by the Datadog search API, flattened.

record

record() -> LogRecord

This event normalized to a :class:LogRecord (see :func:event_to_log_record).

DatadogLogExporter

Bases: _ExporterBase

:class:LogExporter for POST {intake}/api/v2/logs.

Maps records to Datadog JSON, truncates oversized messages (grow.truncated: true), splits batches at 1000 entries / 5 MB, gzips when asked and sends with header DD-API-KEY only. The intake POST is retried like an idempotent call (429, 5xx, network errors; duplicates are possible after an ambiguous failure). Limits above the Datadog limits are capped. Create it with :attr:DatadogLogsClient.exporter.

export

export(records: Sequence[LogRecord], *, gzip: bool = True, timeout_s: float = 30.0) -> ExportResult

Send the records; never raises for service errors.

A failing request stops the export: later records count as rejected and the error is returned in :attr:ExportResult.error.

send_payload

send_payload(body: str, *, gzip: bool = True, timeout_s: float | None = None) -> int

Post one JSON array body to the intake; returns the transport retries used.

Raises the mapped SDK error.

shutdown

shutdown() -> None

Nothing to release; the client owns the transport.

DatadogLogIndex dataclass

One Datadog log index.

DatadogLogSearchResult dataclass

Bases: LogSearchResult

Result of :meth:DatadogLogsQuery.search: the category result plus Datadog metadata.

DatadogLogsClient

Synchronous client for Datadog Log Management.

API key checks (:meth:health, :meth:ping, :meth:validate_api_key), the logs intake (:meth:log_client, :attr:exporter) and the query API (:meth:query, needs app_key). Thread-safe; use as a context manager or call :meth:close. I/O methods accept cancel= (a :class:CancelToken) to abort from another thread.

exporter property

exporter: DatadogLogExporter

The intake exporter (one per client, Datadog limits).

resources property

resources: ResourceRegistry

Background resources (tails) stopped by :meth:close.

close

close() -> None

Flush and close every log client, stop tails and release connections (idempotent).

from_env classmethod

from_env(environ: Mapping[str, str] | None = None, /, **overrides: Any) -> DatadogLogsClient

Build a client from GROW_DATADOG_LOGS_*, DD_API_KEY, DD_SITE … variables.

health

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

Reachability through GET /api/v1/validate (Datadog has no health endpoint).

2xx -> healthy (details["apiKeyValid"]); 401/403 -> healthy=False, status="unauthorized"; 429 -> degraded; 5xx -> unhealthy; network errors -> unreachable. Never raises except :class:CancelledError / :class:ConfigError.

log_client

log_client(options: BatchOptions | None = None, *, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True, exporter: DatadogLogExporter | None = None) -> DatadogLogClient

A batching :class:DatadogLogClient over :attr:exporter (or exporter).

The resource defaults to the configured service, version, env and hostname (resource keys win). :meth:close flushes and closes every log client created here.

new_exporter

new_exporter(*, max_entries_per_request: int | None = None, max_payload_bytes: int | None = None, max_log_bytes: int | None = None) -> DatadogLogExporter

An intake exporter with smaller request limits (values above Datadog's are capped).

ping

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

Authenticated round trip GET /api/v1/validate; returns the latency in ms.

403 -> :class:AuthenticationError; a 2xx without {"valid": true} -> :class:UnavailableError.

query

query() -> DatadogLogsQuery

The query client (search, aggregate, indexes); :class:ConfigError without app key.

server_version

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

Datadog is a SaaS without a version endpoint: always raises :class:UnsupportedError.

validate_api_key

validate_api_key(*, cancel: CancelToken | None = None) -> bool

Whether the API key is valid: True for {"valid": true}, False for 403.

Other failures raise the mapped error.

DatadogLogsConfig dataclass

Bases: BaseConfig

Immutable settings for :class:~grow_datadog_logs.DatadogLogsClient.

Common fields (timeouts, retry, tls, proxy, headers, user_agent_suffix, hooks, logger) come from :class:BaseConfig; durations are float seconds (datetime.timedelta accepted). api_key and app_key accept str and are stored as :class:Secret; repr() never shows them.

The intake and API base URLs are derived from site; url overrides both (tests, proxies, fakeintake) and intake_url / api_url override one each. After construction intake_url and api_url hold the resolved values and url is the given url or else the API base. Build a new config (instead of :func:dataclasses.replace) to change the site.

validate() raises :class:ConfigError for an unknown site (unless both base URLs are set), non-http(s) URLs, a missing or blank api_key and a blank app_key.

from_env classmethod

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

Build from the environment, then validate.

Precedence: explicit keyword > GROW_DATADOG_LOGS_<NAME> > Datadog variable (DD_API_KEY, DD_SITE …) > default. environ defaults to os.environ; pass a dict in tests. Keyword overrides with the value None are ignored.

validate

validate() -> _C

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

DatadogLogsPage dataclass

One page of :meth:DatadogLogsQuery.search_logs.

records property

records: list[LogRecord]

The events normalized to :class:LogRecord.

DatadogLogsQuery

Bases: _QueryBase, BaseLogQueryClient

Synchronous Datadog Logs query client (needs app_key).

Create it with :meth:DatadogLogsClient.query. Every I/O method accepts cancel=.

aggregate_logs

aggregate_logs(compute: DatadogCompute | Mapping[str, Any] | Sequence[DatadogCompute | Mapping[str, Any]], group_by: Sequence[DatadogGroupBy | Mapping[str, Any]] = (), *, query: str | None = None, from_: DatadogTime | None = None, to: DatadogTime | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None, cancel: CancelToken | None = None) -> DatadogAggregateResult

POST /api/v2/logs/analytics/aggregate.

Computes compute (one or a list; results keyed c0, c1 …) over the logs matching the filter, optionally grouped by facets.

q.aggregate_logs(DatadogCompute("count"), [DatadogGroupBy("service")]) # doctest: +SKIP

iterate_logs

iterate_logs(query: str | None = None, *, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, page_size: int | None = None, sort: LogsSort | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None, cancel: CancelToken | None = None) -> Iterator[DatadogLogEvent]

Iterate over every matching event across pages (cursor pagination).

limit caps the total number of events (default: all), page_size the events per request (default min(limit, 1000)). A repeated cursor raises :class:UnavailableError (protocol loop guard).

list_indexes

list_indexes(*, cancel: CancelToken | None = None) -> list[DatadogLogIndex]

Log indexes from GET /api/v1/logs/config/indexes (needs logs_read_config).

list_labels

list_labels() -> list[str]

Datadog has no public API that lists log attributes: raises :class:UnsupportedError.

list_streams

list_streams() -> list[str]

Index names (see :meth:list_indexes).

search

search(query: str, *, start: datetime | None = None, end: datetime | None = None, limit: int = 100, order: SearchOrder = 'desc', cursor: str | None = None) -> DatadogLogSearchResult

Category search: one page of :meth:search_logs.

start/end -> from/to, order -> sort, cursor -> page.cursor. total is never set (Datadog returns none).

search_logs

search_logs(query: str | None = None, *, from_: DatadogTime | None = None, to: DatadogTime | None = None, limit: int | None = None, sort: LogsSort | None = None, indexes: Sequence[str] | None = None, storage_tier: StorageTier | None = None, cursor: str | None = None, cancel: CancelToken | None = None) -> DatadogLogsPage

One page of POST /api/v2/logs/events/search.

from_/to default to now-15m/now, limit (1..5000) to 100, sort to -timestamp, indexes to ["*"]. Pass :attr:DatadogLogsPage.next_cursor back as cursor (with the same filter and sort) for the next page. A 200 without a data array raises :class:UnavailableError.

query.search_logs('service:checkout "run-7f3a"', from_="now-1h") # doctest: +SKIP

tail

tail(query: str, on_record: Callable[[LogRecord], None], *, interval_s: float | timedelta = DEFAULT_POLL_INTERVAL_S, start: datetime | None = None, on_error: Callable[[Exception], None] | None = None) -> PollingTail

Polling tail over :meth:search (Datadog Live Tail has no public API).

Polls every interval_s (default 5 s, the search API is rate limited) for records from start (default: now, like the other languages). :meth:DatadogLogsClient.close stops it.

wait_for_log

wait_for_log(query: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = DEFAULT_POLL_INTERVAL_S, predicate: Callable[[LogRecord], bool] | None = None) -> LogRecord

Poll :meth:search until a record matches (default interval 5 s, timeout 30 s).

Authentication and validation errors propagate at once; :class:TimeoutError at the deadline.

DatadogSiteUrls dataclass

The two base URLs of a Datadog site.

DatadogTimeseriesPoint dataclass

One point of a timeseries compute.

DatadogWarning dataclass

A non-fatal warning of a query (results may be partial).

EncodedBatch dataclass

Result of :meth:DatadogLogExporter.encode.

EntryDefaults dataclass

Values used when a record's resource does not carry them (from the client config).

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.

ExportResult dataclass

Outcome of one :meth:LogExporter.export call.

retries is a Python extension: the number of transport retries the export needed (summed into BatchStats.retries).

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.

IntakePayload dataclass

One intake request body before compression.

LogClient

Bases: Protocol

Synchronous log client (SPEC LogClient).

LogExporter

Bases: Protocol

Synchronous exporter, called from the :class:BatchProcessor worker thread.

export sends one batch and reports how many records the service accepted. It may raise an SDK error instead of returning ExportResult(error=...); both count as failed records. timeout_s is the per-batch export budget the exporter should pass to its transport.

LogHandler

Bases: Handler

:class:logging.Handler that forwards records to a log client.

Attributes: extra= fields, logger.name, code.filepath/code.function/ code.lineno, thread.name and exception.* for exc_info. Records from loggers in exclude_loggers (prefix match; defaults to the HTTP stack the exporters use) and from the SDK's own worker threads are skipped to avoid feedback loops. When a formatter is set, the formatted text is the body; otherwise record.getMessage().

LogInput dataclass

Convenience input for :meth:LogClient.send; defaults are filled by the client.

LogQueryClient

Bases: Protocol

Synchronous query API. Services without a query API raise UnsupportedError.

LogRecord dataclass

One log record (OTel log data model subset). Treat instances as immutable.

from_json classmethod

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

Parse the normalized wire form; raises ValidationError for malformed input.

json_size

json_size() -> int

UTF-8 byte size of the compact JSON form (used for maxBatchBytes).

to_json

to_json() -> dict[str, Any]

Normalized wire form (spec/schemas/log-record.schema.json, camelCase keys).

severity is the OTel number; timestamps are RFC 3339 UTC with microseconds.

to_json_str

to_json_str() -> str

Compact JSON text of :meth:to_json (UTF-8 safe, non-JSON values via str).

LogSearchResult dataclass

One page of search results.

LogSink

Bases: Protocol

Anything that accepts records: every log client.

Logger

Small structured logger writing to a :class:LogSink.

Records below min_severity are discarded. The sink fills timestamp, resource and trace correlation (the active OpenTelemetry span) for records without a trace id.

child

child(attributes: Mapping[str, AttrValue]) -> Logger

Logger with the same sink and level and the extra attributes.

LoggerLike

Bases: Protocol

Structured logger interface accepted in configuration (SPEC Logger).

NotFoundError

Bases: DatadogLogsError

Missing record (HTTP 404).

PermissionDeniedError

Bases: DatadogLogsError

Authenticated but not allowed (HTTP 403).

PollingTail

tail built on search: a daemon thread polls for records newer than the last one.

Errors go to on_error (default: ignored) and polling continues. :meth:stop is idempotent.

poll_once

poll_once() -> int

Run one poll; returns the number of delivered records.

RateLimitError

Bases: DatadogLogsError

Too many requests (HTTP 429); retry_after holds the requested delay when known.

RedactionProcessor

Returns redacted copies of records.

Attribute names containing one of keys (case-insensitive substring) get replacement as value, recursively through nested mappings and lists. patterns (regular expressions or their source strings) are replaced in the body and in every string attribute value. :class:Secret values are always replaced.

is_sensitive

is_sensitive(name: str) -> bool

True when an attribute name matches one of the keys.

process

process(record: LogRecord) -> LogRecord

Redacted copy of record (the input is never modified).

redact_attributes

redact_attributes(attributes: Mapping[str, AttrValue]) -> dict[str, AttrValue]

Redacted copy of an attribute mapping.

redact_text

redact_text(text: str) -> str

Apply every pattern to text.

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.

SerializedEntry dataclass

One serialized intake entry.

Severity

Bases: IntEnum

Log severity; the values are the OpenTelemetry severity numbers.

from_python_level classmethod

from_python_level(level: int) -> Severity

Map a :mod:logging level (WARNING → WARN, CRITICAL → FATAL).

parse classmethod

parse(value: Severity | int | str) -> Severity

Parse a severity name ("warn", "WARNING", "critical") or OTel number (1-24).

Numbers inside a band map to the band start (10 → INFO). Raises ValidationError for anything else.

TimeoutError

Bases: DatadogLogsError

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.

UnavailableError

Bases: DatadogLogsError

Network error or server unavailable (HTTP 500, 502, 503).

UnsupportedError

Bases: DatadogLogsError

The service or deployment does not offer this capability (HTTP 501, missing API).

ValidationError

Bases: DatadogLogsError

Bad input (HTTP 400, 413, 422, other 4xx, client-side validation).

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_wait_for_log async

async_wait_for_log(client: AsyncLogQueryClient, query: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = 1.0, predicate: RecordPredicate | None = None) -> LogRecord

Async form of :func:wait_for_log.

build_ddtags

build_ddtags(env: str | None, version: str | None, tags: Sequence[str] = ()) -> str | None

The ddtags value: env:, version:, then tags.

Comma-joined, de-duplicated, whitespace and commas inside a tag replaced by _. None when there is no tag.

current_trace_context

current_trace_context() -> tuple[str, str, int] | None

(trace_id, span_id, trace_flags) of the active OpenTelemetry span, if any.

datadog_id_to_hex

datadog_id_to_hex(value: Any, length: int) -> str | None

Convert a Datadog id (decimal of up to 64 bits, or lower hex) to hex padded to length.

Returns None for invalid or all-zero ids.

datadog_status

datadog_status(record: LogRecord) -> str

Datadog status of a record: its severity text lower-cased, else the severity name.

error_for_code

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

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.

event_to_log_record

event_to_log_record(event: DatadogLogEvent) -> LogRecord

Normalize a search event into a :class:LogRecord (API.md 6.1).

status -> severity; service/host/env:/version: tags -> resource; custom attributes plus datadog.log_id and datadog.tags; trace ids from otel.trace_id / otel.span_id, else from dd.trace_id / dd.span_id (decimal -> hex; only the lower 64 bits survive that way).

format_datadog_time

format_datadog_time(value: DatadogTime) -> str

Convert a :data:DatadogTime to the API form (ISO-8601 UTC with milliseconds).

Strings (ISO-8601 or date math) are sent as given (trimmed).

format_timestamp

format_timestamp(value: datetime) -> str

RFC 3339 UTC form with microseconds and Z; naive datetimes are taken as UTC.

get_logger

get_logger() -> logging.Logger

The package logger (LOGGER_NAME), silent by default (NullHandler).

is_datadog_site

is_datadog_site(site: str) -> bool

True when site (after :func:normalize_site) is a known Datadog site.

map_datadog_error

map_datadog_error(err: ServiceError) -> ServiceError

Map Datadog's 403 (:class:PermissionDeniedError) onto :class:AuthenticationError.

new_idempotency_key

new_idempotency_key() -> str

A random key for the Idempotency-Key header.

normalize_site

normalize_site(site: str) -> str

Lower-case and trim a site name.

parse_bool

parse_bool(text: str) -> bool

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

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_log_event

parse_log_event(item: Any) -> DatadogLogEvent | None

Parse one data[] item of a search response; None when it is not an object.

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.

parse_tags

parse_tags(value: str | Iterable[str] | None) -> tuple[str, ...]

Parse Datadog tags: key:value items separated by commas and/or whitespace.

Accepts one string (the DD_TAGS convention) or a list of strings. Empty items are dropped and duplicates removed; order is kept.

parse_tags("env:prod, team:sdk team:sdk") ('env:prod', 'team:sdk')

parse_timestamp

parse_timestamp(value: str) -> datetime

Parse RFC 3339 (any fraction precision, Z/offset; none = UTC) to aware UTC.

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.

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.

resolve_site

resolve_site(site: str = DEFAULT_SITE) -> DatadogSiteUrls

Resolve a site name to its intake and API base URLs.

Raises :class:ConfigError for an unknown site.

resolve_site("datadoghq.eu").intake_url 'https://http-intake.logs.datadoghq.eu'

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.

serialize_entry

serialize_entry(entry: Mapping[str, Any], max_bytes: int = MAX_LOG_BYTES) -> SerializedEntry | None

Serialize an entry to at most max_bytes UTF-8 bytes (DECISIONS 7).

An oversized entry gets its message cut at a character boundary and grow.truncated: true. Returns None when even an empty message does not fit (the metadata alone is too large).

severity_from_status

severity_from_status(status: str | None) -> Severity

OpenTelemetry severity of a Datadog status (unknown values map to INFO).

span_id_to_datadog

span_id_to_datadog(span_id: str | None) -> str | None

Datadog span-id form: decimal string of a 16-hex OpenTelemetry span id.

structlog_processor

structlog_processor(client: LogSink) -> StructlogProcessor

Return a structlog processor that sends every event to client.

The event dict passes through unchanged, so put this processor before the renderer. event becomes the body, level (or the method name) the severity, timestamp (TimeStamper output, epoch float or datetime) the timestamp; exc_info and a rendered exception become exception.* attributes; every other key is an attribute.

to_attr_value

to_attr_value(value: Any) -> AttrValue

Convert any Python value to an attribute value (unknown types become str(value)).

to_datadog_entry

to_datadog_entry(record: LogRecord, defaults: EntryDefaults | None = None) -> dict[str, Any]

Convert a :class:LogRecord into a Datadog intake entry (API.md 5.2).

message, timestamp (epoch ms), status, service, hostname, ddsource, ddtags, dd.trace_id / dd.span_id (decimal, DECISIONS 6) plus otel.trace_id / otel.span_id (lower hex, lossless), then the record attributes (other resource keys are not sent). User attributes named like a reserved key are prefixed with attr..

to_seconds

to_seconds(value: float | timedelta) -> float

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

trace_id_to_datadog

trace_id_to_datadog(trace_id: str | None) -> str | None

Datadog trace-id form (DECISIONS 6): decimal string of the lower 64 bits of a 32-hex id.

Returns None for invalid input.

trace_id_to_datadog("4bf92f3577b34da6a3ce929d0e0e4736") '11803532876627986230'

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.

wait_for_log

wait_for_log(client: LogQueryClient, query: str, *, timeout_s: float | timedelta = 30.0, interval_s: float | timedelta = 1.0, predicate: RecordPredicate | None = None) -> LogRecord

Poll client.search(query) until a record (matching predicate) shows up.