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 Amazon CloudWatch Logs, built on the official AWS SDK for Python.

from grow_aws_cloudwatch_logs import CloudWatchLogsClient client = CloudWatchLogsClient.from_env() # doctest: +SKIP client.ensure_log_group("my-app/prod", retention_days=30) # doctest: +SKIP

AttrValue module-attribute

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

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

AsyncBaseLogQueryClient

Async :class:BaseLogQueryClient.

AsyncBatchProcessor

Bases: _BatchCore

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

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

add

add(record: LogRecord) -> bool

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

add_wait async

add_wait(record: LogRecord) -> bool

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

flush async

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

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

shutdown async

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

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

AsyncBatchingLogClient

Bases: _ClientBase

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

close async

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

Flush and shut down; idempotent.

send_wait async

send_wait(record: LogRecord | LogInput) -> bool

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

AsyncCloudWatchLogsClient

Bases: _Base

Asynchronous Amazon CloudWatch Logs client (aioboto3 / aiobotocore); use async with or call :meth:aclose. Same methods as :class:CloudWatchLogsClient, awaited; iterator methods return async iterators.

Cancel a call by cancelling its task: the SDK raises :class:CancelledError, which is also an :class:asyncio.CancelledError.

aclose async

aclose() -> None

Flush and close log clients, stop live-tail sessions and release connections. Idempotent; never closes a caller-supplied SDK client.

delete_log_group async

delete_log_group(name: str, *, ignore_missing: bool = False) -> bool

See :meth:CloudWatchLogsClient.delete_log_group.

delete_log_stream async

delete_log_stream(group: str, stream: str, *, ignore_missing: bool = False) -> bool

See :meth:CloudWatchLogsClient.delete_log_stream.

describe_log_groups

describe_log_groups(*, prefix: str | None = None, page_size: int | None = None, limit: int | None = None) -> AsyncIterator[LogGroupInfo]

See :meth:CloudWatchLogsClient.describe_log_groups (async iterator).

describe_log_streams

describe_log_streams(group: str, *, prefix: str | None = None, order_by: Literal['LogStreamName', 'LastEventTime'] | None = None, descending: bool | None = None, page_size: int | None = None, limit: int | None = None) -> AsyncIterator[LogStreamInfo]

See :meth:CloudWatchLogsClient.describe_log_streams (async iterator).

describe_queries async

describe_queries(*, group: str | None = None, status: str | None = None, max_results: int | None = None) -> list[QueryInfo]

See :meth:CloudWatchLogsClient.describe_queries.

emf async

emf(metric: str, value: float | Sequence[float], dimensions: Mapping[str, str] | None = None, *, namespace: str = DEFAULT_EMF_NAMESPACE, unit: str = 'None', timestamp: datetime | int | None = None, properties: Mapping[str, str | int | float | bool] | None = None, group: str | None = None, stream: str | None = None) -> dict[str, Any]

See :meth:CloudWatchLogsClient.emf.

ensure_log_group async

ensure_log_group(name: str, *, retention_days: int | None = None, kms_key_id: str | None = None, tags: Mapping[str, str] | None = None) -> EnsureLogGroupResult

See :meth:CloudWatchLogsClient.ensure_log_group.

ensure_log_stream async

ensure_log_stream(group: str, stream: str, *, create_group: bool = False) -> EnsureLogStreamResult

See :meth:CloudWatchLogsClient.ensure_log_stream.

exporter

exporter(*, group: str | None = None, stream: str | None = None, create_group: bool = False) -> AsyncCloudWatchLogsExporter

See :meth:CloudWatchLogsClient.exporter.

filter_log_events

filter_log_events(*, group: str | None = None, streams: Sequence[str] | None = None, stream_prefix: str | None = None, pattern: str | None = None, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, limit: int | None = None) -> AsyncIterator[FilteredLogEvent]

See :meth:CloudWatchLogsClient.filter_log_events (async iterator).

filter_log_events_page async

filter_log_events_page(*, group: str | None = None, streams: Sequence[str] | None = None, stream_prefix: str | None = None, pattern: str | None = None, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, next_token: str | None = None) -> FilterLogEventsPage

See :meth:CloudWatchLogsClient.filter_log_events_page.

from_env classmethod

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

Build a client from GROW_AWS_CLOUDWATCH_LOGS_* and the standard AWS variables.

get_log_events

get_log_events(group: str, stream: str, *, start_from_head: bool = False, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, limit: int | None = None) -> AsyncIterator[StreamLogEvent]

See :meth:CloudWatchLogsClient.get_log_events (async iterator).

