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 Better Stack Logs (unofficial; not affiliated with Better Stack, Inc.).

Ingest logs into a Better Stack source (HTTP ingest API with JSON / NDJSON / MessagePack, or OTLP/HTTP) and read them back through the SQL query API (ClickHouse HTTP interface).

from grow_better_stack_logs import BetterStackClient client = BetterStackClient.from_env() # doctest: +SKIP client.log_client().logger().info("hello") # 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).

BetterStackEvent module-attribute

BetterStackEvent = dict[str, Any]

One Better Stack event: a JSON object; dt is a :class:datetime until it is encoded.

LogProtocol module-attribute

LogProtocol = Literal['http', 'otlp']

Wire protocol of :meth:BetterStackClient.log_client: the HTTP ingest API or OTLP/HTTP.

QueryParamValue module-attribute

QueryParamValue: TypeAlias = str | int | float | bool | datetime | date | None

Value of a bound query parameter; None is sent as \N (NULL).

QueryRow module-attribute

QueryRow = dict[str, Any]

One result row (JSON object; ClickHouse quotes 64-bit integers as strings).

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

AsyncBetterStackClient

Asynchronous Better Stack Logs client; use async with or call :meth:aclose.

Same surface as :class:BetterStackClient with awaitable I/O. Cancel a call by cancelling its task: the SDK raises :class:CancelledError, which is also an :class:asyncio.CancelledError.

exporter property

exporter: AsyncBetterStackLogExporter

See :attr:BetterStackClient.exporter.

otlp_exporter property

otlp_exporter: AsyncBetterStackOtlpLogExporter

See :attr:BetterStackClient.otlp_exporter.

resources property

resources: ResourceRegistry

Background resources stopped by :meth:aclose.

aclose async

aclose() -> None

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

from_env classmethod

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

See :meth:BetterStackClient.from_env.

health async

health() -> HealthStatus

See :meth:BetterStackClient.health.

log_client

log_client(*, protocol: LogProtocol = 'http', exporter: AsyncLogExporter | None = None, options: BatchOptions | None = None, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True) -> AsyncBetterStackLogClient

See :meth:BetterStackClient.log_client; call it inside a running event loop.

new_exporter

new_exporter(*, encoding: IngestEncoding | None = None, max_request_bytes: int | None = None, max_record_bytes: int | None = None) -> AsyncBetterStackLogExporter

See :meth:BetterStackClient.new_exporter.

new_otlp_exporter

new_otlp_exporter(*, protocol: OtlpProtocol = 'protobuf', scope_name: str = DEFAULT_SCOPE_NAME, max_request_bytes: int | None = None) -> AsyncBetterStackOtlpLogExporter

See :meth:BetterStackClient.new_otlp_exporter.

ping async

ping() -> float

See :meth:BetterStackClient.ping.

query

query() -> AsyncBetterStackQuery

See :meth:BetterStackClient.query.

server_version async

server_version() -> str

See :meth:BetterStackClient.server_version (always unsupported).

AsyncBetterStackLogClient

Bases: AsyncBatchingLogClient

Async :class:BetterStackLogClient. Create it with :meth:AsyncBetterStackClient.log_client inside a running event loop.

AsyncBetterStackLogExporter

Bases: _IngestCore

Async :class:BetterStackLogExporter (an :class:AsyncLogExporter).

export async

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

See :meth:BetterStackLogExporter.export.

send_events async

send_events(events: Sequence[Mapping[str, Any]], *, encoding: IngestEncoding | None = None, gzip: bool = True) -> None

See :meth:BetterStackLogExporter.send_events.

shutdown async

shutdown() -> None

Nothing to release; the client owns the transport.

AsyncBetterStackOtlpLogExporter

Bases: _OtlpCore

Async :class:BetterStackOtlpLogExporter (an :class:AsyncLogExporter).

export async

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

See :meth:BetterStackOtlpLogExporter.export.

send async

send(records: Sequence[LogRecord], *, gzip: bool = True, timeout_s: float | None = None) -> OtlpPartialSuccess | None

