Expand description
§grow-aws-cloudwatch-logs
Rust SDK for Amazon CloudWatch Logs
by Grow Codes, built on the official AWS SDK for Rust (aws-sdk-cloudwatchlogs).
use grow_aws_cloudwatch_logs::logging::{attrs, LogClient, LogQueryClient, SearchOptions};
use grow_aws_cloudwatch_logs::{
CloudWatchLogsClient, CloudWatchLogsConfig, EnsureLogGroupOptions, LogClientOptions,
LogEvent, PutLogEventsOptions,
};
let client = CloudWatchLogsClient::new(CloudWatchLogsConfig::from_env()?)?;
client
.ensure_log_group("app/web", EnsureLogGroupOptions::default().retention_days(14))
.await?;
client
.put_log_events("app/web", "web-1", vec![LogEvent::new("hello")], PutLogEventsOptions::default())
.await?;
// Logging category: batching LogClient + Logger facade, and search.
let logs = client.log_client(LogClientOptions::default())?;
logs.logger(Some("http"), attrs! {}).info("listening", attrs! { "port" => 8080 });
logs.flush(None).await?;
let found = client.log_query_client(None)?.search("listening", SearchOptions::default()).await?;
println!("{} records", found.records.len());
client.close().await;Features: blocking (a blocking client), testing (in-memory fakes and the conformance
runner), tracing-layer and log-bridge (logging adapters, on by default).
Not affiliated with or endorsed by Amazon Web Services. Amazon CloudWatch and AWS are trademarks of Amazon.com, Inc. or its affiliates.
Re-exports§
pub use crate::core::Error;pub use crate::core::ErrorCode;pub use crate::core::HealthStatus;pub use crate::core::Result;pub use crate::core::RetryPolicy;pub use crate::core::Secret;pub use aws_sdk_cloudwatchlogs;
Modules§
- blocking
blocking - Blocking wrapper (feature
blocking). Each client owns a multi-thread tokio runtime with one worker, so background work (log batching, live-tail sessions) keeps running between calls. - core
- Shared core: errors, configuration, secrets in config, redaction, retries and transport.
- logging
- Logging category (SPEC §4): records, batching, redaction, the
Loggerfacade, the query model and framework adapters. - testing
testing - Test support (feature
testing): in-memory fakes and the conformance runner (SPEC §6).
Macros§
- attrs
- Builds an
Attributesmap:attrs! { "user" => "ada", "n" => 3 }.
Structs§
- AwsError
Detail - Redacted details of an AWS error, kept as the
Errorsource. It never holds the raw response (which could echo request data). - Cloud
Watch Logs Client - Async client for Amazon CloudWatch Logs. Cheap to clone (clones share one SDK client).
- Cloud
Watch Logs Config - Immutable client configuration; build it with
CloudWatchLogsConfig::builderorCloudWatchLogsConfig::from_env.Debugoutput redacts every credential. - Cloud
Watch Logs Config Builder - Builder for
CloudWatchLogsConfig. Values set here win over the environment. - Cloud
Watch Logs Exporter - The
LogExporterof the client: writes normalized LogRecord JSON documents withPutLogEventsto one log group and stream.gzipis ignored (PutLogEvents has no request compression). - Cloud
Watch Logs Query Client - The
LogQueryClientover one log group:searchusesFilterLogEvents,taillive tail,list_streamsDescribeLogStreams;list_labelsisUNSUPPORTED. - Delete
Options - Options of
delete_log_group/delete_log_stream. - Describe
LogGroups Options - Options of
describe_log_groups. - Describe
LogStreams Options - Options of
describe_log_streams. - Describe
Queries Options - Options of
describe_queries. - EmfOptions
- Options of
build_emfandCloudWatchLogsClient::emf. - Ensure
LogGroup Options - Options of
ensure_log_group. - Ensure
LogGroup Result - What
ensure_log_groupdid. - Ensure
LogStream Options - Options of
ensure_log_stream. - Ensure
LogStream Result - What
ensure_log_streamdid. - Exporter
Options - Where an exporter or log client writes.
- Filter
LogEvents Options - Options of
filter_log_events/filter_log_events_page. - Filter
LogEvents Page - One
FilterLogEventsresponse. - Filtered
LogEvent - One event of
FilterLogEvents. - GetLog
Events Options - Options of
get_log_events. - Live
Tail Event - One event of a live-tail session.
- Live
Tail Options - Options of
start_live_tail. - Live
Tail Session - A running live-tail session. AWS streams events ingested after the session started, about
once per second, for up to 3 h. Dropping the handle does not stop the session; call
close(or close the client). - Live
Tail Update - One
sessionUpdateframe of a live-tail session. - LogClient
Options - Options of
CloudWatchLogsClient::log_client: where to write plus the batching, resource, redaction and severity options of the generatedBatchingLogClient. - LogEvent
- One event for
put_log_events. - LogGroup
- A log group.
- LogStream
- A log stream.
- Paginator
- Lazy iterator over every page of a list call. Nothing is sent until the first
next,next_pageortry_collect. Iteration ends when the service returns no token (or the token it was sent), afterlimititems, or after the first error. - PutLog
Events Options - Options of
put_log_events. - PutLog
Events Result - What
put_log_eventsdid. - Query
Info - One Logs Insights query of
describe_queries. - Query
Options - Options of
start_queryandquery. - Query
Results - Result of
get_query_resultsorquery. - Query
Statistics - Scan statistics of a query (AWS only).
- Rejected
Info rejectedLogEventsInfoof onePutLogEventscall. Indexes refer to the timestamp-sorted events of that batch. As returned by AWS,too_old_log_event_end_indexandexpired_log_event_end_indexare exclusive (events[0, index)rejected) andtoo_new_log_event_start_indexis inclusive (events[index, n)rejected). Moto 5.2.4 returns end indexes one lower (seedocs/compatibility.md).- Stream
LogEvent - One event of
GetLogEvents.
Enums§
- Oversize
Policy - What happens to an event larger than the configured maximum event size.
- Query
Status - Status of a Logs Insights query.
- Stream
Order - Order of
describe_log_streams.
Constants§
- API_
VERSION - Amazon CloudWatch Logs API version this package targets.
- ATTR_
EVENT_ ID - Attribute key with the event id on records read back by
search. - ATTR_
LOG_ GROUP - Attribute key with the log group on plain live-tail records.
- ATTR_
LOG_ STREAM - Attribute key with the stream name on records read back from CloudWatch Logs.
- AWS_
ERROR_ CODES - AWS error code → Grow
ErrorCode(API.md §1.1). - DEFAULT_
EMF_ NAMESPACE - Metric namespace used when
EmfOptions::namespaceis not set. - DEFAULT_
MAX_ EVENT_ BYTES - Default per-event size policy in UTF-8 bytes (256 KiB).
- DEFAULT_
QUERY_ LIMIT_ RETRIES - Default number of
StartQueryretries afterLimitExceededException. - DEFAULT_
QUERY_ POLL_ INTERVAL - First poll interval of
query. - DEFAULT_
QUERY_ TIMEOUT - Default timeout of
query. - DEFAULT_
ROLE_ SESSION_ NAME - Default STS role session name of the assume-role helper.
- DEFAULT_
URL - Informational endpoint used when no endpoint override is set and no region is known. The AWS
SDK resolves the real endpoint (
https://logs.<region>.amazonaws.com) itself. - EMF_
UNITS - Units CloudWatch metrics accept.
- EVENT_
OVERHEAD_ BYTES - Per-event overhead counted against
MAX_BATCH_BYTES. - MAX_
BATCH_ BYTES - Maximum size of one
PutLogEventscall: Σ(UTF-8 message bytes + 26). - MAX_
BATCH_ EVENTS - Maximum number of events in one
PutLogEventscall. - MAX_
BATCH_ SPAN - Largest timestamp span inside one
PutLogEventscall. - MAX_
DESCRIBE_ PAGE_ SIZE - Largest
DescribeLogGroups/DescribeLogStreamspage. - MAX_
EVENTS_ PAGE_ SIZE - Largest
FilterLogEvents/GetLogEventspage (and Logs Insights row limit). - MAX_
EVENT_ BYTES_ LIMIT - Hard per-event cap: 1 MiB minus the 26 bytes of per-event overhead CloudWatch Logs counts
against a
PutLogEventscall. - MAX_
LIVE_ TAIL_ GROUPS - Most log groups one live-tail session can follow.
- MAX_
QUERY_ GROUPS - Most log groups one Logs Insights query can read.
- MAX_
QUERY_ POLL_ INTERVAL - Largest poll interval of
query. - RETENTION_
DAYS - Retention values (days) CloudWatch Logs accepts.
- VENDOR_
LOG_ GROUP_ VARS - Vendor variables checked after
GROW_AWS_CLOUDWATCH_LOGS_LOG_GROUP. - VENDOR_
LOG_ STREAM_ VARS - Vendor variables checked after
GROW_AWS_CLOUDWATCH_LOGS_LOG_STREAM. - VENDOR_
PROFILE_ VARS - Vendor variables checked after
GROW_AWS_CLOUDWATCH_LOGS_PROFILE. - VENDOR_
REGION_ VARS - Vendor variables checked (in order) after
GROW_AWS_CLOUDWATCH_LOGS_REGION. - VENDOR_
URL_ VARS - Vendor variables checked (in order) after
GROW_AWS_CLOUDWATCH_LOGS_URL.
Functions§
- aws_
error_ code - The AWS error code behind an SDK error (e.g.
ResourceNotFoundException), when the error came from an AWS response with a recognisable code. - build_
emf - Builds a CloudWatch Embedded Metric Format document for one metric:
value(oropts.values) is published undermetricwithdimensionsas one dimension set (at most 30). Returns the JSON text; invalid input isVALIDATION. Metric extraction happens inside AWS. - error_
code_ for_ aws - The Grow code for an AWS error code (
Nonewhen unknown). - error_
code_ from_ body - Extracts an AWS error code from an XML (
<Code>) or JSON (__type,code) error body. - filter_
pattern - Turns a search query into a CloudWatch Logs filter pattern: empty stays empty (every
event), a query that starts with
{,?,[,-or"is passed through as a native pattern, anything else becomes an exact quoted phrase. - filtered_
event_ to_ record - A
FilterLogEventsevent as aLogRecord(seemessage_to_record) with the attributesaws.log.streamandaws.event.id. - live_
tail_ event_ to_ record - A live-tail event as a
LogRecord(seemessage_to_record) with the attributeaws.log.streamand, for plain messages,aws.log.group. - message_
to_ record - Decodes a CloudWatch Logs message: a normalized LogRecord JSON document (with
timestampandbody) is decoded as such; any other message becomes anINFOrecord with the message as body,timestampas timestamp andingestedas observed timestamp. - parse_
query_ timestamp - Parses an Insights
@timestampvalue: the AWS form2006-01-02 15:04:05.000(UTC) or epoch milliseconds (Moto).VALIDATIONfor anything else. - partition_
of - The AWS partition of a region.
- truncate_
message - Shortens
messageto at mostmax_bytesUTF-8 bytes, cutting on a character boundary and appending…[truncated N bytes](N = bytes removed). Messages that fit are returned unchanged; whenmax_bytesis smaller than the marker the message is cut without it. - validate_
group_ name VALIDATIONunlessnameis a valid log group name (1–512 of[.-_/#A-Za-z0-9]).- validate_
stream_ name VALIDATIONunlessnameis a valid log stream name (1–512 characters, no:or*).
Type Aliases§
- Cloud
Watch Logs Error - Service-prefixed alias of
Error. - Live
Tail Callback - Callback receiving live-tail events.
- Live
Tail Error Callback - Callback receiving the error that ended a live-tail session.
- Live
Tail Update Callback - Callback receiving live-tail update frames.