get_log_group async

get_log_group(name: str) -> LogGroupInfo | None

See :meth:CloudWatchLogsClient.get_log_group.

get_query_results async

get_query_results(query_id: str) -> QueryResults

See :meth:CloudWatchLogsClient.get_query_results.

get_region async

get_region() -> str | None

The effective AWS region.

get_sdk async

get_sdk() -> Any

The underlying aiobotocore logs client (created on first use).

health async

health() -> HealthStatus

See :meth:CloudWatchLogsClient.health.

list_log_group_tags async

list_log_group_tags(name: str) -> dict[str, str]

See :meth:CloudWatchLogsClient.list_log_group_tags.

log_client

log_client(*, group: str | None = None, stream: str | None = None, create_group: bool = False, options: BatchOptions | None = None, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True) -> AsyncBatchingLogClient

See :meth:CloudWatchLogsClient.log_client (an AsyncBatchingLogClient).

log_group_arn async

log_group_arn(name: str) -> str

See :meth:CloudWatchLogsClient.log_group_arn.

log_query_client

log_query_client(*, group: str | None = None) -> AsyncCloudWatchLogsQueryClient

See :meth:CloudWatchLogsClient.log_query_client.

ping async

ping() -> float

See :meth:CloudWatchLogsClient.ping.

put_log_events async

put_log_events(group: str, stream: str, events: Iterable[InputLogEvent | Mapping[str, Any]], *, auto_create: bool | None = None, create_group: bool = False, max_event_bytes: int | None = None, oversize_policy: str | None = None) -> PutLogEventsResult

See :meth:CloudWatchLogsClient.put_log_events.

put_retention_policy async

put_retention_policy(group: str, days: int | None) -> None

See :meth:CloudWatchLogsClient.put_retention_policy.

query async

query(query_string: str, *, groups: Sequence[str] | None = None, start: TimeInput | None = None, end: TimeInput | None = None, limit: int | None = None, timeout_s: float | timedelta = 60.0, poll_interval_s: float | timedelta = 1.0, retry_on_query_limit: int = 3) -> QueryResults

See :meth:CloudWatchLogsClient.query.

server_version async

server_version() -> str

Always :class:UnsupportedError (CloudWatch Logs exposes no server version).

start_live_tail async

start_live_tail(groups: Sequence[str], on_event: Callable[[LiveTailEvent], None], *, streams: Sequence[str] | None = None, stream_prefixes: Sequence[str] | None = None, pattern: str | None = None, on_update: Callable[[LiveTailUpdate], None] | None = None, on_error: Callable[[CloudWatchLogsError], None] | None = None) -> AsyncLiveTailSession

See :meth:CloudWatchLogsClient.start_live_tail; the session is read by a task on the running event loop.

start_query async

start_query(query_string: str, *, groups: Sequence[str] | None = None, start: TimeInput | None = None, end: TimeInput | None = None, limit: int | None = None) -> str

See :meth:CloudWatchLogsClient.start_query.

stop_query async

stop_query(query_id: str) -> bool

See :meth:CloudWatchLogsClient.stop_query.

tag_log_group async

tag_log_group(name: str, tags: Mapping[str, str]) -> None

See :meth:CloudWatchLogsClient.tag_log_group.

untag_log_group async

untag_log_group(name: str, keys: Iterable[str]) -> None

See :meth:CloudWatchLogsClient.untag_log_group.

AsyncCloudWatchLogsExporter

Async :class:CloudWatchLogsExporter for :class:AsyncCloudWatchLogsClient.

export async

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

Send one batch; ExportResult.rejected counts oversized and rejected records.

shutdown async

shutdown() -> None

Nothing to release (the client owns the connection).

AsyncCloudWatchLogsQueryClient

Bases: AsyncBaseLogQueryClient

Async :class:CloudWatchLogsQueryClient for :class:AsyncCloudWatchLogsClient.

list_streams async

list_streams() -> list[str]

Names of the streams of the group (all pages).

search async

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

One page of records matching query (see :class:CloudWatchLogsQueryClient).

tail async

tail(query: str, on_record: Callable[[LogRecord], None], *, interval_s: float = 1.0, on_error: Callable[[CloudWatchLogsError], None] | None = None) -> AsyncLiveTailSession

Stream new records with Live Tail (see :meth:CloudWatchLogsQueryClient.tail).

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.

AsyncLiveTailSession

A running Live Tail session of :class:~grow_aws_cloudwatch_logs.AsyncCloudWatchLogsClient.

