Merge pull request #32 from arielb1/deny-missing-docs

deny missing docs

Author: arielb1

.github/workflows/build.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           toolchain: ${{ matrix.toolchain }}
   build-for-testing:
-    name: Build For Testing
+    name: Build for testing
     runs-on: ubuntu-latest
     env:
       RUSTFLAGS: --cfg tokio_unstable

README.md

@@ -38,7 +38,7 @@ let profiler = ProfilerBuilder::default()
         sdk_config: &sdk_config,
         bucket_owner: bucket_owner.into(),
         bucket_name: bucket_name.into(),
-        profiling_group: profiling_group.into(),
+        profiling_group_name: profiling_group.into(),
     }))
     .build();
 

src/lib.rs

@@ -1,7 +1,94 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+#![deny(missing_docs)]
+
+//! ## async-profiler Rust agent
+//! An in-process Rust agent for profiling an application using [async-profiler] and uploading the resulting profiles.
+//!
+//! [async-profiler]: https://github.com/async-profiler/async-profiler
+//!
+//! ### OS/CPU Support
+//!
+//! This Rust agent currently only supports Linux, on either x86-64 or aarch64.
+//!
+//! ### Usage
+//!
+//! The agent runs the profiler and uploads the output periodically via a reporter.
+//!
+//! When starting, the profiler [dlopen(3)]'s `libasyncProfiler.so` and returns an [`Err`] if it is not found,
+//! so make sure there is a `libasyncProfiler.so` in the search path[^1].
+//!
+//! [^1]: the dlopen search path includes RPATH and LD_LIBRARY_PATH, but *not* the current directory to avoid current directory attacks.
+//! [dlopen(3)]: <https://linux.die.net/man/3/dlopen>
+//!
+//! You can use the [S3Reporter], which uploads the reports to an S3 bucket, as follows:
+//!
+//! ```no_run
+//! # use async_profiler_agent::profiler::{ProfilerBuilder, SpawnError};
+//! # use async_profiler_agent::reporter::s3::{S3Reporter, S3ReporterConfig};
+//! # use aws_config::BehaviorVersion;
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), SpawnError> {
+//!
+//! let bucket_owner = "<your account id>";
+//! let bucket_name = "<your bucket name>";
+//! let profiling_group = "a-name-to-give-the-uploaded-data";
+//!
+//! let sdk_config = aws_config::defaults(BehaviorVersion::latest()).load().await;
+//!
+//! let profiler = ProfilerBuilder::default()
+//!    .with_reporter(S3Reporter::new(S3ReporterConfig {
+//!        sdk_config: &sdk_config,
+//!        bucket_owner: bucket_owner.into(),
+//!        bucket_name: bucket_name.into(),
+//!        profiling_group_name: profiling_group.into(),
+//!    }))
+//!    .build();
+//!
+//! profiler.spawn()?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! The [S3Reporter] uploads each report in a `zip` file, that currently contains 2 files:
+//! 1. a [JFR] as `async_profiler_dump_0.jfr`
+//! 2. metadata as `metadata.json`, in format [`reporter::s3::MetadataJson`].
+//!
+//! The `zip` file is uploaded to the bucket under the path `profile_{profiling_group_name}_{machine}_{pid}_{time}.zip`,
+//! where `{machine}` is either `ec2_{ec2_instance_id}_`, `ecs_{cluster_arn}_{task_arn}`, or `onprem__`.
+//!
+//! 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.
+//!
+//! [`LocalReporter`]: reporter::local::LocalReporter
+//! [JFR]: https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm
+//!
+//! #### Sample program
+//!
+//! You can test the agent by using the sample program, for example:
+//!
+//! ```notrust
+//! 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
+//! ```
+//!
+//! ### Host Metadata Auto-Detection
+//!
+//! The Rust agent currently auto-detects the machine's [EC2] or [Fargate] id using [IMDS].
+//!
+//! 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.
+//!
+//! 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.
+//!
+//! [EC2]: https://aws.amazon.com/ec2
+//! [Fargate]: https://aws.amazon.com/fargate
+//! [IMDS]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
+//!
+//! ### PollCatch
+//!
+//! If you want to find long poll times, and you have `RUSTFLAGS="--cfg tokio_unstable"`, see the
+//! [pollcatch] module for emitting `tokio.PollCatchV1` events.
 mod asprof;
+
 pub mod metadata;
 pub mod pollcatch;
 pub mod profiler;

src/metadata/aws.rs

@@ -1,43 +1,62 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! Contains functions for getting host metadata from [IMDS]
+//!
+//! [IMDS]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
+
 use reqwest::Method;
 use serde::Deserialize;
 use thiserror::Error;
 
 use super::AgentMetadata;
 
+/// An error converting Fargate IMDS metadata to Agent metadata. This error
+/// should probably not happen except in case of a bug in either this crate or IMDS.
 #[derive(Error, Debug)]
 pub enum FargateMetadataToAgentMetadataError {
+    /// unable to parse task ARN as a valid ARN
     #[error("unable to parse task ARN as a valid ARN")]
     TaskArnInvalid(#[from] aws_arn::Error),
+    /// AWS account id not found in Fargate metadata
     #[error("AWS account id not found in Fargate metadata")]
     AccountIdNotFound,
+    /// AWS region not found in Fargate metadata
     #[error("AWS region not found in Fargate metadata")]
     AwsRegionNotFound,
 }
 
+/// An error getting IMDS metadata
 #[derive(Error, Debug)]
 #[error("profiler metadata error: {0}")]
 pub enum AwsProfilerMetadataError {
+    /// Internal IO error
     #[error("failed to create profiler metadata file: {0}")]
     FailedToCreateFile(#[from] std::io::Error),
 
+    /// Error parsing IMDS metadata. Should normally not happen except in case of a bug
     #[error("failed fetching valid Fargate metadata: {0}")]
     FargateMetadataToAgentMetadataError(#[from] FargateMetadataToAgentMetadataError),
 
-    #[error("retrieved invalid endpoint URI: {0}")]
+    /// Invalid endpoint URI in `ECS_CONTAINER_METADATA_URI_V4`
+    #[error("retrieved invalid endpoint URI from ECS_CONTAINER_METADATA_URI_V4: {0}")]
     InvalidUri(String),
 
+    /// Failed to fetch metadata from FarGate endpoint
     #[error("failed to fetch metadata from endpoint over HTTP: {0}")]
     FailedToFetchMetadataFromEndpoint(reqwest::Error),
 
+    /// Failed to fetch metadata from IMDS
     #[error("failed to fetch metadata from IMDS endpoint over HTTP: {0}")]
     FailedToFetchMetadataFromImds(#[from] aws_config::imds::client::error::ImdsError),
 
+    /// Failed to parse metadata from IMDS - this indicates a bug in this crate
+    /// or in IMDS
     #[error("failed to parse metadata as valid UTF-8 from endpoint over HTTP: {0}")]
     FailedToParseMetadataFromEndpoint(reqwest::Error),
 
+    /// Failed to serialize metadata file - this indicates a bug in this crate
+    /// or in IMDS
     #[error("failed to serialize metadata file: {0}")]
     FailedToSerializeMetadataFile(#[from] serde_json::Error),
 }
@@ -132,6 +151,13 @@ impl super::AgentMetadata {
     }
 }
 
+/// Load agent metadata from [Fargate] or [IMDS].
+///
+/// This will return an error if this machine does not appear to be a [Fargate] or [EC2].
+///
+/// [Fargate]: https://aws.amazon.com/fargate
+/// [IMDS]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
+/// [EC2]: https://aws.amazon.com/ec2
 pub async fn load_agent_metadata() -> Result<AgentMetadata, AwsProfilerMetadataError> {
     let agent_metadata: AgentMetadata = match read_ec2_metadata().await {
         Ok(imds_ec2_instance_metadata) => {

src/metadata/mod.rs

@@ -1,30 +1,62 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! This module includes ways to get metadata attached to profiling reports.
+
 pub use std::time::Duration;
 
+/// Host Metadata, which describes a host that runs a profiling agent. The current set of supported agent metadata is
+/// AWS-specific. If you are not running on AWS, you can use [AgentMetadata::Other].
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum AgentMetadata {
+    /// Metadata for an [EC2] instance running on AWS
+    ///
+    /// [EC2]: https://aws.amazon.com/ec2
     Ec2AgentMetadata {
+        /// The AWS account id
         aws_account_id: String,
+        /// The AWS region id
         aws_region_id: String,
+        /// The EC2 instance id
         ec2_instance_id: String,
     },
+    /// Metadata for a [Fargate] task running on AWS.
+    ///
+    /// [Fargate]: https://aws.amazon.com/fargate
     FargateAgentMetadata {
+        /// The AWS account id
         aws_account_id: String,
+        /// The AWS region id
         aws_region_id: String,
+        /// The ECS task ARN
+        ///
+        /// For example, `arn:aws:ecs:us-east-1:123456789012:task/profiler-metadata-cluster/5261e761e0e2a3d92da3f02c8e5bab1f`
+        ///
+        /// See the ECS documentation for more details
         ecs_task_arn: String,
+        /// The ECS cluster ARN
+        ///
+        /// For example, `arn:aws:ecs:us-east-1:123456789012:cluster/profiler-metadata-cluster`
+        ///
+        /// See the ECS documentation for more details
         ecs_cluster_arn: String,
     },
+    /// Metadata for a host that is neither an EC2 nor a Fargate
     Other,
 }
 
+/// Metadata associated with a specific individual profiling report
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ReportMetadata<'a> {
+    /// The host running the agent
     pub instance: &'a AgentMetadata,
+    /// The start time of the profiling report, as a duration from the process start
     pub start: Duration,
+    /// The end time of the profiling report, as a duration from the process start
     pub end: Duration,
+    /// The desired reporting interval (on average, this should be
+    /// approximately the same as `self.end - self.start`).
     pub reporting_interval: Duration,
 }
 

src/pollcatch/mod.rs

@@ -1,3 +1,30 @@
+//! To emit `tokio.PollCatchV1` events, you can set up the task hooks when setting up your Tokio runtime:
+//!
+//! Then, you can use the `decoder` (look at the crate README) to find long polls in your program.
+//!
+//! Use it around your `main` like this:
+//! ```
+//! # async fn your_main() {}
+//!
+//! let mut rt: tokio::runtime::Builder = tokio::runtime::Builder::new_multi_thread();
+//! rt.enable_all();
+//!
+//! #[cfg(tokio_unstable)]
+//! {
+//!     rt.on_before_task_poll(|_| async_profiler_agent::pollcatch::before_poll_hook())
+//!      .on_after_task_poll(|_| async_profiler_agent::pollcatch::after_poll_hook());
+//! }
+//! let rt = rt.build().unwrap();
+//! rt.block_on(your_main())
+//! ```
+//!
+//! Except on a poll that is involved in a profiling sample, the poll hook overhead
+//! is limited to a few thread-local accesses and should be very very fast.
+//!
+//! When a profiling sample is taken (normally around 1 / second), it adds slightly
+//! more overhead to report the sample, but that is a matter of microseconds
+//! and therefore should not worsen tail latency problems.
+
 use std::{
     cell::Cell,
     sync::{

src/profiler.rs

@@ -1,6 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! A profiler that periodically uploads profiling samples of your program to a [Reporter]
+
 use crate::{
     asprof::{self, AsProfError},
     metadata::{aws::AwsProfilerMetadataError, AgentMetadata, ReportMetadata},
@@ -206,9 +208,12 @@ enum TickError {
 
 #[derive(Debug, Error)]
 #[non_exhaustive]
+/// An error that happened spawning a profiler
 pub enum SpawnError {
+    /// Error interactive with async-profiler
     #[error(transparent)]
     AsProf(#[from] asprof::AsProfError),
+    /// Error writing to a tempfile
     #[error("tempfile error: {0}")]
     TempFile(io::Error),
 }

src/reporter/local.rs

@@ -1,6 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! A reporter that reports into a directory.
+
 use async_trait::async_trait;
 use chrono::SecondsFormat;
 use std::path::PathBuf;

src/reporter/mod.rs

@@ -1,6 +1,13 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+//! This module contains [Reporter]s that upload profiling data to a destination.
+//!
+//! The following [Reporter]s are included:
+//! 1. [local::LocalReporter], which uploads profiling data to a local directory
+//! 2. [s3::S3Reporter], which uploads profiling data to an S3 bucket
+//! 3. [multi::MultiReporter], which allows combining multiple reporters.
+
 use std::fmt;
 
 use async_trait::async_trait;
@@ -15,6 +22,17 @@ pub mod s3;
 /// Abstraction around reporting profiler data.
 #[async_trait]
 pub trait Reporter: fmt::Debug {
+    /// Takes a profiling sample, including JFR data and sample metadata,
+    /// and uploads it towards a destination.
+    ///
+    /// If this function returns an error, the sample will be dropped
+    /// but profiling will continue, and this function will be called
+    /// again for the next sample (or theoretically, a future version
+    /// might have configuration that will an attempt to re-upload the
+    /// current sample will be made - but today's [`Profiler`] does
+    /// not make any such attempts).
+    ///
+    /// [`Profiler`]: crate::profiler::Profiler
     async fn report(
         &self,
         jfr: Vec<u8>,

src/reporter/multi.rs

@@ -1,3 +1,5 @@
+//! A reporter that reports profiling results to several destinations.
+
 use async_trait::async_trait;
 
 use crate::metadata::ReportMetadata;
@@ -69,7 +71,7 @@ impl Reporter for MultiReporter {
 }
 
 #[cfg(test)]
-pub mod test {
+mod test {
     use std::{
         sync::{
             atomic::{self, AtomicBool},