See :meth:BetterStackOtlpLogExporter.send.

shutdown async

shutdown() -> None

Nothing to release; the client owns the transport.

AsyncBetterStackQuery

Bases: _QueryCore, AsyncBaseLogQueryClient

Async :class:BetterStackQuery. Get it from :meth:AsyncBetterStackClient.query.

list_labels async

list_labels() -> list[str]

See :meth:BetterStackQuery.list_labels.

list_streams async

list_streams() -> list[str]

See :meth:BetterStackQuery.list_streams.

query async

query(sql: str, params: Mapping[str, QueryParamValue] | None = None, *, settings: Mapping[str, str | int | float | bool] | None = None) -> list[QueryRow]

See :meth:BetterStackQuery.query.

query_raw async

query_raw(sql: str, params: Mapping[str, QueryParamValue] | None = None, *, settings: Mapping[str, str | int | float | bool] | None = None) -> str

See :meth:BetterStackQuery.query_raw.

search async

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

See :meth:BetterStackQuery.search.

search_logs async

search_logs(*, source: str | None = None, contains: str | None = None, start: datetime | None = None, end: datetime | None = None, limit: int = DEFAULT_SEARCH_LIMIT, order: SearchOrder = 'desc', cursor: str | None = None) -> LogSearchResult

See :meth:BetterStackQuery.search_logs.

tail async

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

See :meth:BetterStackQuery.tail; the polling task runs on the current loop.

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: BetterStackError

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

BetterStackClient

Synchronous Better Stack Logs client; thread-safe. Use it as a context manager or call :meth:close.

Ingestion goes to the source's ingesting host (:meth:log_client, :attr:exporter, :attr:otlp_exporter) and SQL to the query host (:meth:query), each with its own credentials and transport: a source token is never sent to the query host and SQL credentials never to the ingest host. I/O methods accept cancel= (a :class:CancelToken) to abort from another thread.

client = BetterStackClient.from_env() # doctest: +SKIP logs = client.log_client(resource={"service.name": "checkout"}) # doctest: +SKIP logs.logger().info("order placed", {"order_id": 42}) # doctest: +SKIP client.close() # doctest: +SKIP

exporter property

exporter: BetterStackLogExporter

The HTTP ingest exporter (config.encoding, default limits); needs the ingest side (:class:ConfigError otherwise).

otlp_exporter property

otlp_exporter: BetterStackOtlpLogExporter

The OTLP/HTTP protobuf logs exporter ({url}/v1/logs); needs the ingest side.

resources property

resources: ResourceRegistry

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

close

close() -> None

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

Later calls on the client (and on its exporters and query client) raise :class:CancelledError.

from_env classmethod

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

Build a client from GROW_BETTER_STACK_LOGS_*, BETTERSTACK_SOURCE_TOKEN, BETTERSTACK_INGESTING_HOST, BETTERSTACK_QUERY_* … variables.

health

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

Unauthenticated liveness; never raises for an unhealthy or unreachable service.

With a query host: GET {query_url}/ping (Ok.). Ingest-only: GET {url}/ without credentials; any answer below 500 proves the host is reachable and no data is sent. details["endpoint"] is "query" or "ingest".

log_client

log_client(*, protocol: LogProtocol = 'http', exporter: LogExporter | None = None, options: BatchOptions | None = None, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True) -> BetterStackLogClient

A batching :class:BetterStackLogClient over the HTTP ingest API (default) or OTLP.

exporter replaces the default one (for example :meth:new_exporter with another encoding); options.max_batch_bytes is capped at 10 MiB. :meth:close flushes and closes every log client it created. Needs the ingest side.

new_exporter

new_exporter(*, encoding: IngestEncoding | None = None, max_request_bytes: int | None = None, max_record_bytes: int | None = None) -> BetterStackLogExporter

An HTTP ingest exporter with its own encoding (default config.encoding) and limits (at most 10 MiB each).

new_otlp_exporter

new_otlp_exporter(*, protocol: OtlpProtocol = 'protobuf', scope_name: str = DEFAULT_SCOPE_NAME, max_request_bytes: int | None = None) -> BetterStackOtlpLogExporter