Frames are read by an asyncio task on the client's event loop; behaviour as :class:LiveTailSession. :meth:close and :meth:stop are coroutines.

closed property

closed: bool

Whether the session has ended.

error property

error: CloudWatchLogsError | None

The error that ended the session, if any.

close async

close() -> None

Stop the session and wait for the reader task; idempotent.

wait async

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

Wait until the session ended (or timeout seconds); returns whether it ended.

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

Credentials missing or rejected (HTTP 401).

AwsSdkError

Bases: Exception

Redacted stand-in for the AWS SDK exception, kept as error.cause.

type_name is the class name of the original exception; the text has every known credential removed and is truncated to 300 characters.

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

BatchPlan dataclass

Result of :func:plan_log_event_batches.

Attributes:

Name Type Description
batches list[list[dict[str, Any]]]

batches in send order; each is sorted by timestamp, within every service limit, and holds wire events {"timestamp": <epoch ms>, "message": <str>}.

truncated int

events that were truncated.

dropped int

events that were dropped (oversize_policy="drop").

BatchProcessor

Bases: _BatchCore

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

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

add

add(record: LogRecord) -> bool

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

flush

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

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

shutdown

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

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

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

BatchStats dataclass

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

BatchingLogClient

Bases: _ClientBase

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

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

close

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

Flush and shut down; idempotent.

CancelToken

Thread-safe cancellation flag passed to sync calls as cancel=.

Cancelling interrupts an in-flight request (the call returns immediately with :class:CancelledError; the abandoned HTTP exchange finishes in the background) and any retry backoff sleep.

cancel

cancel() -> None

Request cancellation (idempotent).

on_cancel

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

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

wait

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

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

CancelledError

Bases: CloudWatchLogsError, 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.

ClientInternals dataclass

Test seams; not part of the stable API.

inject_host_prefix=False stops botocore from sending StartLiveTail to streaming-<host> (needed only for local mock servers); sleep replaces the wait between Logs Insights polls.

CloudWatchLogsClient

Bases: _Base

Synchronous Amazon CloudWatch Logs client (boto3). Thread-safe; use as a context manager or call :meth:close.

Every I/O method accepts cancel= (a :class:CancelToken) to abort from another thread (the abandoned AWS call finishes in the background). Iterator methods (describe_*, filter_log_events, get_log_events) fetch pages lazily while you iterate.

region property

region: str | None

The effective AWS region.

sdk property

sdk: Any

The underlying boto3 logs client (for operations this package does not wrap).

close

close() -> None

Flush and close every log client from :meth:log_client, stop live-tail sessions and release connections. Idempotent; never closes a caller-supplied SDK client.

delete_log_group

delete_log_group(name: str, *, ignore_missing: bool = False, cancel: CancelToken | None = None) -> bool

Delete a group with its streams and events; False when missing and ignore_missing (else NotFoundError).

delete_log_stream

delete_log_stream(group: str, stream: str, *, ignore_missing: bool = False, cancel: CancelToken | None = None) -> bool

Delete a stream; False when missing and ignore_missing.

describe_log_groups

describe_log_groups(*, prefix: str | None = None, page_size: int | None = None, limit: int | None = None, cancel: CancelToken | None = None) -> Iterator[LogGroupInfo]

Iterate log groups (sorted by name) across pages; page_size 1-50 (default 50), limit stops after that many groups.

describe_log_streams

describe_log_streams(group: str, *, prefix: str | None = None, order_by: Literal['LogStreamName', 'LastEventTime'] | None = None, descending: bool | None = None, page_size: int | None = None, limit: int | None = None, cancel: CancelToken | None = None) -> Iterator[LogStreamInfo]

Iterate the streams of a group across pages (prefix is not allowed with order_by="LastEventTime").

describe_queries

describe_queries(*, group: str | None = None, status: str | None = None, max_results: int | None = None, cancel: CancelToken | None = None) -> list[QueryInfo]

Recent Logs Insights queries (DescribeQueries).

emf

emf(metric: str, value: float | Sequence[float], dimensions: Mapping[str, str] | None = None, *, namespace: str = DEFAULT_EMF_NAMESPACE, unit: str = 'None', timestamp: datetime | int | None = None, properties: Mapping[str, str | int | float | bool] | None = None, group: str | None = None, stream: str | None = None, cancel: CancelToken | None = None) -> dict[str, Any]

Build an Embedded Metric Format document (:func:build_emf) and send it as one log event to group / stream (defaults config.log_group / config.log_stream). Returns the document sent.

ensure_log_group

