From 7679b7991b99182ba6a747a910bc5b0ca767ae53 Mon Sep 17 00:00:00 2001 From: Andrew Glaude Date: Mon, 9 Sep 2024 13:52:42 -0400 Subject: [PATCH 1/3] Require docs on all public things in data-pipeline --- data-pipeline/src/lib.rs | 7 +++++++ data-pipeline/src/trace_exporter.rs | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/data-pipeline/src/lib.rs b/data-pipeline/src/lib.rs index 50daf7f418..b8858f63e4 100644 --- a/data-pipeline/src/lib.rs +++ b/data-pipeline/src/lib.rs @@ -1,5 +1,12 @@ // Copyright 2024-Present Datadog, Inc. https://www.datadoghq.com/ // SPDX-License-Identifier: Apache-2.0 +#![deny(missing_docs)] +//! TraceExporter provides a minimum viable product (MVP) to send traces to agents. The aim of the project at this +//! state is to provide a basic API in order to test its viability and integration in different languages. + +/// Span Concentrator provides a method to "concentrate" span stats together. pub mod span_concentrator; +/// Trace Exporter allows accepts trace payloads and exports them to the datadog agent. pub mod trace_exporter; + diff --git a/data-pipeline/src/trace_exporter.rs b/data-pipeline/src/trace_exporter.rs index 7aa25cd9c8..c0a00db8d5 100644 --- a/data-pipeline/src/trace_exporter.rs +++ b/data-pipeline/src/trace_exporter.rs @@ -21,6 +21,7 @@ pub enum TraceExporterInputFormat { /// Proxy format is used when the traces are to be sent to the agent without processing them. /// The whole payload is sent as is to the agent. Proxy, + /// V04 is the v0.4 payload format defined in the datadog agent, this format is just a list of spans. #[default] V04, } @@ -30,8 +31,10 @@ pub enum TraceExporterInputFormat { #[derive(Copy, Clone, Debug, Default, PartialEq)] #[repr(C)] pub enum TraceExporterOutputFormat { + /// V04 is the v0.4 payload format defined in the datadog agent, this format is just a list of spans. #[default] V04, + /// V07 is the v0.7 payload format defined in the datadog agent. See (trace-protobuf/src/pb/tracer_payload.proto). V07, } @@ -105,6 +108,7 @@ impl<'a> From<&'a TracerTags> for HashMap<&'static str, String> { } } +/// TraceExporter accepts traces as input and outputs them to a configured endpoint. pub struct TraceExporter { endpoint: Endpoint, tags: TracerTags, @@ -116,10 +120,13 @@ pub struct TraceExporter { } impl TraceExporter { + /// Get a TraceExporterBuilder to configure a TraceExporter using a builder pattern pub fn builder() -> TraceExporterBuilder { TraceExporterBuilder::default() } + /// Send the data to a configured endpoint, trace_count is the number of traces within data. + /// Returns the resulting body or an error. pub fn send(&self, data: &[u8], trace_count: usize) -> Result { match self.input_format { TraceExporterInputFormat::Proxy => self.send_proxy(data, trace_count), @@ -257,6 +264,7 @@ impl TraceExporter { } } +/// TraceExporterBuilder allows configuring a TraceExporter with the Builder pattern. #[derive(Default)] pub struct TraceExporterBuilder { url: Option, @@ -270,46 +278,55 @@ pub struct TraceExporterBuilder { } impl TraceExporterBuilder { + /// Sets the url to export traces to. pub fn set_url(mut self, url: &str) -> Self { self.url = Some(url.to_owned()); self } + /// Set the tracer version receiving traces from. pub fn set_tracer_version(mut self, tracer_version: &str) -> Self { tracer_version.clone_into(&mut self.tracer_version); self } + /// Set the language of incoming traces. pub fn set_language(mut self, lang: &str) -> Self { lang.clone_into(&mut self.language); self } + /// Set the language version of incoming traces. pub fn set_language_version(mut self, lang_version: &str) -> Self { lang_version.clone_into(&mut self.language_version); self } + /// Set the language interprester of incoming traces. pub fn set_language_interpreter(mut self, lang_interpreter: &str) -> Self { lang_interpreter.clone_into(&mut self.language_interpreter); self } + /// Set the input format for incoming traces. pub fn set_input_format(mut self, input_format: TraceExporterInputFormat) -> Self { self.input_format = input_format; self } + /// Set the output format for outgoing traces. pub fn set_output_format(mut self, output_format: TraceExporterOutputFormat) -> Self { self.output_format = output_format; self } + /// Set a response callback to process responses from sending traces. pub fn set_response_callback(mut self, response_callback: Box) -> Self { self.response_callback = Some(response_callback); self } + /// Build a TraceExporter instance using the built configuration options. pub fn build(mut self) -> anyhow::Result { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() @@ -331,7 +348,9 @@ impl TraceExporterBuilder { } } +/// A callback to process some response body. pub trait ResponseCallback { + /// A callback handling a response body fn call(&self, response: &str); } From 31fc739df4488ba90048152e8f8806a275ebc15c Mon Sep 17 00:00:00 2001 From: Andrew Glaude Date: Mon, 9 Sep 2024 14:51:23 -0400 Subject: [PATCH 2/3] just use allow missing_docs until we have a template for our docs here --- data-pipeline/src/lib.rs | 5 ++-- data-pipeline/src/trace_exporter.rs | 37 ++++++++++++++--------------- 2 files changed, 20 insertions(+), 22 deletions(-) diff --git a/data-pipeline/src/lib.rs b/data-pipeline/src/lib.rs index b8858f63e4..387445a05f 100644 --- a/data-pipeline/src/lib.rs +++ b/data-pipeline/src/lib.rs @@ -5,8 +5,7 @@ //! TraceExporter provides a minimum viable product (MVP) to send traces to agents. The aim of the project at this //! state is to provide a basic API in order to test its viability and integration in different languages. -/// Span Concentrator provides a method to "concentrate" span stats together. +#[allow(missing_docs)] pub mod span_concentrator; -/// Trace Exporter allows accepts trace payloads and exports them to the datadog agent. +#[allow(missing_docs)] pub mod trace_exporter; - diff --git a/data-pipeline/src/trace_exporter.rs b/data-pipeline/src/trace_exporter.rs index c0a00db8d5..baf38b8df2 100644 --- a/data-pipeline/src/trace_exporter.rs +++ b/data-pipeline/src/trace_exporter.rs @@ -21,7 +21,7 @@ pub enum TraceExporterInputFormat { /// Proxy format is used when the traces are to be sent to the agent without processing them. /// The whole payload is sent as is to the agent. Proxy, - /// V04 is the v0.4 payload format defined in the datadog agent, this format is just a list of spans. + #[allow(missing_docs)] #[default] V04, } @@ -31,10 +31,10 @@ pub enum TraceExporterInputFormat { #[derive(Copy, Clone, Debug, Default, PartialEq)] #[repr(C)] pub enum TraceExporterOutputFormat { - /// V04 is the v0.4 payload format defined in the datadog agent, this format is just a list of spans. + #[allow(missing_docs)] #[default] V04, - /// V07 is the v0.7 payload format defined in the datadog agent. See (trace-protobuf/src/pb/tracer_payload.proto). + #[allow(missing_docs)] V07, } @@ -108,7 +108,7 @@ impl<'a> From<&'a TracerTags> for HashMap<&'static str, String> { } } -/// TraceExporter accepts traces as input and outputs them to a configured endpoint. +#[allow(missing_docs)] pub struct TraceExporter { endpoint: Endpoint, tags: TracerTags, @@ -120,13 +120,12 @@ pub struct TraceExporter { } impl TraceExporter { - /// Get a TraceExporterBuilder to configure a TraceExporter using a builder pattern + #[allow(missing_docs)] pub fn builder() -> TraceExporterBuilder { TraceExporterBuilder::default() } - /// Send the data to a configured endpoint, trace_count is the number of traces within data. - /// Returns the resulting body or an error. + #[allow(missing_docs)] pub fn send(&self, data: &[u8], trace_count: usize) -> Result { match self.input_format { TraceExporterInputFormat::Proxy => self.send_proxy(data, trace_count), @@ -264,7 +263,7 @@ impl TraceExporter { } } -/// TraceExporterBuilder allows configuring a TraceExporter with the Builder pattern. +#[allow(missing_docs)] #[derive(Default)] pub struct TraceExporterBuilder { url: Option, @@ -278,55 +277,55 @@ pub struct TraceExporterBuilder { } impl TraceExporterBuilder { - /// Sets the url to export traces to. + #[allow(missing_docs)] pub fn set_url(mut self, url: &str) -> Self { self.url = Some(url.to_owned()); self } - /// Set the tracer version receiving traces from. + #[allow(missing_docs)] pub fn set_tracer_version(mut self, tracer_version: &str) -> Self { tracer_version.clone_into(&mut self.tracer_version); self } - /// Set the language of incoming traces. + #[allow(missing_docs)] pub fn set_language(mut self, lang: &str) -> Self { lang.clone_into(&mut self.language); self } - /// Set the language version of incoming traces. + #[allow(missing_docs)] pub fn set_language_version(mut self, lang_version: &str) -> Self { lang_version.clone_into(&mut self.language_version); self } - /// Set the language interprester of incoming traces. + #[allow(missing_docs)] pub fn set_language_interpreter(mut self, lang_interpreter: &str) -> Self { lang_interpreter.clone_into(&mut self.language_interpreter); self } - /// Set the input format for incoming traces. + #[allow(missing_docs)] pub fn set_input_format(mut self, input_format: TraceExporterInputFormat) -> Self { self.input_format = input_format; self } - /// Set the output format for outgoing traces. + #[allow(missing_docs)] pub fn set_output_format(mut self, output_format: TraceExporterOutputFormat) -> Self { self.output_format = output_format; self } - /// Set a response callback to process responses from sending traces. + #[allow(missing_docs)] pub fn set_response_callback(mut self, response_callback: Box) -> Self { self.response_callback = Some(response_callback); self } - /// Build a TraceExporter instance using the built configuration options. + #[allow(missing_docs)] pub fn build(mut self) -> anyhow::Result { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() @@ -348,9 +347,9 @@ impl TraceExporterBuilder { } } -/// A callback to process some response body. +#[allow(missing_docs)] pub trait ResponseCallback { - /// A callback handling a response body + #[allow(missing_docs)] fn call(&self, response: &str); } From 66975a4e480d08e93a6d06e955054d1b33d8dc4a Mon Sep 17 00:00:00 2001 From: Andrew Glaude Date: Mon, 9 Sep 2024 14:54:28 -0400 Subject: [PATCH 3/3] rust fmt --- data-pipeline/src/lib.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/data-pipeline/src/lib.rs b/data-pipeline/src/lib.rs index 387445a05f..f0a1fcb611 100644 --- a/data-pipeline/src/lib.rs +++ b/data-pipeline/src/lib.rs @@ -2,8 +2,9 @@ // SPDX-License-Identifier: Apache-2.0 #![deny(missing_docs)] -//! TraceExporter provides a minimum viable product (MVP) to send traces to agents. The aim of the project at this -//! state is to provide a basic API in order to test its viability and integration in different languages. +//! TraceExporter provides a minimum viable product (MVP) to send traces to agents. The aim of the +//! project at this state is to provide a basic API in order to test its viability and integration +//! in different languages. #[allow(missing_docs)] pub mod span_concentrator;