Add basic documentation

Author: davidsteiner

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ddtrace"
-version = "0.0.1"
+version = "0.0.2"
 authors = ["David Steiner <david_j_steiner@yahoo.co.nz", "Fergus Strangways-Dixon <fergusdixon101@gmail.com>"]
 edition = "2021"
 license = "MIT"
@@ -9,6 +9,7 @@ readme = "README.md"
 
 [features]
 axum = ["dep:axum", "dep:axum-tracing-opentelemetry"]
+reqwest = ["dep:reqwest"]
 
 [dependencies]
 axum = { version = "^0.6.10", optional = true }
@@ -17,6 +18,7 @@ chrono = "^0.4.24"
 opentelemetry = { version = "^0.18.0", features = ["rt-tokio"] }
 opentelemetry-datadog = "^0.6.0"
 opentelemetry-otlp = { version = "^0.11.0" }
+reqwest = { version = "^0.11.16", optional = true }
 serde = { version = "^1.0.156", features = ["derive"] }
 serde_json = "^1.0.95"
 tracing = "^0.1.37"

src/axum.rs

@@ -0,0 +1,9 @@
+//! Axum utilities.
+//!
+//! This module re-exposes the middleware layers provided by the
+//! [`axum-tracing-opentelemetry`] project.
+//!
+//! [`axum-tracing-opentelemetry`]: https://github.com/davidB/axum-tracing-opentelemetry
+
+pub use axum_tracing_opentelemetry::opentelemetry_tracing_layer;
+pub use axum_tracing_opentelemetry::opentelemetry_tracing_layer_grpc;

src/formatter.rs

@@ -1,3 +1,10 @@
+//! An event formatter to emit events in a way that Datadog can correlate them with traces.
+//!
+//! Datadog's trace ID and span ID format is different from the OpenTelemetry standard.
+//! Using this formatter, the trace ID is converted to the correct format.
+//! It also adds the trace ID to the `dd.trace_id` field and the span ID to the
+//! `dd.span_id` field, which is where Datadog looks for these by default
+//! (although the path to the trace ID can be overridden in Datadog).
 use std::io;
 
 use chrono::Utc;
@@ -11,9 +18,9 @@ use tracing_subscriber::fmt::format::Writer;
 use tracing_subscriber::fmt::{FmtContext, FormatEvent, FormatFields};
 use tracing_subscriber::registry::{LookupSpan, SpanRef};
 
-pub struct TraceInfo {
-    pub trace_id: String,
-    pub span_id: String,
+struct TraceInfo {
+    trace_id: String,
+    span_id: String,
 }
 
 fn convert_trace_id(id: TraceId) -> String {
@@ -24,14 +31,14 @@ fn convert_trace_id(id: TraceId) -> String {
 }
 
 fn convert_span_id(id: SpanId) -> String {
-    let dd_id = u64::from_be_bytes(id.to_bytes().try_into().unwrap());
+    let dd_id = u64::from_be_bytes(id.to_bytes());
 
     dd_id.to_string()
 }
 
 fn lookup_trace_info<S>(span_ref: &SpanRef<S>) -> Option<TraceInfo>
-    where
-        S: Subscriber + for<'a> LookupSpan<'a>,
+where
+    S: Subscriber + for<'a> LookupSpan<'a>,
 {
     span_ref.extensions().get::<OtelData>().map(|o| TraceInfo {
         trace_id: convert_trace_id(o.parent_cx.span().span_context().trace_id()),
@@ -40,21 +47,21 @@ fn lookup_trace_info<S>(span_ref: &SpanRef<S>) -> Option<TraceInfo>
 }
 
 // mostly stolen from here: https://github.com/tokio-rs/tracing/issues/1531
-pub struct TraceIdFormat;
+pub struct DatadogFormatter;
 
-impl<S, N> FormatEvent<S, N> for TraceIdFormat
-    where
-        S: Subscriber + for<'lookup> LookupSpan<'lookup>,
-        N: for<'writer> FormatFields<'writer> + 'static,
+impl<S, N> FormatEvent<S, N> for DatadogFormatter
+where
+    S: Subscriber + for<'lookup> LookupSpan<'lookup>,
+    N: for<'writer> FormatFields<'writer> + 'static,
 {
     fn format_event(
         &self,
         ctx: &FmtContext<'_, S, N>,
         mut writer: Writer<'_>,
         event: &Event<'_>,
     ) -> std::fmt::Result
-        where
-            S: Subscriber + for<'a> LookupSpan<'a>,
+    where
+        S: Subscriber + for<'a> LookupSpan<'a>,
     {
         let meta = event.metadata();
 
@@ -81,12 +88,12 @@ impl<S, N> FormatEvent<S, N> for TraceIdFormat
     }
 }
 
-pub struct WriteAdaptor<'a> {
+struct WriteAdaptor<'a> {
     fmt_write: &'a mut dyn std::fmt::Write,
 }
 
 impl<'a> WriteAdaptor<'a> {
-    pub fn new(fmt_write: &'a mut dyn std::fmt::Write) -> Self {
+    fn new(fmt_write: &'a mut dyn std::fmt::Write) -> Self {
         Self { fmt_write }
     }
 }

src/lib.rs

@@ -1,11 +1,15 @@
-mod formatter;
+//! Utilities to integrate Rust services with Datadog using [`opentelemetry`],
+//! [`tracing`], and other open source libraries.
+//!
+//! This is an opinionated crate providing the building blocks for a setup that
+//! works with Datadog. It has been tested with services using [`axum`] hosted
+//! on AWS ECS, with propagation working when requests are made to other services
+//! using [`reqwest`].
+
+#[cfg(feature = "axum")]
+pub mod axum;
+pub mod formatter;
 mod propagator;
-mod tracer;
+pub mod tracer;
 
-pub use formatter::TraceIdFormat;
 pub use propagator::set_global_propagator;
-pub use tracer::{build_tracer, build_layer};
-pub use opentelemetry::trace::{TraceError, TraceResult};
-
-#[cfg(feature = "axum")]
-pub use axum_tracing_opentelemetry::opentelemetry_tracing_layer;

src/propagator.rs

@@ -1,3 +1,4 @@
+/// Sets the Datadog propagator as the global propagator.
 pub fn set_global_propagator() {
     let propagator = opentelemetry_datadog::DatadogPropagator::new();
     opentelemetry::global::set_text_map_propagator(propagator);

src/tracer.rs

@@ -1,9 +1,15 @@
-use std::time::Duration;
-use opentelemetry::KeyValue;
-use opentelemetry::trace::{TraceResult};
-use opentelemetry::sdk::{Resource, trace};
+//! Trace and layer builders to export traces to the Datadog agent.
+//!
+//! This module contains a function that builds a tracer with an exporter
+//! to send traces to the Datadog agent in batches over gRPC.
+//!
+//! It also contains a convenience function to build a layer with the tracer.
 use opentelemetry::sdk::trace::{RandomIdGenerator, Sampler, Tracer};
+use opentelemetry::sdk::{trace, Resource};
+pub use opentelemetry::trace::{TraceError, TraceResult};
+use opentelemetry::KeyValue;
 use opentelemetry_otlp::WithExportConfig;
+use std::time::Duration;
 use tracing::Subscriber;
 use tracing_opentelemetry::{OpenTelemetryLayer, PreSampledTracer};
 use tracing_subscriber::registry::LookupSpan;