ensure_log_group(name: str, *, retention_days: int | None = None, kms_key_id: str | None = None, tags: Mapping[str, str] | None = None, cancel: CancelToken | None = None) -> EnsureLogGroupResult

Create the log group when missing (CreateLogGroup), then apply retention / tags.

On an existing group the requested tags are added (never removed) and the retention is re-applied; a different kms_key_id raises ConflictError. retention_days: None = leave unchanged, 0 = never expire, else one of RETENTION_DAYS.

ensure_log_stream

ensure_log_stream(group: str, stream: str, *, create_group: bool = False, cancel: CancelToken | None = None) -> EnsureLogStreamResult

Create the log stream when missing; a missing group raises NotFoundError unless create_group.

exporter

exporter(*, group: str | None = None, stream: str | None = None, create_group: bool = False) -> CloudWatchLogsExporter

A LogExporter writing to group / stream (defaults config.log_group / config.log_stream).

filter_log_events

filter_log_events(*, group: str | None = None, streams: Sequence[str] | None = None, stream_prefix: str | None = None, pattern: str | None = None, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, limit: int | None = None, cancel: CancelToken | None = None) -> Iterator[FilteredLogEvent]

Iterate events matching a filter pattern (FilterLogEvents) across pages until no token is left (or limit). group is a name or ARN (default config.log_group); streams (max 100) and stream_prefix are mutually exclusive; start / end are inclusive (datetime or epoch ms).

filter_log_events_page

filter_log_events_page(*, group: str | None = None, streams: Sequence[str] | None = None, stream_prefix: str | None = None, pattern: str | None = None, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, next_token: str | None = None, cancel: CancelToken | None = None) -> FilterLogEventsPage

One FilterLogEvents request (next_token is None at the end; AWS may return empty pages that still carry a token). Events are ordered by timestamp, then id.

from_env classmethod

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

Build a client from GROW_AWS_CLOUDWATCH_LOGS_* and the standard AWS variables.

get_log_events

get_log_events(group: str, stream: str, *, start_from_head: bool = False, start: TimeInput | None = None, end: TimeInput | None = None, page_size: int | None = None, limit: int | None = None, cancel: CancelToken | None = None) -> Iterator[StreamLogEvent]

Iterate the events of one stream (GetLogEvents).

start_from_head=True reads oldest → newest; the default reads the newest page first, then older pages (events inside a page stay in ascending order). Iteration stops when the service returns the token that was sent.

get_log_group

get_log_group(name: str, *, cancel: CancelToken | None = None) -> LogGroupInfo | None

The log group named exactly name (None when it does not exist).

get_query_results

get_query_results(query_id: str, *, cancel: CancelToken | None = None) -> QueryResults

Status and rows of a Logs Insights query (GetQueryResults).

health

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

Liveness via a signed DescribeLogGroups {limit: 1} without retries.

Never raises for an unhealthy or unreachable service (only CANCELLED / CONFIG). An authentication or permission error still counts as healthy (details["auth"] == "failed": the service answered); throttling reports degraded.

list_log_group_tags

list_log_group_tags(name: str, *, cancel: CancelToken | None = None) -> dict[str, str]

Tags of a log group (name or ARN; ListTagsForResource).

log_client

log_client(*, group: str | None = None, stream: str | None = None, create_group: bool = False, options: BatchOptions | None = None, resource: Mapping[str, AttrValue] | None = None, redaction: RedactionProcessor | None = _DEFAULT_REDACTION, correlate: bool = True) -> BatchingLogClient

A BatchingLogClient exporting to group / stream (records are sent as normalized LogRecord JSON; the stream is created on first use). :meth:close of this client flushes and closes it too.

log_group_arn

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

ARN of a log group (without :*): built from config.account_id and the region when the account is configured, otherwise looked up with DescribeLogGroups.

log_query_client

log_query_client(*, group: str | None = None) -> CloudWatchLogsQueryClient

A LogQueryClient over group (default config.log_group).

ping

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

Authenticated round trip; latency in milliseconds. AuthenticationError on bad credentials, PermissionDeniedError without logs:DescribeLogGroups.

put_log_events

put_log_events(group: str, stream: str, events: Iterable[InputLogEvent | Mapping[str, Any]], *, auto_create: bool | None = None, create_group: bool = False, max_event_bytes: int | None = None, oversize_policy: str | None = None, cancel: CancelToken | None = None) -> PutLogEventsResult

Send events with PutLogEvents.

