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
¶
Attribute value: scalar, list of values or nested mapping (OTel AnyValue without bytes).
AsyncBaseLogQueryClient ¶
Async :class:BaseLogQueryClient.
AsyncBatchProcessor ¶
Bases: _BatchCore
Batches records for an :class:AsyncLogExporter on an asyncio task.
The task starts on the running loop at the first :meth:add (or :meth:flush). :meth:add
may be called from other threads; it wakes the worker thread-safely. Exports are bounded by
export_timeout_s with :func:asyncio.wait_for.
add ¶
Queue without blocking; False when dropped (block acts as drop_newest here).
add_wait
async
¶
Queue a record, waiting for queue space with drop_policy="block".
flush
async
¶
Export everything queued now; raises TimeoutError when timeout_s passes first.
shutdown
async
¶
Drain (bounded by timeout_s), stop the task, shut the exporter down; idempotent.
AsyncBatchingLogClient ¶
Bases: _ClientBase
:class:AsyncLogClient over an :class:AsyncLogExporter + :class:AsyncBatchProcessor.
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
¶
Flush and close log clients, stop live-tail sessions and release connections. Idempotent; never closes a caller-supplied SDK client.
delete_log_group
async
¶
See :meth:CloudWatchLogsClient.delete_log_group.
delete_log_stream
async
¶
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
¶
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
¶
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
¶
See :meth:CloudWatchLogsClient.get_log_group.
get_query_results
async
¶
See :meth:CloudWatchLogsClient.get_query_results.
list_log_group_tags
async
¶
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_query_client ¶
See :meth:CloudWatchLogsClient.log_query_client.
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
¶
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
¶
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.
tag_log_group
async
¶
See :meth:CloudWatchLogsClient.tag_log_group.
untag_log_group
async
¶
See :meth:CloudWatchLogsClient.untag_log_group.
AsyncCloudWatchLogsExporter ¶
Async :class:CloudWatchLogsExporter for :class:AsyncCloudWatchLogsClient.
AsyncCloudWatchLogsQueryClient ¶
Bases: AsyncBaseLogQueryClient
Async :class:CloudWatchLogsQueryClient for :class:AsyncCloudWatchLogsClient.
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").
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.
wait
async
¶
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.
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 …).
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 |
truncated |
int
|
events that were truncated. |
dropped |
int
|
events that were dropped ( |
BatchProcessor ¶
Bases: _BatchCore
Batches records for a synchronous :class:LogExporter on a daemon worker thread.
The worker starts with the first record. It exports when a batch is full, when
flush_interval_s passed since the first queued record, on :meth:flush and on
:meth:shutdown. Processors with a started worker are shut down at interpreter exit.
add ¶
Queue a record; False when it was dropped. Blocks only with drop_policy="block".
flush ¶
Export everything queued now; raises TimeoutError when timeout_s passes first.
shutdown ¶
Drain the queue (bounded by timeout_s), stop the worker and shut the exporter down.
Idempotent. Records still queued when the timeout passes are dropped with reason
shutdown; later :meth:add calls are dropped the same way.
BatchStats
dataclass
¶
Counters of a batch processor (see the module docs for their meaning).
BatchingLogClient ¶
Bases: _ClientBase
:class:LogClient over a synchronous :class:LogExporter and a :class:BatchProcessor.
redaction defaults to RedactionProcessor(); pass None to disable it.
correlate adds the active span's ids to records without a trace id.
CancelToken ¶
Thread-safe cancellation flag passed to sync calls as cancel=.
Cancelling interrupts an in-flight request (the call returns immediately with
:class:CancelledError; the abandoned HTTP exchange finishes in the background) and any
retry backoff sleep.
CancelledError ¶
Bases: 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.
sdk
property
¶
The underlying boto3 logs client (for operations this package does not wrap).
close ¶
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
¶
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 ¶
The log group named exactly name (None when it does not exist).
get_query_results ¶
Status and rows of a Logs Insights query (GetQueryResults).
health ¶
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 ¶
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 ¶
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 ¶
A LogQueryClient over group (default config.log_group).
ping ¶
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 ¶
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 ¶
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 a running query (StopQuery); False when it had already finished.
tag_log_group ¶
Add or overwrite tags of a log group (name or ARN; TagResource).
untag_log_group ¶
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) = |
region |
str | None
|
AWS region ( |
access_key_id |
str | None
|
access key id (requires |
secret_access_key |
Secret | None
|
secret access key (:class: |
session_token |
Secret | None
|
session token for temporary credentials (:class: |
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 |
external_id |
Secret | None
|
STS external id (:class: |
log_group |
str | None
|
default log group of the log client, the query client and |
log_stream |
str
|
log stream of the log client (default |
account_id |
str | None
|
12-digit account id used to build log group ARNs for live tail (else they
are looked up with |
max_event_bytes |
int
|
per-event message limit in UTF-8 bytes (64 - 1,048,550). |
oversize_policy |
OversizePolicy
|
|
auto_create |
bool
|
|
sdk_client |
Any
|
an existing AWS SDK client to use instead of building one (a boto3 |
effective_url
property
¶
url when set, else the public endpoint of region (us-east-1 when unset).
endpoint
property
¶
The explicit endpoint override passed to the AWS SDK (None = SDK resolves it).
from_env
classmethod
¶
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 ¶
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.
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).
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.
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 (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").
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 |
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.
wait ¶
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 ( |
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
|
|
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.
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 ¶
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.
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 ( |
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 ( |
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.
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 ¶
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.
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 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 ¶
(trace_id, span_id, trace_flags) of the active OpenTelemetry span, if any.
default_log_stream_name ¶
Default stream name <hostname>-<pid>-<random6> (:, * and spaces become -).
error_for_code ¶
Return the error class for a code (ErrorCode member or wire value).
error_from_status ¶
error_from_status(status: int, operation: str, *, content: bytes = b'', headers: Headers | None = None, known_secrets: list[str] | None = None, retry_after: float | None = None, request_id_headers: Sequence[str] = ()) -> ServiceError
Map an HTTP error status to the SPEC 2.1 error with a redacted, truncated message.
request_id_headers are checked before the default :data:REQUEST_ID_HEADERS.
event_to_log_record ¶
Normalize a 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 ¶
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_log_group_name ¶
True when name is a valid log group name (1-512 of [.-_/#A-Za-z0-9]).
is_valid_log_stream_name ¶
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.
parse_bool ¶
Parse true/false/1/0/yes/no/on/off (case-insensitive); raise :class:ValueError.
parse_duration ¶
Parse a duration into seconds.
Accepts integer milliseconds ("1500" → 1.5) or Go-style units ("500ms", "10s",
"2m", "1h", "1m30s"). Raises :class:ValueError for anything else.
parse_insights_timestamp ¶
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 as delta seconds or an HTTP-date; return seconds (>= 0) or None.
parse_timestamp ¶
Parse RFC 3339 (any fraction precision, Z/offset; none = UTC) to aware UTC.
partition_for_region ¶
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 ¶
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 ¶
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.
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_filter_pattern ¶
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 ¶
Normalise a duration given as float seconds or :class:datetime.timedelta.
truncate ¶
Truncate text to limit characters (adds an ellipsis when cut).
truncate_message ¶
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 ¶
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.