xray_lite/
lib.rs

1#![warn(missing_docs)]
2//#![deny(warnings)]
3//! Provides a client interface for [AWS X-Ray](https://aws.amazon.com/xray/)
4//!
5//! ### Examples
6//!
7//! #### Subsegment of AWS service operation
8//!
9//! **The [`xray_lite_aws_sdk`](https://docs.rs/xray-lite-aws-sdk) extension is
10//! recommended for tracing operations through
11//! [AWS SDK for Rust](https://aws.amazon.com/sdk-for-rust/).**
12//!
13//! Here is an example to record a subsegment of an AWS service operation
14//! within a Lambda function invocation instrumented with AWS X-Ray:
15//!
16//! ```
17//! use xray_lite::{AwsNamespace, Context, DaemonClient, SubsegmentContext};
18//!
19//! fn main() {
20//!    // reads AWS_XRAY_DAEMON_ADDRESS
21//!    # std::env::set_var("AWS_XRAY_DAEMON_ADDRESS", "127.0.0.1:2000");
22//!    let client = DaemonClient::from_lambda_env().unwrap();
23//!    // reads _X_AMZN_TRACE_ID
24//!    # std::env::set_var("_X_AMZN_TRACE_ID", "Root=1-65dfb5a1-0123456789abcdef01234567;Parent=0123456789abcdef;Sampled=1");
25//!    let context = SubsegmentContext::from_lambda_env(client).unwrap();
26//!
27//!    do_s3_get_object(&context);
28//! }
29//!
30//! fn do_s3_get_object(context: &impl Context) {
31//!     // subsegment will have the name "S3" and `aws.operation` "GetObject"
32//!     let subsegment = context.enter_subsegment(AwsNamespace::new("S3", "GetObject"));
33//!
34//!     // call S3 GetObject ...
35//!
36//!     // if you are using `aws-sdk-s3` crate, you can update the subsegment
37//!     // with the request ID. suppose `out` is the output of the `GetObject`
38//!     // operation:
39//!     //
40//!     //     subsegment
41//!     //         .namespace_mut()
42//!     //         .zip(out.request_id())
43//!     //         .map(|(ns, id)| ns.request_id(id));
44//!
45//!     // the subsegment will be ended and reported when it is dropped
46//! }
47//! ```
48//!
49//! #### Subsegment of remote service call
50//!
51//! Here is an example to record a subsegment of a remote service call within a
52//! Lambda function invocation intstrumented with AWS X-Ray:
53//!
54//! ```
55//! use xray_lite::{Context, DaemonClient, RemoteNamespace, SubsegmentContext};
56//!
57//! fn main() {
58//!    // reads AWS_XRAY_DAEMON_ADDRESS
59//!    # std::env::set_var("AWS_XRAY_DAEMON_ADDRESS", "127.0.0.1:2000");
60//!    let client = DaemonClient::from_lambda_env().unwrap();
61//!    // reads _X_AMZN_TRACE_ID
62//!    # std::env::set_var("_X_AMZN_TRACE_ID", "Root=1-65dfb5a1-0123456789abcdef01234567;Parent=0123456789abcdef;Sampled=1");
63//!    let context = SubsegmentContext::from_lambda_env(client).unwrap();
64//!
65//!    do_some_request(&context);
66//! }
67//!
68//! fn do_some_request(context: &impl Context) {
69//!     // subsegment will have the name "readme example",
70//!     // `http.request.method` "POST", and `http.request.url` "https://codemonger.io/"
71//!     let subsegment = context.enter_subsegment(RemoteNamespace::new(
72//!         "readme example",
73//!         "GET",
74//!         "https://codemonger.io/",
75//!     ));
76//!
77//!     // do some request ...
78//!
79//!     // the subsegment will be ended and reported when it is dropped
80//! }
81//! ```
82//!
83//! #### Custom subsegment
84//!
85//! Here is an example to record a custom subsegment within a Lambda function
86//! invocation intstrumented with AWS X-Ray:
87//!
88//! ```
89//! use xray_lite::{Context, DaemonClient, CustomNamespace, SubsegmentContext};
90//!
91//! fn main() {
92//!    // reads AWS_XRAY_DAEMON_ADDRESS
93//!    # std::env::set_var("AWS_XRAY_DAEMON_ADDRESS", "127.0.0.1:2000");
94//!    let client = DaemonClient::from_lambda_env().unwrap();
95//!    // reads _X_AMZN_TRACE_ID
96//!    # std::env::set_var("_X_AMZN_TRACE_ID", "Root=1-65dfb5a1-0123456789abcdef01234567;Parent=0123456789abcdef;Sampled=1");
97//!    let context = SubsegmentContext::from_lambda_env(client).unwrap()
98//!        .with_name_prefix("readme_example.");
99//!
100//!    do_something(&context);
101//! }
102//!
103//! fn do_something(context: &impl Context) {
104//!     // subsegment will have the name "readme_example.do_something"
105//!     let subsegment = context.enter_subsegment(CustomNamespace::new("do_something"));
106//!
107//!     // do some thing ...
108//!
109//!     // the subsegment will be ended and reported when it is dropped
110//! }
111//! ```
112//!
113//! ### Acknowledgements
114//!
115//! This crate is based on the [great work](https://github.com/softprops/xray)
116//! by [Doug Tangren (softprops)](https://github.com/softprops).
117
118mod client;
119mod context;
120mod epoch;
121mod error;
122mod header;
123mod hexbytes;
124mod lambda;
125mod namespace;
126mod segment;
127mod segment_id;
128mod session;
129mod trace_id;
130
131pub use crate::{
132    client::{Client, DaemonClient, InfallibleClient, IntoInfallibleClient},
133    context::{Context, InfallibleContext, IntoInfallibleContext, SubsegmentContext},
134    epoch::Seconds,
135    error::{Error, Result},
136    header::Header,
137    namespace::{AwsNamespace, CustomNamespace, Namespace, RemoteNamespace},
138    segment::*,
139    segment_id::SegmentId,
140    session::SubsegmentSession,
141    trace_id::TraceId,
142};
xray_lite/lib.rs

xray_lite/
lib.rs