Events are sorted, oversized events are truncated / dropped / rejected per oversize_policy (default config.oversize_policy, limit config.max_event_bytes) and split into batches that respect every service limit (10,000 events, 1 MiB incl. 26 bytes per event, 24 h span). A missing stream is created when auto_create (default config.auto_create); create_group also creates a missing group. Events the service rejects (too old / new, expired) are reported, never retried. Throttling and 5xx are retried by the AWS SDK (a lost response may duplicate events).

put_retention_policy

put_retention_policy(group: str, days: int | None, *, cancel: CancelToken | None = None) -> None

Set the retention (PutRetentionPolicy); None or 0 removes it.

query

query(query_string: str, *, groups: Sequence[str] | None = None, start: TimeInput | None = None, end: TimeInput | None = None, limit: int | None = None, timeout_s: float | timedelta = 60.0, poll_interval_s: float | timedelta = 1.0, retry_on_query_limit: int = 3, cancel: CancelToken | None = None) -> QueryResults

Run a Logs Insights query to completion: StartQuery, then poll GetQueryResults (interval doubling up to 5 s) until a terminal status.

Failed / Unknown → UnavailableError (not retryable), Timeout → TimeoutError, Cancelled → CancelledError (messages include the query id). After timeout_s or on cancellation the query is stopped best-effort. LimitExceededException on start is retried retry_on_query_limit times.

server_version

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

Always :class:UnsupportedError: CloudWatch Logs exposes no server version (see API_VERSION).

start_live_tail

start_live_tail(groups: Sequence[str], on_event: Callable[[LiveTailEvent], None], *, streams: Sequence[str] | None = None, stream_prefixes: Sequence[str] | None = None, pattern: str | None = None, on_update: Callable[[LiveTailUpdate], None] | None = None, on_error: Callable[[CloudWatchLogsError], None] | None = None, cancel: CancelToken | None = None) -> LiveTailSession

Start a Live Tail session (StartLiveTail) and call on_event for every event.

Returns once the session has started (sessionStart). groups are 1-10 names or ARNs (names become ARNs); streams / stream_prefixes need exactly one group. On AWS the session streams new events for up to 3 hours; the Moto emulator replays the matching existing events once and ends.

start_query

start_query(query_string: str, *, groups: Sequence[str] | None = None, start: TimeInput | None = None, end: TimeInput | None = None, limit: int | None = None, cancel: CancelToken | None = None) -> str

Start a Logs Insights query (StartQuery); returns its id. groups are names or ARNs (max 50, default [config.log_group]); end defaults to now, start to one hour before end.

stop_query

stop_query(query_id: str, *, cancel: CancelToken | None = None) -> bool

Stop a running query (StopQuery); False when it had already finished.

tag_log_group

tag_log_group(name: str, tags: Mapping[str, str], *, cancel: CancelToken | None = None) -> None

Add or overwrite tags of a log group (name or ARN; TagResource).

untag_log_group

untag_log_group(name: str, keys: Iterable[str], *, cancel: CancelToken | None = None) -> None

Remove tags from a log group (name or ARN; UntagResource).

CloudWatchLogsConfig dataclass

Bases: BaseConfig

Immutable settings for the CloudWatch Logs clients.

Common fields (url, timeouts, retry, tls, proxy, headers, user_agent_suffix, hooks, logger) come from :class:BaseConfig; durations are float seconds (datetime.timedelta accepted). How they reach the AWS SDK: url is the endpoint override (empty = the SDK resolves the regional endpoint), connect_timeout / request_timeout become the botocore connect / read timeouts, retry.max_retries the standard retry mode with max_retries + 1 attempts, total_timeout bounds a whole call, tls / proxy the botocore verify / client_cert / proxies settings, headers are added to every request and user_agent_suffix follows the Grow User-Agent token. Credentials left unset use the AWS default chain (environment, shared config / SSO, web identity, container, instance metadata).

Environment (:meth:from_env), prefix GROW_AWS_CLOUDWATCH_LOGS_, then the standard variables: URL (> AWS_ENDPOINT_URL_CLOUDWATCH_LOGS > AWS_ENDPOINT_URL), REGION (> AWS_REGION > AWS_DEFAULT_REGION), ACCESS_KEY_ID / SECRET_ACCESS_KEY / SESSION_TOKEN (> AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN, one layer only), PROFILE (> AWS_PROFILE), ROLE_ARN, ROLE_SESSION_NAME, EXTERNAL_ID, LOG_GROUP (> CLOUDWATCH_LOG_GROUP), LOG_STREAM (> CLOUDWATCH_LOG_STREAM), ACCOUNT_ID, MAX_EVENT_BYTES, OVERSIZE_POLICY, AUTO_CREATE plus the common CONNECT_TIMEOUT, REQUEST_TIMEOUT, TOTAL_TIMEOUT, MAX_RETRIES, CA_CERT, CLIENT_CERT, CLIENT_KEY, INSECURE_SKIP_VERIFY, PROXY.

