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
¶
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 ¶
Queue without blocking; False when dropped (block acts as drop_newest here).
add_wait
async
¶
Queue a record, waiting for queue space with drop_policy="block".
flush
async
¶
Export everything queued now; raises TimeoutError when timeout_s passes first.
shutdown
async
¶
Drain (bounded by timeout_s), stop the task, shut the exporter down; idempotent.
AsyncBatchingLogClient ¶
Bases: _ClientBase
:class:AsyncLogClient over an :class:AsyncLogExporter + :class:AsyncBatchProcessor.
AsyncDatadogLogClient ¶
Bases: AsyncBatchingLogClient
Async :class:DatadogLogClient; create it with :meth:AsyncDatadogLogsClient.log_client.
AsyncDatadogLogExporter ¶
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
¶
The intake exporter (one per client, Datadog limits).
aclose
async
¶
Flush and close every log client, stop tails and release connections (idempotent).
from_env
classmethod
¶
Build a client from the environment (see :meth:DatadogLogsConfig.from_env).
health
async
¶
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
¶
Authenticated round trip GET /api/v1/validate; returns the latency in ms.
server_version
async
¶
Always raises :class:UnsupportedError (Datadog reports no server version).
validate_api_key
async
¶
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
¶
Log indexes from GET /api/v1/logs/config/indexes (needs logs_read_config).
list_labels
async
¶
Always raises :class:UnsupportedError (no Datadog API lists log attributes).
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 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").
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.
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
¶
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 ¶
Queue a record; False when it was dropped. Blocks only with drop_policy="block".
flush ¶
Export everything queued now; raises TimeoutError when timeout_s passes first.
shutdown ¶
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.
CancelToken ¶
Thread-safe cancellation flag passed to sync calls as cancel=.
Cancelling interrupts an in-flight request (the call returns immediately with
:class:CancelledError; the abandoned HTTP exchange finishes in the background) and any
retry backoff sleep.
CancelledError ¶
Bases: 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
¶
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 ¶
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 ¶
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 ¶
Post one JSON array body to the intake; returns the transport retries used.
Raises the mapped SDK error.
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
¶
The intake exporter (one per client, Datadog limits).
resources
property
¶
Background resources (tails) stopped by :meth:close.
close ¶
Flush and close every log client, stop tails and release connections (idempotent).
from_env
classmethod
¶
Build a client from GROW_DATADOG_LOGS_*, DD_API_KEY, DD_SITE … variables.
health ¶
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 ¶
Authenticated round trip GET /api/v1/validate; returns the latency in ms.
403 -> :class:AuthenticationError; a 2xx without {"valid": true} ->
:class:UnavailableError.
query ¶
The query client (search, aggregate, indexes); :class:ConfigError without app key.
server_version ¶
Datadog is a SaaS without a version endpoint: always raises :class:UnsupportedError.
validate_api_key ¶
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
¶
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 ¶
Common checks plus the Datadog rules; raises :class:ConfigError. Returns self.
DatadogLogsPage
dataclass
¶
One page of :meth:DatadogLogsQuery.search_logs.
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 ¶
Log indexes from GET /api/v1/logs/config/indexes (needs logs_read_config).
list_labels ¶
Datadog has no public API that lists log attributes: raises :class:UnsupportedError.
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.
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 (orNoneto keep the default). The mapped error is whatHooks.on_error, the retry planner (retry_after) and the caller see; whether a status is retried stays the SPEC rule. Exceptions raised by the mapper are logged and ignored.
Every call after :meth:close raises :class:CancelledError ("client is closed").
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
¶
Parse the normalized wire form; raises ValidationError for malformed input.
to_json ¶
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 ¶
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 ¶
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.
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.
Request
dataclass
¶
One logical API call (possibly several attempts).
path is joined to the base URL ({name} style values must already be encoded; use
:func:urllib.parse.quote); an absolute http:///https:// URL is used as is (for
pagination links the service returns; the default headers, config.headers included,
are sent there too, so only pass URLs of the same service). json is encoded when not
None; content sends raw bytes. idempotent overrides the method rule; an
idempotency_key sends the Idempotency-Key header and marks the request idempotent.
raise_for_status=False returns error responses instead of raising (retries still
apply). Statuses in allow_status are expected answers (a 404 that carries data, a
health endpoint's 503): the response is returned at once, like a success, without retries
or on_error.
RequestInfo
dataclass
¶
Passed to Hooks.on_request; url and headers are redacted.
ResourceRegistry ¶
Holds :class:Stoppable objects; :meth:stop_all stops each once, ignoring errors.
register ¶
Track item; when the registry is already closed the item is stopped now.
Response
dataclass
¶
A completed HTTP response (body fully read).
ResponseInfo
dataclass
¶
Passed to Hooks.on_response; headers are the redacted response headers (rate
limit headers and the like stay readable).
RetryPolicy
dataclass
¶
Retry settings. Durations are seconds (datetime.timedelta is accepted).
Backoff for retry n (0-based) is full jitter:
random(0, min(max_backoff, initial_backoff * multiplier ** n)).
random returns a float in [0, 1); inject it in tests for deterministic sleeps.
Secret ¶
Wraps a credential so it never shows up in str/repr/logs.
s = Secret("hunter2") str(s), s.reveal() ('[REDACTED]', 'hunter2')
SerializedEntry
dataclass
¶
One serialized intake entry.
Severity ¶
Bases: IntEnum
Log severity; the values are the OpenTelemetry severity numbers.
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 ¶
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 ¶
(trace_id, span_id, trace_flags) of the active OpenTelemetry span, if any.
datadog_id_to_hex ¶
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 of a record: its severity text lower-cased, else the severity name.
error_for_code ¶
Return the error class for a code (ErrorCode member or wire value).
error_from_status ¶
error_from_status(status: int, operation: str, *, content: bytes = b'', headers: Headers | None = None, known_secrets: list[str] | None = None, retry_after: float | None = None, request_id_headers: Sequence[str] = ()) -> ServiceError
Map an HTTP error status to the SPEC 2.1 error with a redacted, truncated message.
request_id_headers are checked before the default :data:REQUEST_ID_HEADERS.
event_to_log_record ¶
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 ¶
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 ¶
RFC 3339 UTC form with microseconds and Z; naive datetimes are taken as UTC.
get_logger ¶
The package logger (LOGGER_NAME), silent by default (NullHandler).
is_datadog_site ¶
True when site (after :func:normalize_site) is a known Datadog site.
map_datadog_error ¶
Map Datadog's 403 (:class:PermissionDeniedError) onto :class:AuthenticationError.
parse_bool ¶
Parse true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.
parse_duration ¶
Parse a duration into seconds.
Accepts integer milliseconds ("1500" → 1.5) or Go-style units ("500ms", "10s",
"2m", "1h", "1m30s"). Raises :class:ValueError for anything else.
parse_log_event ¶
Parse one data[] item of a search response; None when it is not an object.
parse_retry_after ¶
Parse Retry-After as delta seconds or an HTTP-date; return seconds (>= 0) or None.
parse_tags ¶
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 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 ¶
Recursively redact values whose key looks sensitive in nested mappings and lists.
redact_headers ¶
Copy of headers with sensitive values replaced by [REDACTED].
redact_text ¶
Replace every known secret value (length >= 4) in text with [REDACTED].
redact_url ¶
Redact user info and every query value (all values, not only sensitive ones).
Query names are kept so the URL stays useful in logs.
resolve_site ¶
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 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 ¶
OpenTelemetry severity of a Datadog status (unknown values map to INFO).
span_id_to_datadog ¶
Datadog span-id form: decimal string of a 16-hex OpenTelemetry span id.
structlog_processor ¶
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 ¶
Convert any Python value to an attribute value (unknown types become str(value)).
to_datadog_entry ¶
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 ¶
Normalise a duration given as float seconds or :class:datetime.timedelta.
trace_id_to_datadog ¶
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 to limit characters (adds an ellipsis when cut).
user_agent ¶
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.