Skip to content

Functions

The Amazon CloudWatch Logs API of this SDK. Every function exists in all five languages with the same behaviour, named per language convention (putLogEvents in TypeScript and Java, put_log_events in Python and Rust, PutLogEvents in Go with ctx first). Each page shows the functions of one area with an example in every language.

Area Functions Description
Client new / fromEnv / builder / withSdkClient, health, ping, serverVersion, close builds or wraps the AWS SDK client (region, credentials, endpoint, assume role); signed DescribeLogGroups(limit 1) probe (health never throws, auth failures count as reachable); serverVersion is always UNSUPPORTED; close is idempotent, flushes log clients, stops live-tail sessions; later calls raise CANCELLED
Bootstrap ensureLogGroup, ensureLogStream, putRetentionPolicy, deleteLogGroup, deleteLogStream, describeLogGroups, describeLogStreams, getLogGroup, tagLogGroup, untagLogGroup, listLogGroupTags, logGroupArn idempotent create (existing group: tags added, never removed; retention re-applied when given, 0 = never expire; different KMS key → CONFLICT); retention 0/none removes the policy; lazy pagination iterators; delete with ignoreMissing
Ingest putLogEvents, emf, buildEmf, truncateMessage (Go/Rust) client-side batching that respects the service limits (10,000 events and 1,048,576 bytes incl. 26 bytes per event per call, 24 h span, sorted by timestamp), 256 KiB per-event policy truncate / drop / error, missing stream auto-created, throttling retried; Embedded Metric Format documents (emf returns the document sent, VALIDATION when rejected)
Query filterLogEvents, filterLogEventsPage, getLogEvents pattern search over a group (streams or a stream prefix, time window) as a lazy iterator or one page; reading one stream forward (startFromHead) or backward, ending when the token repeats
Logs Insights startQuery, getQueryResults, query, stopQuery, describeQueries Insights queries; query polls until a terminal status, retries LimitExceeded, stops the query on timeout or cancellation
Live tail startLiveTail streaming StartLiveTail session (up to 3 h on AWS) with onEvent / onUpdate / onError callbacks and a handle to stop it; names are turned into ARNs
Logging logClient, exporter, logQueryClient → search, tail, listStreams, listLabels, waitForLog the shared Grow Codes LogClient (batching, logger facade, redaction, framework adapters) writing normalized LogRecord JSON; search uses FilterLogEvents (asc) or walks the time window backwards (desc, default); tail is live tail; listLabels is UNSUPPORTED

All calls go through the official AWS SDK of the language (SigV4, endpoint resolution, standard retry mode). Errors are mapped by AWS error code (HTTP status only as a fallback), see Error handling and the code table in Compatibility.

Service configuration

These settings come on top of the common settings. Precedence: explicit value > GROW_AWS_CLOUDWATCH_LOGS_* > standard AWS / CloudWatch variable > AWS SDK default chain / default.

Setting Environment variable Default
url — endpoint override (emulator, VPC endpoint) GROW_AWS_CLOUDWATCH_LOGS_URL, AWS_ENDPOINT_URL_CLOUDWATCH_LOGS, AWS_ENDPOINT_URL none: the AWS SDK resolves https://logs.<region>.amazonaws.com
region GROW_AWS_CLOUDWATCH_LOGS_REGION, AWS_REGION, AWS_DEFAULT_REGION AWS SDK chain (profile region); none → CONFIG
accessKeyId GROW_AWS_CLOUDWATCH_LOGS_ACCESS_KEY_ID, AWS_ACCESS_KEY_ID AWS default credential chain
secretAccessKey GROW_AWS_CLOUDWATCH_LOGS_SECRET_ACCESS_KEY, AWS_SECRET_ACCESS_KEY (same layer as the key id) AWS default credential chain
sessionToken GROW_AWS_CLOUDWATCH_LOGS_SESSION_TOKEN, AWS_SESSION_TOKEN (same layer as the key id) none
profile GROW_AWS_CLOUDWATCH_LOGS_PROFILE, AWS_PROFILE AWS SDK default
credentials — an AWS SDK credentials provider — none
roleArn — assume a role with STS (standard STS endpoint, AWS_ENDPOINT_URL_STS honoured) GROW_AWS_CLOUDWATCH_LOGS_ROLE_ARN none
roleSessionName GROW_AWS_CLOUDWATCH_LOGS_ROLE_SESSION_NAME grow-sdk
externalId GROW_AWS_CLOUDWATCH_LOGS_EXTERNAL_ID none
logGroup — default group of emf, filterLogEvents, logClient, logQueryClient, startLiveTail GROW_AWS_CLOUDWATCH_LOGS_LOG_GROUP, CLOUDWATCH_LOG_GROUP none
logStream — default stream of emf and logClient GROW_AWS_CLOUDWATCH_LOGS_LOG_STREAM, CLOUDWATCH_LOG_STREAM <hostname>-<pid>-<random6>
accountId — builds live-tail log group ARNs without a lookup GROW_AWS_CLOUDWATCH_LOGS_ACCOUNT_ID none: the ARN is read with DescribeLogGroups
maxEventBytes — per-event message limit in UTF-8 bytes GROW_AWS_CLOUDWATCH_LOGS_MAX_EVENT_BYTES 262,144 (256 KiB; at most 1,048,550)
oversizePolicy — truncate, drop or error GROW_AWS_CLOUDWATCH_LOGS_OVERSIZE_POLICY truncate
autoCreate — create a missing stream in putLogEvents GROW_AWS_CLOUDWATCH_LOGS_AUTO_CREATE true
sdkClient — use an existing AWS SDK client — none (the SDK builds one)

Static credentials are read as one set: when GROW_AWS_CLOUDWATCH_LOGS_ACCESS_KEY_ID is set, the secret key and session token come from GROW_AWS_CLOUDWATCH_LOGS_* only, never from AWS_*. sdkClient replaces the AWS SDK client the package would build (Grow TLS, proxy, hooks and User-Agent settings do not apply to it; close() leaves it usable).

Integration coverage

Every function is called against motoserver/moto:5.2.4 in the Docker suite with a round-trip assertion. Paths Moto cannot serve (for example stopQuery, Insights filter/stats, the PutLogEvents service limits, live-tail streaming semantics) are covered by unit tests against recorded AWS responses and listed in Compatibility.