Attributes:

Name Type Description
url str

endpoint override; empty (default) = https://logs.<region>.amazonaws.com.

region str | None

AWS region (None = the SDK chain: environment, profile).

access_key_id str | None

access key id (requires secret_access_key).

secret_access_key Secret | None

secret access key (:class:Secret).

session_token Secret | None

session token for temporary credentials (:class:Secret).

profile str | None

shared config profile.

role_arn str | None

role assumed with STS on top of the base credentials.

role_session_name str

STS session name (default grow-sdk).

external_id Secret | None

STS external id (:class:Secret).

log_group str | None

default log group of the log client, the query client and emf.

log_stream str

log stream of the log client (default <hostname>-<pid>-<random6>, created on first use).

account_id str | None

12-digit account id used to build log group ARNs for live tail (else they are looked up with DescribeLogGroups).

max_event_bytes int

per-event message limit in UTF-8 bytes (64 - 1,048,550).

oversize_policy OversizePolicy

truncate (default), drop or error for larger events.

auto_create bool

put_log_events creates a missing log stream and retries once.

sdk_client Any

an existing AWS SDK client to use instead of building one (a boto3 logs client for the sync client, an entered aiobotocore logs client for the async client). Mutually exclusive with the credential, region, profile, role and endpoint fields; close() never closes it and the Grow hooks, TLS, proxy, timeout, header and User-Agent settings do not apply to it.

effective_url property

effective_url: str

url when set, else the public endpoint of region (us-east-1 when unset).

endpoint property

endpoint: str | None

The explicit endpoint override passed to the AWS SDK (None = SDK resolves it).

from_env classmethod

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

Build from the environment, then validate.

Precedence: explicit keyword > GROW_AWS_CLOUDWATCH_LOGS_<NAME> > the standard AWS / CloudWatch variables > default. env defaults to os.environ; pass a dict in tests. An explicit sdk_client replaces the credentials, region, profile, role and endpoint found in the environment.

validate

validate() -> _C

Common checks plus the CloudWatch Logs rules; raises :class:ConfigError.

CloudWatchLogsExporter

Exports log records with PutLogEvents to one group / stream (sync).

The message of each event is the normalized LogRecord JSON (redaction already applied by the log client); the event timestamp is the record timestamp in ms. The stream is created on first use (and the group with create_group). gzip is ignored: PutLogEvents has no request compression in the AWS API model.

export

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

Send one batch; ExportResult.rejected counts oversized and rejected records.

shutdown

shutdown() -> None

Nothing to release (the client owns the connection).

CloudWatchLogsQueryClient

Bases: BaseLogQueryClient

LogQueryClient over one log group (sync).

search uses FilterLogEvents: order="asc" reads natively (oldest first, cursor = the service token); order="desc" (default) walks the time window backwards in slices (5 min, each 4 times wider) from now to one hour before the group's creation time (else 30 days), newest slice first, newest record first. A plain query is an exact phrase; a query starting with { ? [ - " is a native filter pattern. tail uses Live Tail, list_streams DescribeLogStreams; list_labels raises UnsupportedError (CloudWatch Logs has no label inventory).

list_streams

list_streams() -> list[str]

Names of the streams of the group (all pages).

search

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

One page of records matching query (see the class docs).

tail

tail(query: str, on_record: Callable[[LogRecord], None], *, interval_s: float = 1.0, on_error: Callable[[CloudWatchLogsError], None] | None = None) -> LiveTailSession

Stream new records with Live Tail (filter pattern built like :meth:search).

interval_s does not apply (the service pushes events). Errors that end the session go to on_error; start-up errors are raised.

ConfigError

Bases: CloudWatchLogsError

Invalid or missing configuration.

ConflictError

Bases: CloudWatchLogsError

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

EnsureLogGroupResult dataclass

Result of ensure_log_group: whether this call created the group, and its ARN.

EnsureLogStreamResult dataclass

Result of ensure_log_stream: whether this call created the stream.

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

FilterLogEventsPage dataclass

One FilterLogEvents page; next_token is None at the end.

FilteredLogEvent dataclass

One event returned by filter_log_events.

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.

InputLogEvent dataclass

One log event to send with put_log_events.

Attributes:

Name Type Description
message str

the message text.

timestamp TimeInput | None

