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
¶
Attribute value: scalar, list of values or nested mapping (OTel AnyValue without bytes).
BetterStackEvent
module-attribute
¶
One Better Stack event: a JSON object; dt is a :class:datetime until it is encoded.
LogProtocol
module-attribute
¶
Wire protocol of :meth:BetterStackClient.log_client: the HTTP ingest API or OTLP/HTTP.
QueryParamValue
module-attribute
¶
Value of a bound query parameter; None is sent as \N (NULL).
QueryRow
module-attribute
¶
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 ¶
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.
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.
otlp_exporter
property
¶
See :attr:BetterStackClient.otlp_exporter.
aclose
async
¶
Flush and close every log client, stop tails and close connections (idempotent).
from_env
classmethod
¶
See :meth:BetterStackClient.from_env.
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.
server_version
async
¶
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).
AsyncBetterStackOtlpLogExporter ¶
Bases: _OtlpCore
Async :class:BetterStackOtlpLogExporter (an :class:AsyncLogExporter).
AsyncBetterStackQuery ¶
Bases: _QueryCore, AsyncBaseLogQueryClient
Async :class:BetterStackQuery. Get it from :meth:AsyncBetterStackClient.query.
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").
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.
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.
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
¶
The HTTP ingest exporter (config.encoding, default limits); needs the ingest
side (:class:ConfigError otherwise).
otlp_exporter
property
¶
The OTLP/HTTP protobuf logs exporter ({url}/v1/logs); needs the ingest side.
resources
property
¶
Background resources (tails) stopped by :meth:close.
close ¶
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
¶
Build a client from GROW_BETTER_STACK_LOGS_*, BETTERSTACK_SOURCE_TOKEN,
BETTERSTACK_INGESTING_HOST, BETTERSTACK_QUERY_* … variables.
health ¶
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 ¶
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 ¶
The SQL query client; :class:ConfigError without query credentials.
server_version ¶
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://getshttps://. Required for sending logs; there is no default host.GROW_BETTER_STACK_LOGS_URL,BETTERSTACK_INGESTING_URL,BETTERSTACK_INGESTING_HOST.source_token- sent asAuthorization: Bearerto 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) forsearch,search_logs,tailandping.GROW_BETTER_STACK_LOGS_SOURCE_TABLE,BETTERSTACK_SOURCE_TABLE.encoding- ingest body encoding,json(default),ndjsonormsgpack.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_query
property
¶
Whether the SQL side (query_url + query_username + query_password) is set.
basic_credentials ¶
base64(username:password) for HTTP Basic, or None without query credentials.
common_config ¶
The common settings with url as base URL (one per host transport).
from_env
classmethod
¶
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 ¶
Credential values to redact from error messages and logs.
transport_config ¶
The common settings for one side's transport; :class:ConfigError when not set.
validate ¶
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 ¶
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.
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 ¶
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.
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 ¶
Always :class:UnsupportedError: Better Stack events are schemaless JSON.
list_streams ¶
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.
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.
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").
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
¶
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: 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.
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.
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')
Severity ¶
Bases: IntEnum
Log severity; the values are the OpenTelemetry severity numbers.
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 ¶
The ClickHouse exception code in text (Code: 60. DB::Exception: …), or None.
current_trace_context ¶
(trace_id, span_id, trace_flags) of the active OpenTelemetry span, if any.
encode_events ¶
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 a value as MessagePack (:class:datetime → timestamp extension, bytes → bin).
encode_otlp_protobuf ¶
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 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 ¶
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 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 ¶
Compact JSON text of one event (:class:datetime → RFC 3339 UTC).
format_datetime64 ¶
YYYY-MM-DD HH:MM:SS.ffffff (UTC), the DateTime64(6) text form; naive = UTC.
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_valid_identifier ¶
Whether value is a safe ClickHouse identifier (^[A-Za-z_][A-Za-z0-9_]*$).
json_escape ¶
JSON string escaping without the surrounding quotes (quote, backslash, control characters), as the text appears inside raw event JSON.
log_record_from_row ¶
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 an ingest-host error: 403 → :class:AuthenticationError, 402 → non-retryable
:class:RateLimitError. Anything else is returned unchanged.
map_query_error ¶
Map an SQL-host error by the ClickHouse code found in its message, else keep it.
normalize_base_url ¶
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 true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.
parse_datetime ¶
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 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 ¶
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 as delta seconds or an HTTP-date; return seconds (>= 0) or None.
parse_rows ¶
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 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 ¶
Recursively redact values whose key looks sensitive in nested mappings and lists.
redact_headers ¶
Copy of headers with sensitive values replaced by [REDACTED].
redact_text ¶
Replace every known secret value (length >= 4) in text with [REDACTED].
redact_url ¶
Redact user info and every query value (all values, not only sensitive ones).
Query names are kept so the URL stays useful in logs.
retry_after_from_headers ¶
retry_after_from_headers(headers: Headers | Mapping[str, str], names: Sequence[str] = RETRY_AFTER_HEADERS, *, now: Callable[[], float] = time.time) -> float | None
Server requested delay in seconds from the first of names that parses.
Retry-After is delta seconds or an HTTP-date. Other headers (X-RateLimit-Reset,
RateLimit-Reset …) may be delta seconds or a Unix timestamp in seconds or milliseconds;
timestamps are turned into the remaining delay.
sql_string ¶
value as a single-quoted ClickHouse string literal (backslash, quote, newline,
carriage return, tab and NUL escaped with a backslash).
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_better_stack_event ¶
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 ¶
Normalise a duration given as float seconds or :class:datetime.timedelta.
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.