async_profiler_agent/
lib.rs

1// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4#![deny(missing_docs)]
5
6//! ## async-profiler Rust agent
7//! An in-process Rust agent for profiling an application using [async-profiler] and uploading the resulting profiles.
8//!
9//! [async-profiler]: https://github.com/async-profiler/async-profiler
10//!
11//! ### OS/CPU Support
12//!
13//! This Rust agent currently only supports Linux, on either x86-64 or aarch64.
14//!
15//! ### Usage
16//!
17//! The agent runs the profiler and uploads the output periodically via a reporter.
18//!
19//! When starting, the profiler [dlopen(3)]'s `libasyncProfiler.so` and returns an [`Err`] if it is not found,
20//! so make sure there is a `libasyncProfiler.so` in the search path[^1].
21//!
22//! [^1]: the dlopen search path includes RPATH and LD_LIBRARY_PATH, but *not* the current directory to avoid current directory attacks.
23//!
24//! [dlopen(3)]: https://linux.die.net/man/3/dlopen
25//!
26//! You can use the [`S3Reporter`], which uploads the reports to an S3 bucket, as follows:
27//!
28#![cfg_attr(feature = "s3-no-defaults", doc = "```no_run")]
29#![cfg_attr(not(feature = "s3-no-defaults"), doc = "```compile_fail")]
30//! # use async_profiler_agent::profiler::{ProfilerBuilder, SpawnError};
31//! # use async_profiler_agent::reporter::s3::{S3Reporter, S3ReporterConfig};
32//! # use aws_config::BehaviorVersion;
33//! # #[tokio::main]
34//! # async fn main() -> Result<(), SpawnError> {
35//!
36//! let bucket_owner = "<your account id>";
37//! let bucket_name = "<your bucket name>";
38//! let profiling_group = "a-name-to-give-the-uploaded-data";
39//!
40//! let sdk_config = aws_config::defaults(BehaviorVersion::latest()).load().await;
41//!
42//! let profiler = ProfilerBuilder::default()
43//!    .with_reporter(S3Reporter::new(S3ReporterConfig {
44//!        sdk_config: &sdk_config,
45//!        bucket_owner: bucket_owner.into(),
46//!        bucket_name: bucket_name.into(),
47//!        profiling_group_name: profiling_group.into(),
48//!    }))
49//!    .build();
50//!
51//! profiler.spawn()?;
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! The [`S3Reporter`] uploads each report in a `zip` file, that currently contains 2 files:
57//! 1. a [JFR] as `async_profiler_dump_0.jfr`
58//! 2. metadata as `metadata.json`, in format [`reporter::s3::MetadataJson`].
59//!
60//! The `zip` file is uploaded to the bucket under the path `profile_{profiling_group_name}_{machine}_{pid}_{time}.zip`,
61//! where `{machine}` is either `ec2_{ec2_instance_id}_`, `ecs_{cluster_arn}_{task_arn}`, or `onprem__`.
62//!
63//! In addition to the S3 reporter, this crate also includes [`LocalReporter`] that writes to a directory, and a `MultiReporter` that allows combining reporters. You can also write your own reporter (via the `Reporter` trait) to upload the profile results to your favorite profiler backend.
64//!
65//! [`LocalReporter`]: reporter::local::LocalReporter
66//! [`S3Reporter`]: reporter::s3::S3Reporter
67//! [JFR]: https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm
68//!
69//! #### Sample program
70//!
71//! You can test the agent by using the sample program, for example:
72//!
73//! ```notrust
74//! LD_LIBRARY_PATH=/path/to/libasyncProfiler.so cargo run --release --example simple -- --profiling-group PG --bucket-owner YOUR-AWS-ACCOUNT-ID --bucket YOUR_BUCKET_ID
75//! ```
76//!
77//! ### Host Metadata Auto-Detection
78//!
79//! The Rust agent currently auto-detects the machine's [EC2] or [Fargate] id using [IMDS].
80//!
81//! If you want to run the agent on a machine that is not EC2 or Fargate, you can use [`profiler::ProfilerBuilder::with_custom_agent_metadata`] to provide your own metadata.
82//!
83//! The metadata is not used by the agent directly, and only provided to the reporters, to allow them to associate the profiling data with the correct host. In the S3 reporter, it's used to generate the `metadata.json` and zip file name.
84//!
85//! [EC2]: https://aws.amazon.com/ec2
86//! [Fargate]: https://aws.amazon.com/fargate
87//! [IMDS]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
88//!
89//! ### PollCatch
90//!
91//! If you want to find long poll times, and you have `RUSTFLAGS="--cfg tokio_unstable"`, see the
92//! [pollcatch] module for emitting `tokio.PollCatchV1` events.
93mod asprof;
94
95pub mod metadata;
96pub mod pollcatch;
97pub mod profiler;
98pub mod reporter;
async_profiler_agent/lib.rs

async_profiler_agent/
lib.rs