An OTLP exporter with its own payload format (protobuf or json), scope name and request limit.

ping

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

Authenticated round trip; returns the latency in milliseconds.

With query credentials: SELECT count() AS c FROM remote(<source_table>_logs) WHERE 1 = 0 (or SELECT 1 without a source_table). Ingest-only: posts an empty batch [] (no event is stored). Bad credentials raise :class:AuthenticationError.

query

query() -> BetterStackQuery

The SQL query client; :class:ConfigError without query credentials.

server_version

server_version() -> str

Always raises :class:UnsupportedError: Better Stack is a SaaS without a version endpoint (the query host's ClickHouse version is not a Better Stack version).

BetterStackConfig dataclass

Bases: BaseConfig

Immutable settings for :class:~grow_better_stack_logs.BetterStackClient.

Common fields (timeouts, retry, tls, proxy, headers, user_agent_suffix, hooks, logger) come from :class:BaseConfig and apply to both hosts. Durations are float seconds; datetime.timedelta is accepted. source_token and query_password accept a str and are stored as :class:Secret; repr() never shows them.

Fields (environment variables of :meth:from_env in precedence order after the explicit value):

  • url - ingest base URL, the source's ingesting host. A value without :// gets https://. Required for sending logs; there is no default host. GROW_BETTER_STACK_LOGS_URL, BETTERSTACK_INGESTING_URL, BETTERSTACK_INGESTING_HOST.
  • source_token - sent as Authorization: Bearer to the ingest host only. GROW_BETTER_STACK_LOGS_SOURCE_TOKEN, BETTERSTACK_SOURCE_TOKEN.
  • query_url - SQL query base URL (ClickHouse HTTP interface). GROW_BETTER_STACK_LOGS_QUERY_URL, BETTERSTACK_QUERY_URL, BETTERSTACK_QUERY_HOST.
  • query_username / query_password - HTTP Basic credentials of the SQL connection. GROW_BETTER_STACK_LOGS_QUERY_USERNAME / _QUERY_PASSWORD, BETTERSTACK_QUERY_USERNAME / BETTERSTACK_QUERY_PASSWORD.
  • source_table - default collection (t1234_myapp) for search, search_logs, tail and ping. GROW_BETTER_STACK_LOGS_SOURCE_TABLE, BETTERSTACK_SOURCE_TABLE.
  • encoding - ingest body encoding, json (default), ndjson or msgpack. GROW_BETTER_STACK_LOGS_ENCODING.

Common variables: CONNECT_TIMEOUT, REQUEST_TIMEOUT, TOTAL_TIMEOUT, MAX_RETRIES, CA_CERT, CLIENT_CERT, CLIENT_KEY, INSECURE_SKIP_VERIFY, PROXY (prefix GROW_BETTER_STACK_LOGS_).

has_ingest property

has_ingest: bool

Whether the ingest side (url + source_token) is configured.

has_query property

has_query: bool

Whether the SQL side (query_url + query_username + query_password) is set.

basic_credentials

basic_credentials() -> str | None

base64(username:password) for HTTP Basic, or None without query credentials.

common_config

common_config(url: str) -> BaseConfig

The common settings with url as base URL (one per host transport).

from_env classmethod

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

Build from the environment, then validate (raises :class:ConfigError).

Precedence: explicit keyword > GROW_BETTER_STACK_LOGS_<NAME> > vendor variables (BETTERSTACK_INGESTING_URL, BETTERSTACK_INGESTING_HOST, BETTERSTACK_SOURCE_TOKEN, BETTERSTACK_QUERY_URL, BETTERSTACK_QUERY_HOST, BETTERSTACK_QUERY_USERNAME, BETTERSTACK_QUERY_PASSWORD, BETTERSTACK_SOURCE_TABLE) > default. env defaults to os.environ.

known_secrets

known_secrets() -> list[str]

Credential values to redact from error messages and logs.

transport_config

transport_config(side: Literal['ingest', 'query']) -> BaseConfig

The common settings for one side's transport; :class:ConfigError when not set.

validate

validate() -> _C

Check the configuration; raises :class:ConfigError. Returns self.

The ingest set (url + source_token) and the query set (query_url + query_username + query_password) are each all-or-nothing and at least one is complete; URLs are absolute http(s) URLs; source_table is an identifier; encoding is json, ndjson or msgpack; the common rules hold.

BetterStackLogClient

Bases: BatchingLogClient

:class:LogClient that ships records to the source's ingesting host through a background :class:BatchProcessor. Create it with :meth:BetterStackClient.log_client.

BetterStackLogExporter

Bases: _IngestCore

:class:LogExporter for Better Stack's HTTP ingest API.

Maps records to events (:func:to_better_stack_event), splits batches so that no request exceeds 10 MiB, encodes them as JSON, NDJSON or MessagePack, gzips when asked and posts with Authorization: Bearer <source token>. Exports are retried like idempotent calls (429, 5xx, network errors); Better Stack does not deduplicate, so an ambiguous failure may store a record twice. Create it with :meth:BetterStackClient.new_exporter or use :attr:BetterStackClient.exporter.

export

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

Send the records; a failing request stops the export (later records count as rejected). Never raises for service errors.

send_events

send_events(events: Sequence[Mapping[str, Any]], *, encoding: IngestEncoding | None = None, gzip: bool = True, cancel: CancelToken | None = None) -> None

Post raw events (JSON objects; dt may be a :class:datetime, an RFC 3339 string or UNIX seconds/ms/ns) as one request, without splitting.

Raises the mapped SDK error: 403 → :class:AuthenticationError, 402 → :class:RateLimitError (not retryable), 406/413 → :class:ValidationError. cancel aborts the call from another thread.

shutdown

shutdown() -> None

Nothing to release; the client owns the transport.

BetterStackOtlpLogExporter

Bases: _OtlpCore

:class:LogExporter that sends OTLP/HTTP logs to the source's ingesting host (POST {url}/v1/logs) with the source token.

Records are grouped by resource; batches are split so that no request exceeds max_request_bytes. partial_success in the response counts as rejected records. Retried like idempotent calls (duplicates possible after an ambiguous failure).

export

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

Send the records; never raises for service errors (see :class:LogExporter).

send

send(records: Sequence[LogRecord], *, gzip: bool = True, timeout_s: float | None = None, cancel: CancelToken | None = None) -> OtlpPartialSuccess | None

Post one OTLP request for records; returns the partial success when the service reports rejected records. Raises the mapped SDK error.

shutdown

shutdown() -> None

Nothing to release; the client owns the transport.

BetterStackQuery

Bases: _QueryCore, BaseLogQueryClient

SQL query client for Better Stack Logs (sync). Get it from :meth:BetterStackClient.query; thread-safe.

Better Stack allows 4 concurrent log queries per account and suggests 1-2 s between calls, so polling helpers default to a 1 s interval.

list_labels

list_labels() -> list[str]

Always :class:UnsupportedError: Better Stack events are schemaless JSON.

list_streams

list_streams() -> list[str]

The configured collections ([source_table] or []); Better Stack's data plane has no listing endpoint.

query

query(sql: str, params: Mapping[str, QueryParamValue] | None = None, *, settings: Mapping[str, str | int | float | bool] | None = None, cancel: CancelToken | None = None) -> list[QueryRow]

Run SQL and return the rows.

Without a FORMAT clause FORMAT JSONEachRow is appended; FORMAT JSON / JSONEachRow (also with output_format_json_array_of_rows) are parsed, other formats raise :class:ValidationError (use :meth:query_raw). A ClickHouse exception appended to a 200 response raises the mapped error.

q.query( # doctest: +SKIP ... "SELECT count() AS c FROM remote(t1_app_logs) " ... "WHERE position(raw, {needle:String}) > 0", ... {"needle": "checkout"}, ... ) [{'c': '3'}]

query_raw

query_raw(sql: str, params: Mapping[str, QueryParamValue] | None = None, *, settings: Mapping[str, str | int | float | bool] | None = None, cancel: CancelToken | None = None) -> str

Run SQL and return the response body unchanged (any FORMAT).

params are bound server side: {name:Type} placeholders in sql + param_<name> URL parameters. settings are ClickHouse settings sent as URL parameters ({"max_execution_time": 30}). Errors map by ClickHouse exception code. cancel aborts the call from another thread (:class:CancelledError).

search

search(query: str, *, start: datetime | None = None, end: datetime | None = None, limit: int = DEFAULT_SEARCH_LIMIT, order: SearchOrder = 'desc', cursor: str | None = None, cancel: CancelToken | None = None) -> LogSearchResult

LogQueryClient.search: query is the contains text, searched in the configured source_table.

search_logs

search_logs(*, source: str | None = None, contains: str | None = None, start: datetime | None = None, end: datetime | None = None, limit: int = DEFAULT_SEARCH_LIMIT, order: SearchOrder = 'desc', cursor: str | None = None, cancel: CancelToken | None = None) -> LogSearchResult

Search the hot and cold logs of a collection (see :meth:render_search_sql).

source defaults to config.source_table; contains is a case-sensitive literal substring of the raw event JSON (JSON-escaped first, so it matches text inside string values); start/end are inclusive (default: the last 24 h, no upper bound); order is "desc" (newest first) or "asc". Rows are normalized (:func:log_record_from_row) and de-duplicated on (dt, raw); next_cursor is set when more rows exist.

tail

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

Poll :meth:search every interval_s for new records of source_table that contain query, starting at start (default now), and call on_record for each new record in dt order. Errors go to on_error and polling continues. Stop it with handle.stop(); :meth:BetterStackClient.close stops it too.

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

Invalid or missing configuration.

ConflictError

Bases: BetterStackError

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

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.

IngestPayload dataclass

One 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: BetterStackError

Missing record (HTTP 404).

OtlpPartialSuccess

Partial success reported by an OTLP response (rejected records, optional message).

PermissionDeniedError

Bases: BetterStackError

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: BetterStackError

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.

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.

SplitResult dataclass

Result of :meth:BetterStackLogExporter.split.

TimeoutError

Bases: BetterStackError

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: BetterStackError

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

UnsupportedError

Bases: BetterStackError

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

ValidationError

Bases: BetterStackError

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.

clickhouse_code

clickhouse_code(text: str) -> int | None

The ClickHouse exception code in text (Code: 60. DB::Exception: …), or None.

current_trace_context

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

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

encode_events

encode_events(events: Sequence[Any], encoding: IngestEncoding) -> bytes

Encode events as one request body.

json: a JSON array; ndjson: one object per line; msgpack: a MessagePack array with :class:datetime values as timestamp extensions (type -1).

encode_msgpack

encode_msgpack(value: Any) -> bytes

Encode a value as MessagePack (:class:datetime → timestamp extension, bytes → bin).

encode_otlp_protobuf

encode_otlp_protobuf(records: Sequence[LogRecord], scope_name: str = DEFAULT_SCOPE_NAME) -> bytes

Encode an ExportLogsServiceRequest (collector/logs/v1) as protobuf bytes.

Records are grouped by resource; trace/span ids are hex strings in the record and bytes on the wire. Raises :class:ValidationError for a record that cannot be encoded.

encoded_event_size

encoded_event_size(event: Any, encoding: IngestEncoding) -> int

Encoded size of one event inside a body of encoding (separators included).

error_for_clickhouse_code

error_for_clickhouse_code(code: int, message: str, *, http_status: int | None = None, request_id: str | None = None) -> BetterStackError | None

The SDK error for a ClickHouse exception code, or None when the code has no mapping.

516/192/193/194 → authentication, 497 → permission denied, 60/81 → not found, 62/47/46/36/53/42/73/456/457 → validation, 241 (memory limit) → validation with a hint, 48 → unsupported, 159/160 → timeout, 202 (too many simultaneous queries) → rate limited (retryable).

error_for_code

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

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.

escape_param_value

escape_param_value(value: str) -> str

Escape a param_<name> value for ClickHouse (DECISIONS §12).

ClickHouse parses query parameter values in the escaped (TabSeparated) text format, so a backslash becomes \\, tab \t, newline \n and carriage return \r. Applied to every str parameter by :meth:BetterStackQuery.query.

event_json

event_json(event: Any) -> str

Compact JSON text of one event (:class:datetime → RFC 3339 UTC).

format_datetime64

format_datetime64(value: datetime) -> str

YYYY-MM-DD HH:MM:SS.ffffff (UTC), the DateTime64(6) text form; naive = UTC.

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_valid_identifier

is_valid_identifier(value: str) -> bool

Whether value is a safe ClickHouse identifier (^[A-Za-z_][A-Za-z0-9_]*$).

json_escape

json_escape(text: str) -> str

JSON string escaping without the surrounding quotes (quote, backslash, control characters), as the text appears inside raw event JSON.

log_record_from_row

log_record_from_row(row: Mapping[str, Any]) -> LogRecord

Normalize a {dt, raw} row to a :class:LogRecord (API.md §5.3).

body = message (else msg, else the raw text); severity from severity_number, else level / severity text (default INFO); timestamp = dt; trace ids from span.trace_id / span.span_id (or top-level trace_id / span_id, hex only); resource = resource; every other key plus the attributes object into attributes.

map_ingest_error

map_ingest_error(err: BaseException) -> BaseException

Map an ingest-host error: 403 → :class:AuthenticationError, 402 → non-retryable :class:RateLimitError. Anything else is returned unchanged.

map_query_error

map_query_error(err: BaseException) -> BaseException

Map an SQL-host error by the ClickHouse code found in its message, else keep it.

new_idempotency_key

new_idempotency_key() -> str

A random key for the Idempotency-Key header.

normalize_base_url

normalize_base_url(value: str | None) -> str

Normalize a host or URL.

A value containing :// is used as given, a bare host[:port] becomes https://host[:port]; trailing slashes are removed. None and blank input give "".

otlp_json_request

otlp_json_request(records: Sequence[LogRecord], scope_name: str = DEFAULT_SCOPE_NAME) -> dict[str, Any]

The OTLP JSON ExportLogsServiceRequest object (ids as hex, 64-bit ints as strings).

parse_bool

parse_bool(text: str) -> bool

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

parse_datetime

parse_datetime(value: Any) -> datetime | None

Parse a DateTime64 text (2026-11-18 21:00:00.123456, UTC, 0-9 fraction digits), an RFC 3339 string or UNIX seconds/milliseconds. Returns aware UTC or None.

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_partial_success

parse_partial_success(body: bytes | Mapping[str, Any]) -> OtlpPartialSuccess | None

Read partial_success from an ExportLogsServiceResponse (protobuf bytes or a JSON object). None when nothing was rejected or the body cannot be read.

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_rows

parse_rows(text: str) -> list[QueryRow]

Parse a JSON-family response body (JSONEachRow, JSON, a JSON array) into rows.

A ClickHouse exception appended to a 200 response (Code: N. DB::Exception) raises the mapped error; any other unparseable line raises :class:UnavailableError.

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.

query_error_from_response

query_error_from_response(resp: Response, operation: str, known_secrets: list[str]) -> BetterStackError

The SDK error for a failed SQL response (status ≥ 400): the HTTP status mapping, replaced by the ClickHouse exception code mapping when the code has one.

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.

sql_string

sql_string(value: str) -> str

value as a single-quoted ClickHouse string literal (backslash, quote, newline, carriage return, tab and NUL escaped with a backslash).

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_better_stack_event

to_better_stack_event(record: LogRecord) -> BetterStackEvent

Map a :class:LogRecord to the Better Stack event shape.

{dt, message, level, severity_number, span: {trace_id, span_id}, trace_flags, resource, attributes, observed_dt}. span.trace_id/span.span_id are Better Stack's log ↔ trace correlation fields. Empty resource/attributes are left out.

to_seconds

to_seconds(value: float | timedelta) -> float

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

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.