Documentation: note metrics that will be set in captures

src/blackhole/http.rs

@@ -1,4 +1,10 @@
 //! The HTTP protocol speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `bytes_received`: Total bytes received
+//! `requests_received`: Total requests received
+//!
 
 use std::{net::SocketAddr, time::Duration};
 

src/blackhole/splunk_hec.rs

@@ -1,4 +1,10 @@
 //! The Splunk HEC protocol speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `bytes_received`: Total bytes received
+//! `requests_received`: Total requests received
+//!
 
 use std::{
     collections::HashMap,

src/blackhole/sqs.rs

@@ -1,4 +1,10 @@
 //! The [SQS](https://aws.amazon.com/sqs/) protocol speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `bytes_received`: Total bytes received
+//! `requests_received`: Total messages received
+//!
 
 use std::{fmt::Write, net::SocketAddr};
 

src/blackhole/tcp.rs

@@ -1,4 +1,11 @@
 //! The TCP protocol speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `connection_accepted`: Incoming connections received
+//! `bytes_received`: Total bytes received
+//! `message_received`: Total messages received
+//!
 
 use std::{io, net::SocketAddr};
 

src/blackhole/udp.rs

@@ -1,4 +1,10 @@
 //! The UDP protocol speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `bytes_received`: Total bytes received
+//! `packet_received`: Total packets received
+//!
 
 use std::{io, net::SocketAddr};
 

src/blackhole/unix_datagram.rs

@@ -1,4 +1,9 @@
 //! The Unix Domain Socket datagram speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `bytes_received`: Total bytes received
+//!
 
 use std::{io, path::PathBuf};
 

src/blackhole/unix_stream.rs

@@ -1,4 +1,11 @@
 //! The Unix Domain Socket stream speaking blackhole.
+//!
+//! ## Metrics
+//!
+//! `connection_accepted`: Incoming connections received
+//! `bytes_received`: Total bytes received
+//! `requests_received`: Total requests received
+//!
 
 use std::{io, path::PathBuf};
 

src/generator.rs

@@ -7,7 +7,7 @@
 //! into the target according to a user-defined rate limit in a cyclic
 //! manner. That is, we avoid runtime delays in payload generation by, well,
 //! building a lot of payloads in one shot and rotating through them
-//! indefinately, paying higher memory and longer startup for better
+//! indefinitely, paying higher memory and longer startup for better
 //! experimental control.
 
 use serde::Deserialize;
@@ -39,15 +39,15 @@ pub enum Error {
     SplunkHec(splunk_hec::Error),
     /// See [`crate::generator::file_gen::Error`] for details.
     FileGen(file_gen::Error),
-    /// See [`crate::generator::file_tree_gen::Error`] for details.
+    /// See [`crate::generator::file_tree::Error`] for details.
     FileTree(file_tree::Error),
     /// See [`crate::generator::grpc::Error`] for details.
     Grpc(grpc::Error),
     /// See [`crate::generator::unix_stream::Error`] for details.
     UnixStream(unix_stream::Error),
     /// See [`crate::generator::unix_datagram::Error`] for details.
     UnixDatagram(unix_datagram::Error),
-    /// See [`crate::generator::process_tree_gen::Error`] for details.
+    /// See [`crate::generator::process_tree::Error`] for details.
     ProcessTree(process_tree::Error),
 }
 
@@ -85,15 +85,15 @@ pub enum Inner {
     SplunkHec(splunk_hec::Config),
     /// See [`crate::generator::file_gen::Config`] for details.
     FileGen(file_gen::Config),
-    /// See [`crate::generator::file_tree_gen::Config`] for details.
+    /// See [`crate::generator::file_tree::Config`] for details.
     FileTree(file_tree::Config),
     /// See [`crate::generator::grpc::Config`] for details.
     Grpc(grpc::Config),
     /// See [`crate::generator::unix_stream::Config`] for details.
     UnixStream(unix_stream::Config),
     /// See [`crate::generator::unix_datagram::Config`] for details.
     UnixDatagram(unix_datagram::Config),
-    /// See [`crate::generator::process_tree_gen::Config`] for details.
+    /// See [`crate::generator::process_tree::Config`] for details.
     ProcessTree(process_tree::Config),
 }
 
@@ -113,15 +113,15 @@ pub enum Server {
     SplunkHec(splunk_hec::SplunkHec),
     /// See [`crate::generator::file_gen::FileGen`] for details.
     FileGen(file_gen::FileGen),
-    /// See [`crate::generator::file_tree_gen::FileTree`] for details.
+    /// See [`crate::generator::file_tree::FileTree`] for details.
     FileTree(file_tree::FileTree),
     /// See [`crate::generator::grpc::Grpc`] for details.
     Grpc(grpc::Grpc),
     /// See [`crate::generator::unix_stream::UnixStream`] for details.
     UnixStream(unix_stream::UnixStream),
     /// See [`crate::generator::unix_datagram::UnixDatagram`] for details.
     UnixDatagram(unix_datagram::UnixDatagram),
-    /// See [`crate::generator::process_tree_gen::ProcessTree`] for details.
+    /// See [`crate::generator::process_tree::ProcessTree`] for details.
     ProcessTree(process_tree::ProcessTree),
 }
 

src/generator/file_gen.rs

@@ -3,6 +3,14 @@
 //! Unlike the other generators the file generator does not "connect" however
 //! losely to the target but instead, without coordination, merely writes files
 //! on disk.
+//!
+//! ## Metrics
+//!
+//! `bytes_written`: Total bytes written
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use std::{
     num::{NonZeroU32, NonZeroUsize},
@@ -63,7 +71,7 @@ pub struct Config {
     pub path_template: String,
     /// Total number of duplicates to make from this template.
     pub duplicates: u8,
-    /// Sets the [`lading::payload::Config`] of this template.
+    /// Sets the [`crate::payload::Config`] of this template.
     pub variant: payload::Config,
     /// Sets the **soft** maximum bytes to be written into the `LogTarget`. This
     /// limit is soft, meaning a burst may go beyond this limit by no more than

src/generator/file_tree.rs

@@ -1,8 +1,14 @@
 //! The file tree generator.
 //!
 //! Unlike the other generators the file generator does not "connect" however
-//! losely to the target but instead, without coordination, merely generates
-//! a file tree and generates random acess/rename operations.
+//! loosely to the target but instead, without coordination, merely generates
+//! a file tree and generates random access/rename operations.
+//!
+//! ## Metrics
+//!
+//! This generator does not emit any metrics. Some metrics may be emitted by the
+//! configured [throttle].
+//!
 
 use rand::{
     distributions::{Alphanumeric, DistString},

src/generator/grpc.rs

@@ -1,4 +1,16 @@
-//! The gRPC generator
+//! The gRPC generator.
+//!
+//! ## Metrics
+//!
+//! `requests_sent`: Total number of requests sent
+//! `request_ok`: Successful requests
+//! `request_failure`: Failed requests
+//! `bytes_written`: Total bytes written
+//! `response_bytes`: Total bytes received
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use std::{
     convert::TryFrom,

src/generator/http.rs

@@ -1,4 +1,15 @@
 //! The HTTP protocol speaking generator.
+//!
+//! ## Metrics
+//!
+//! `requests_sent`: Total number of requests sent
+//! `request_ok`: Successful requests
+//! `request_failure`: Failed requests
+//! `bytes_written`: Total bytes written
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use std::num::{NonZeroU32, NonZeroUsize};
 

src/generator/process_tree.rs

@@ -1,8 +1,14 @@
 //! The process tree generator.
 //!
 //! Unlike the other generators the process tree generator does not "connect" however
-//! losely to the target but instead, without coordination, merely generates
+//! loosely to the target but instead, without coordination, merely generates
 //! a process tree.
+//!
+//! ## Metrics
+//!
+//! This generator does not emit any metrics. Some metrics may be emitted by the
+//! configured [throttle].
+//!
 
 use crate::{
     signals::Shutdown,

src/generator/splunk_hec.rs

@@ -1,4 +1,18 @@
 //! The Splunk HEC generator.
+//!
+//! ## Metrics
+//!
+//! `maximum_requests`: Total number of parallel connections to maintain
+//! `requests_sent`: Total number of requests sent
+//! `request_ok`: Successful requests
+//! `request_failure`: Failed requests
+//! `request_timeout`: Requests that timed out (these are not included in `request_failure`)
+//! `bytes_written`: Total bytes written
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
+//!
 
 mod acknowledgements;
 

src/generator/tcp.rs

@@ -1,4 +1,15 @@
 //! The TCP protocol speaking generator.
+//!
+//! ## Metrics
+//!
+//! `bytes_written`: Bytes sent successfully
+//! `packets_sent`: Packets sent successfully
+//! `request_failure`: Number of failed writes; each occurrence causes a reconnect
+//! `connection_failure`: Number of connection failures
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use std::{
     net::{SocketAddr, ToSocketAddrs},

src/generator/udp.rs

@@ -1,4 +1,15 @@
 //! The UDP protocol speaking generator.
+//!
+//! ## Metrics
+//!
+//! `bytes_written`: Bytes written successfully
+//! `packets_sent`: Packets written successfully
+//! `request_failure`: Number of failed writes; each occurrence causes a socket re-bind
+//! `connection_failure`: Number of socket bind failures
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use std::{
     net::{SocketAddr, ToSocketAddrs},

src/generator/unix_datagram.rs

@@ -1,4 +1,15 @@
 //! The Unix Domain Socket datagram speaking generator.
+//!
+//! ## Metrics
+//!
+//! `bytes_written`: Bytes sent successfully
+//! `packets_sent`: Packets sent successfully
+//! `request_failure`: Number of failed writes; each occurrence causes a reconnect
+//! `connection_failure`: Number of connection failures
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use crate::{
     block::{self, chunk_bytes, construct_block_cache, Block},

src/generator/unix_stream.rs

@@ -1,4 +1,15 @@
 //! The Unix Domain Socket stream speaking generator.
+//!
+//! ## Metrics
+//!
+//! `bytes_written`: Bytes sent successfully
+//! `packets_sent`: Packets sent successfully
+//! `request_failure`: Number of failed writes; each occurrence causes a reconnect
+//! `connection_failure`: Number of connection failures
+//! `bytes_per_second`: Configured rate to send data
+//!
+//! Additional metrics may be emitted by this generator's [throttle].
+//!
 
 use crate::{
     block::{self, chunk_bytes, construct_block_cache, Block},

src/lib.rs

@@ -31,8 +31,8 @@ pub mod config;
 pub mod generator;
 pub mod inspector;
 pub mod observer;
-pub(crate) mod payload;
+pub mod payload;
 pub mod signals;
 pub mod target;
 pub mod target_metrics;
-pub(crate) mod throttle;
+pub mod throttle;

src/payload.rs

@@ -1,3 +1,10 @@
+//! Lading payloads
+//!
+//! The lading payload implementations are responsible for producing the data
+//! that is sent by [generators](crate::generator). Each payload implementation
+//! defines a particular type of message that can be sent by a generator.
+//!
+
 use std::{
     io::{self, Write},
     path::PathBuf,
@@ -20,20 +27,20 @@ pub(crate) use statik::Static;
 pub(crate) use syslog::Syslog5424;
 pub(crate) use trace_agent::TraceAgent;
 
-mod apache_common;
-mod ascii;
-mod common;
-mod datadog_logs;
-pub(crate) mod dogstatsd;
-mod fluent;
-mod json;
-mod opentelemetry_log;
-mod opentelemetry_metric;
-mod opentelemetry_trace;
-mod splunk_hec;
-mod statik;
-mod syslog;
-mod trace_agent;
+pub mod apache_common;
+pub mod ascii;
+pub(crate) mod common;
+pub mod datadog_logs;
+pub mod dogstatsd;
+pub mod fluent;
+pub mod json;
+pub mod opentelemetry_log;
+pub mod opentelemetry_metric;
+pub mod opentelemetry_trace;
+pub mod splunk_hec;
+pub mod statik;
+pub mod syslog;
+pub mod trace_agent;
 
 /// Errors related to serialization
 #[derive(thiserror::Error, Debug)]
@@ -82,7 +89,10 @@ pub enum Config {
     /// Generates syslog5424 messages
     Syslog5424,
     /// Generates Splunk HEC messages
-    SplunkHec { encoding: SplunkHecEncoding },
+    SplunkHec {
+        /// Defines the encoding to use for the Splunk HEC messages.
+        encoding: SplunkHecEncoding,
+    },
     /// Generates Datadog Logs JSON messages
     DatadogLog,
     /// Generates a static, user supplied data

src/payload/apache_common.rs

@@ -1,3 +1,5 @@
+//! Apache common payload.
+
 use crate::payload::{Error, Serialize};
 
 use core::fmt;

src/payload/ascii.rs

@@ -1,3 +1,5 @@
+//! ASCII payload.
+
 use std::io::Write;
 
 use rand::Rng;