docs(bootstrap): telemetry docs

crates/bootstrap/telemetry/README.md

@@ -3,7 +3,7 @@
 > [!WARNING]  
 > This crate is under active development and may not be stable.
 
- [![crates.io](https://img.shields.io/crates/v/scuffle-bootstrap-telemetry.svg)](https://crates.io/crates/scuffle-bootstrap-telemetry) [![docs.rs](https://img.shields.io/docsrs/scuffle-bootstrap-telemetry)](https://docs.rs/scuffle-bootstrap-telemetry)
+[![crates.io](https://img.shields.io/crates/v/scuffle-bootstrap-telemetry.svg)](https://crates.io/crates/scuffle-bootstrap-telemetry) [![docs.rs](https://img.shields.io/docsrs/scuffle-bootstrap-telemetry)](https://docs.rs/scuffle-bootstrap-telemetry)
 
 ---
 

crates/bootstrap/telemetry/src/lib.rs

@@ -1,3 +1,32 @@
+//! # scuffle-bootstrap-telemetry
+//!
+//! A crate used to add telemetry to applications built with the scuffle-bootstrap.
+//!
+//! ## Feature Flags
+//!
+//! - `prometheus`: Enable Prometheus support.
+//! - `pprof`: Enable pprof support.
+//! - `opentelemetry-metrics`: Enable OpenTelemetry metrics support.
+//! - `opentelemetry-traces`: Enable OpenTelemetry traces support.
+//! - `opentelemetry-logs`: Enable OpenTelemetry logs support.
+//!
+//! All features are enabled by default.
+//!
+//! See [`TelemetrySvc`] for more details.
+//!
+//! ## Status
+//!
+//! This crate is currently under development and is not yet stable, unit tests are not yet fully implemented.
+//!
+//! Unit tests are not yet fully implemented. Use at your own risk.
+//!
+//! ## License
+//!
+//! This project is licensed under the [MIT](./LICENSE.MIT) or [Apache-2.0](./LICENSE.Apache-2.0) license.
+//! You can choose between one of them if you use this work.
+//!
+//! `SPDX-License-Identifier: MIT OR Apache-2.0`
+
 use anyhow::Context;
 use bytes::Bytes;
 use scuffle_bootstrap::global::Global;
@@ -15,15 +44,49 @@ pub use prometheus_client;
 #[cfg(feature = "opentelemetry-traces")]
 pub use tracing_opentelemetry;
 
+/// The telemetry service.
+///
+/// This is supposed to be used with the `scuffle-bootstrap` crate.
+///
+/// # HTTP Server
+///
+/// This service provides a http server which will bind to the address provided by the config. (See [`TelemetryConfig`])
+///
+/// ## Endpoints
+///
+/// The server provides the following endpoints:
+///
+/// ### `/health`
+///
+/// Health check endpoint.
+///
+/// ### `/metrics`
+///
+/// Prometheus metrics endpoint.
+///
+/// This endpoint is only enabled if the `prometheus` feature flag is enabled and a metrics registry is provided through the config.
+///
+/// ### `/pprof/cpu`
+///
+/// pprof cpu endpoint.
+///
+/// This endpoint is only enabled if the `pprof` feature flag is enabled.
+///
+/// ### `/opentelemetry/flush`
+///
+/// OpenTelemetry flush endpoint.
+///
+/// This endpoint is only enabled if the `opentelemetry` feature flag is enabled and an OpenTelemetry config is provided through the config.
 pub struct TelemetrySvc;
 
+/// Implement this trait to configure the telemetry service.
 pub trait TelemetryConfig: Global {
     /// Return true if the service is enabled.
     fn enabled(&self) -> bool {
         true
     }
 
-    /// Return the bind address to listen on.
+    /// Return the bind address for the http server.
     fn bind_address(&self) -> Option<std::net::SocketAddr> {
         None
     }
@@ -34,19 +97,27 @@ pub trait TelemetryConfig: Global {
     }
 
     /// Return a health check to determine if the service is healthy.
+    ///
+    /// Always healthy by default.
     fn health_check(&self) -> impl std::future::Future<Output = Result<(), anyhow::Error>> + Send {
         std::future::ready(Ok(()))
     }
 
     /// Return a Prometheus metrics registry to scrape metrics from.
+    ///
+    /// Returning `Some` will enable the `/metrics` http endpoint which is used by Prometheus to scrape metrics.
+    ///
+    /// Disabled (`None`) by default.
     #[cfg(feature = "prometheus")]
     fn prometheus_metrics_registry(&self) -> Option<&prometheus_client::registry::Registry> {
         None
     }
 
     /// Pass an OpenTelemetry instance to the service.
+    ///
     /// If provided the service will flush and shutdown the OpenTelemetry
-    /// instance when the service shuts down.
+    /// instance when it shuts down.
+    /// Additionally, the service provides the `/opentelemetry/flush` http endpoint to manually flush the data.
     #[cfg(feature = "opentelemetry")]
     fn opentelemetry(&self) -> Option<&opentelemetry::OpenTelemetry> {
         None