Skip to main content

Crate grow_aws_cloudwatch_logs

Crate grow_aws_cloudwatch_logs 

Source
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§

blockingblocking
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 Logger facade, the query model and framework adapters.
testingtesting
Test support (feature testing): in-memory fakes and the conformance runner (SPEC §6).

Macros§

attrs
Builds an Attributes map: attrs! { "user" => "ada", "n" => 3 }.

Structs§

AwsErrorDetail
Redacted details of an AWS error, kept as the Error source. It never holds the raw response (which could echo request data).
CloudWatchLogsClient
Async client for Amazon CloudWatch Logs. Cheap to clone (clones share one SDK client).
CloudWatchLogsConfig
Immutable client configuration; build it with CloudWatchLogsConfig::builder or CloudWatchLogsConfig::from_env. Debug output redacts every credential.
CloudWatchLogsConfigBuilder
Builder for CloudWatchLogsConfig. Values set here win over the environment.
CloudWatchLogsExporter
The LogExporter of the client: writes normalized LogRecord JSON documents with PutLogEvents to one log group and stream. gzip is ignored (PutLogEvents has no request compression).
CloudWatchLogsQueryClient
The LogQueryClient over one log group: search uses FilterLogEvents, tail live tail, list_streams DescribeLogStreams; list_labels is UNSUPPORTED.
DeleteOptions
Options of delete_log_group / delete_log_stream.
DescribeLogGroupsOptions
Options of describe_log_groups.
DescribeLogStreamsOptions
Options of describe_log_streams.
DescribeQueriesOptions
Options of describe_queries.
EmfOptions
Options of build_emf and CloudWatchLogsClient::emf.
EnsureLogGroupOptions
Options of ensure_log_group.
EnsureLogGroupResult
What ensure_log_group did.
EnsureLogStreamOptions
Options of ensure_log_stream.
EnsureLogStreamResult
What ensure_log_stream did.
ExporterOptions
Where an exporter or log client writes.
FilterLogEventsOptions
Options of filter_log_events / filter_log_events_page.
FilterLogEventsPage
One FilterLogEvents response.
FilteredLogEvent
One event of FilterLogEvents.
GetLogEventsOptions
Options of get_log_events.
LiveTailEvent
One event of a live-tail session.
LiveTailOptions
Options of start_live_tail.
LiveTailSession
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).
LiveTailUpdate
One sessionUpdate frame of a live-tail session.
LogClientOptions
Options of CloudWatchLogsClient::log_client: where to write plus the batching, resource, redaction and severity options of the generated BatchingLogClient.
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_page or try_collect. Iteration ends when the service returns no token (or the token it was sent), after limit items, or after the first error.
PutLogEventsOptions
Options of put_log_events.
PutLogEventsResult
What put_log_events did.
QueryInfo
One Logs Insights query of describe_queries.
QueryOptions
Options of start_query and query.
QueryResults
Result of get_query_results or query.
QueryStatistics
Scan statistics of a query (AWS only).
RejectedInfo
rejectedLogEventsInfo of one PutLogEvents call. Indexes refer to the timestamp-sorted events of that batch. As returned by AWS, too_old_log_event_end_index and expired_log_event_end_index are exclusive (events [0, index) rejected) and too_new_log_event_start_index is inclusive (events [index, n) rejected). Moto 5.2.4 returns end indexes one lower (see docs/compatibility.md).
StreamLogEvent
One event of GetLogEvents.

Enums§

OversizePolicy
What happens to an event larger than the configured maximum event size.
QueryStatus
Status of a Logs Insights query.
StreamOrder
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::namespace is not set.
DEFAULT_MAX_EVENT_BYTES
Default per-event size policy in UTF-8 bytes (256 KiB).
DEFAULT_QUERY_LIMIT_RETRIES
Default number of StartQuery retries after LimitExceededException.
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 PutLogEvents call: Σ(UTF-8 message bytes + 26).
MAX_BATCH_EVENTS
Maximum number of events in one PutLogEvents call.
MAX_BATCH_SPAN
Largest timestamp span inside one PutLogEvents call.
MAX_DESCRIBE_PAGE_SIZE
Largest DescribeLogGroups / DescribeLogStreams page.
MAX_EVENTS_PAGE_SIZE
Largest FilterLogEvents / GetLogEvents page (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 PutLogEvents call.
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 (or opts.values) is published under metric with dimensions as one dimension set (at most 30). Returns the JSON text; invalid input is VALIDATION. Metric extraction happens inside AWS.
error_code_for_aws
The Grow code for an AWS error code (None when 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 FilterLogEvents event as a LogRecord (see message_to_record) with the attributes aws.log.stream and aws.event.id.
live_tail_event_to_record
A live-tail event as a LogRecord (see message_to_record) with the attribute aws.log.stream and, for plain messages, aws.log.group.
message_to_record
Decodes a CloudWatch Logs message: a normalized LogRecord JSON document (with timestamp and body) is decoded as such; any other message becomes an INFO record with the message as body, timestamp as timestamp and ingested as observed timestamp.
parse_query_timestamp
Parses an Insights @timestamp value: the AWS form 2006-01-02 15:04:05.000 (UTC) or epoch milliseconds (Moto). VALIDATION for anything else.
partition_of
The AWS partition of a region.
truncate_message
Shortens message to at most max_bytes UTF-8 bytes, cutting on a character boundary and appending …[truncated N bytes] (N = bytes removed). Messages that fit are returned unchanged; when max_bytes is smaller than the marker the message is cut without it.
validate_group_name
VALIDATION unless name is a valid log group name (1–512 of [.-_/#A-Za-z0-9]).
validate_stream_name
VALIDATION unless name is a valid log stream name (1–512 characters, no : or *).

Type Aliases§

CloudWatchLogsError
Service-prefixed alias of Error.
LiveTailCallback
Callback receiving live-tail events.
LiveTailErrorCallback
Callback receiving the error that ended a live-tail session.
LiveTailUpdateCallback
Callback receiving live-tail update frames.