event time (aware datetime or epoch milliseconds; None = now).

LiveTailEvent dataclass

One live-tail event.

LiveTailSession

A running Live Tail session of :class:~grow_aws_cloudwatch_logs.CloudWatchLogsClient.

Frames are read by a daemon thread that calls on_event for every event (and on_update for every sessionUpdate frame, also empty keep-alive updates). The session ends when the service closes the stream (Moto: after replaying the matching existing events; AWS: after up to 3 hours), on an error (passed to on_error and kept in :attr:error) or on :meth:close. Exceptions raised by callbacks are ignored.

closed property

closed: bool

Whether the session has ended.

error property

error: CloudWatchLogsError | None

The error that ended the session, if any.

close

close() -> None

Stop the session and wait (up to 5 s) for the reader thread; idempotent.

wait

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

Block until the session ended (or timeout seconds); returns whether it ended.

LiveTailUpdate dataclass

One sessionUpdate frame: whether results were sampled and how many it held.

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.

LogGroupInfo dataclass

A log group (DescribeLogGroups).

Attributes:

Name Type Description
name str

log group name.

arn str

log group ARN without the trailing :*.

creation_time datetime | None

creation time.

retention_days int | None

retention in days (None = never expire).

stored_bytes int | None

stored bytes (approximate, eventually consistent).

kms_key_id str | None

KMS key ARN that encrypts the group.

metric_filter_count int | None

number of metric filters.

log_group_class str | None

STANDARD, INFREQUENT_ACCESS …

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.

LogStreamInfo dataclass

A log stream (DescribeLogStreams).

Attributes:

Name Type Description
name str

log stream name.

arn str | None

log stream ARN.

creation_time datetime | None

creation time.

first_event_time datetime | None

time of the first event.

last_event_time datetime | None

time of the last event (eventually consistent on AWS).

last_ingestion_time datetime | None

last ingestion time.

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

Missing record (HTTP 404).

PermissionDeniedError

Bases: CloudWatchLogsError

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.

PutLogEventsResult dataclass

Result of put_log_events.

Attributes:

Name Type Description
accepted int

events the service accepted.

rejected int

events the service rejected (too old, too new, expired; never retried).

truncated int

events truncated by the size policy before sending.

dropped int

events dropped by the size policy (oversize_policy="drop").

batches int

PutLogEvents calls made.

rejected_info list[RejectedLogEventsInfo]

rejection details per batch that had rejections.

QueryInfo dataclass

One Logs Insights query (describe_queries).

QueryResults dataclass

Result of get_query_results / query.

Attributes:

Name Type Description
query_id str

the query id.

status str

query status.

rows list[Mapping[str, str]]

result rows, field name → value (@timestamp, @message, @ptr …).

statistics QueryStatistics | None

scan statistics when the service reports them.

QueryStatistics dataclass

Logs Insights scan statistics (reported by AWS, not by the emulator).

RateLimitError

Bases: CloudWatchLogsError

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.

RejectedLogEventsInfo dataclass

Events of one batch the service did not store (indexes into the sorted batch).

As returned by AWS the …end_index fields are exclusive (events 0..index-1 were rejected) and too_new_log_event_start_index is the first rejected event at the end (inclusive). Moto 5.2.4 returns end indexes one lower.

Attributes:

Name Type Description
batch int

index of the batch within the call (0-based).

too_old_log_event_end_index int | None

end (exclusive) of the events older than 14 days or the retention.

too_new_log_event_start_index int | None

first event more than 2 hours in the future.

expired_log_event_end_index int | None

end (exclusive) of the events older than the retention period.

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.

StreamLogEvent dataclass

One event returned by get_log_events.

TimeoutError

Bases: CloudWatchLogsError

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

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

UnsupportedError

Bases: CloudWatchLogsError

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

ValidationError

Bases: CloudWatchLogsError

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.

aws_error_code

aws_error_code(exc: BaseException | None) -> str | None

