tracing_cloudwatch/lib.rs
1//! tracing-cloudwatch is a custom tracing-subscriber layer that sends your application's tracing events(logs) to AWS CloudWatch Logs.
2//!
3//! We have supported [rusoto](https://github.com/rusoto/rusoto) and the [AWS SDK](https://github.com/awslabs/aws-sdk-rust) as AWS clients.
4//!
5//! ## Usage
6//!
7//! ### With Rusoto
8//!
9//! feature `rusoto` required
10//!
11//! ```rust,no_run
12//! # #[cfg(feature = "rusoto")]
13//! # {
14//! use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
15//!
16//! #[tokio::main]
17//! async fn main() {
18//! let cw_client = rusoto_logs::CloudWatchLogsClient::new(rusoto_core::Region::ApNortheast1);
19//!
20//! let (cw_layer, cw_guard) = tracing_cloudwatch::layer().with_client(
21//! cw_client,
22//! tracing_cloudwatch::ExportConfig::default()
23//! .with_batch_size(5)
24//! .with_interval(std::time::Duration::from_secs(1))
25//! .with_log_group_name("tracing-cloudwatch")
26//! .with_log_stream_name("stream-1"),
27//! );
28//!
29//! tracing_subscriber::registry::Registry::default()
30//! .with(cw_layer)
31//! .init();
32//!
33//! cw_guard.shutdown().await;
34//! }
35//! # }
36//! ```
37//!
38//! ### With AWS SDK
39//!
40//! feature `awssdk` required
41//!
42//! ```rust,no_run
43//! # #[cfg(feature = "awssdk")]
44//! # {
45//! use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
46//!
47//! #[tokio::main]
48//! async fn main() {
49//! let config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
50//! let cw_client = aws_sdk_cloudwatchlogs::Client::new(&config);
51//!
52//! let (cw_layer, cw_guard) = tracing_cloudwatch::layer().with_client(
53//! cw_client,
54//! tracing_cloudwatch::ExportConfig::default()
55//! .with_batch_size(5)
56//! .with_interval(std::time::Duration::from_secs(1))
57//! .with_log_group_name("tracing-cloudwatch")
58//! .with_log_stream_name("stream-1"),
59//! );
60//!
61//! tracing_subscriber::registry::Registry::default()
62//! .with(cw_layer)
63//! .init();
64//!
65//! cw_guard.shutdown().await;
66//! }
67//! # }
68//! ```
69//!
70//! ## Required Permissions
71//!
72//! Currently, following AWS IAM Permissions required
73//!
74//! * `logs:PutLogEvents`
75//!
76//! ## CloudWatch Log Groups and Streams
77//!
78//! This crate does not create a log group and log stream, so if the specified log group and log stream does not exist, it will raise an error.
79//!
80//! ## Retry and Timeout
81//!
82//! We haven't implemented any custom retry logic or timeout settings within the crate. We assume that these configurations are handled through the SDK Client.
83//! For instance, in the AWS SDK, you can set up these configurations using [`timeout_config`](https://docs.rs/aws-sdk-cloudwatchlogs/0.28.0/aws_sdk_cloudwatchlogs/config/struct.Builder.html#method.timeout_config) and [`retry_config`](https://docs.rs/aws-sdk-cloudwatchlogs/0.28.0/aws_sdk_cloudwatchlogs/config/struct.Builder.html#method.retry_config)
84
85mod client;
86mod dispatch;
87mod export;
88mod guard;
89mod layer;
90
91pub use client::CloudWatchClient;
92pub use dispatch::{CloudWatchDispatcher, NoopDispatcher};
93pub use export::{ExportConfig, LogDestination};
94pub use guard::CloudWatchWorkerGuard;
95pub use layer::{CloudWatchLayer, layer};