AWS error code of an SDK exception (without a namespace# prefix) or of a mapped SDK error (error.aws_code); None when there is none.

build_emf

build_emf(metric: str, value: float | Sequence[float], dimensions: Mapping[str, str] | None = None, *, namespace: str = DEFAULT_EMF_NAMESPACE, unit: str = 'None', timestamp: datetime | int | None = None, properties: Mapping[str, str | int | float | bool] | None = None) -> dict[str, Any]

Build an EMF document for one metric.

value is a finite number or 1-100 finite numbers; dimensions (at most 30) become one dimension set; properties are extra top-level fields (searchable, not dimensions); timestamp defaults to now. Raises ValidationError on invalid input.

current_trace_context

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

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

default_log_stream_name

default_log_stream_name() -> str

Default stream name <hostname>-<pid>-<random6> (:, * and spaces become -).

error_for_code

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

Return the error class for a code (ErrorCode member or wire value).

error_from_status

error_from_status(status: int, operation: str, *, content: bytes = b'', headers: Headers | None = None, known_secrets: list[str] | None = None, retry_after: float | None = None, request_id_headers: Sequence[str] = ()) -> ServiceError

Map an HTTP error status to the SPEC 2.1 error with a redacted, truncated message.

request_id_headers are checked before the default :data:REQUEST_ID_HEADERS.

event_to_log_record

event_to_log_record(event: FilteredLogEvent | LiveTailEvent) -> LogRecord

Normalize a CloudWatch event: a message holding a normalized LogRecord JSON is decoded; any other message becomes body with severity INFO. Attributes aws.log.stream, aws.event.id (and aws.log.group for live tail) are added.

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_log_group_name

is_valid_log_group_name(name: object) -> bool

True when name is a valid log group name (1-512 of [.-_/#A-Za-z0-9]).

is_valid_log_stream_name

is_valid_log_stream_name(name: object) -> bool

True when name is a valid log stream name (1-512 characters, no : or *).

map_aws_error

map_aws_error(operation: str, exc: BaseException, known_secrets: Iterable[str | Secret | None] = ()) -> CloudWatchLogsError

Map any exception raised by an AWS SDK call to a :class:CloudWatchLogsError.

AWS error code first, then the HTTP status (a 403 without a recognised code — Moto answers IAM errors with XML on a JSON protocol — is AUTHENTICATION when the body names a bad key or signature, else PERMISSION_DENIED), then credential / configuration / timeout / network shapes. The message is "<operation>: <reason>[: <AwsCode>] (HTTP <status>)"; AWS messages are never copied (they may echo log data). error.aws_code holds the AWS code and error.cause a redacted :class:AwsSdkError.

new_idempotency_key

new_idempotency_key() -> str

A random key for the Idempotency-Key header.

parse_bool

parse_bool(text: str) -> bool

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

parse_duration

parse_duration(text: str) -> float

Parse a duration into seconds.

Accepts integer milliseconds ("1500" → 1.5) or Go-style units ("500ms", "10s", "2m", "1h", "1m30s"). Raises :class:ValueError for anything else.

parse_insights_timestamp

parse_insights_timestamp(value: str) -> datetime | None

Convert a Logs Insights @timestamp (YYYY-MM-DD HH:mm:ss.SSS UTC on AWS, epoch milliseconds on the emulator) to an aware UTC datetime; None when unparseable.

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_timestamp

parse_timestamp(value: str) -> datetime

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

partition_for_region

partition_for_region(region: str) -> str

AWS partition of a region (aws, aws-cn, aws-us-gov).

plan_log_event_batches

plan_log_event_batches(events: Iterable[InputLogEvent | Mapping[str, Any]], *, max_event_bytes: int = DEFAULT_MAX_EVENT_BYTES, oversize_policy: str = 'truncate') -> BatchPlan

Apply the per-event size policy, sort events by timestamp (stable) and split them into batches that respect every PutLogEvents limit.

Events are :class:InputLogEvent objects or mappings with message and an optional timestamp (None = now). Raises ValidationError for invalid timestamps, non-string messages, a bad max_event_bytes / oversize_policy, or an oversized event with oversize_policy="error".

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.

record_to_message

record_to_message(record: LogRecord, max_event_bytes: int, policy: str) -> str | None

Serialize a record to its normalized JSON message.

When the message is larger than max_event_bytes, truncate shortens the record body so the message stays valid JSON (falling back to a plain cut only when the other fields alone are too large); drop and error return None.

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.

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_filter_pattern

to_filter_pattern(query: str) -> str

Convert a search query to a CloudWatch filter pattern.

Empty → match everything; a query starting with {, ?, [, - or " is passed through as a native pattern; anything else becomes an exact phrase ("…", inner quotes and backslashes escaped).

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

truncate_message

truncate_message(message: str, max_bytes: int) -> str

Truncate message on a UTF-8 character boundary so the result, including the appended …[truncated N bytes] marker, is at most max_bytes UTF-8 bytes. N is the number of bytes removed from the original. Returns message unchanged when it already fits.

user_agent

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

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

utf8_bytes

utf8_bytes(text: str) -> int

UTF-8 size of text in bytes.

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.