From dd4c13bd69ca4b24d5a8f21024a466fbb35cdd14 Mon Sep 17 00:00:00 2001 From: Zhongyang Wu Date: Thu, 1 Feb 2024 21:33:30 -0800 Subject: [PATCH] fix(sdk): fix incorrect doc (#1499) Co-authored-by: Cijo Thomas --- .../src/metrics/meter_provider.rs | 5 +-- opentelemetry-sdk/src/propagation/baggage.rs | 42 ------------------ .../src/propagation/trace_context.rs | 43 +++++++++++-------- 3 files changed, 26 insertions(+), 64 deletions(-) diff --git a/opentelemetry-sdk/src/metrics/meter_provider.rs b/opentelemetry-sdk/src/metrics/meter_provider.rs index fd10b832ea..13a14c1739 100644 --- a/opentelemetry-sdk/src/metrics/meter_provider.rs +++ b/opentelemetry-sdk/src/metrics/meter_provider.rs @@ -38,10 +38,7 @@ impl Default for SdkMeterProvider { } impl SdkMeterProvider { - /// Flushes all pending telemetry. - /// - /// There is no guaranteed that all telemetry be flushed or all resources have - /// been released on error. + /// Return default [MeterProviderBuilder] pub fn builder() -> MeterProviderBuilder { MeterProviderBuilder::default() } diff --git a/opentelemetry-sdk/src/propagation/baggage.rs b/opentelemetry-sdk/src/propagation/baggage.rs index ee7cf285d6..4e42e722f6 100644 --- a/opentelemetry-sdk/src/propagation/baggage.rs +++ b/opentelemetry-sdk/src/propagation/baggage.rs @@ -1,45 +1,3 @@ -//! # OpenTelemetry Baggage API -//! -//! Baggage is used to annotate telemetry, adding context and -//! information to metrics, traces, and logs. It is an abstract data type -//! represented by a set of name-value pairs describing user-defined properties. -//! Each name in a [`Baggage`] is associated with exactly one value. -//! `Baggage`s are serialized according to the editor's draft of -//! the [W3C Baggage] specification. -//! -//! [`Baggage`]: opentelemetry::baggage::Baggage -//! [W3C Baggage]: https://w3c.github.io/baggage/ -//! -//! # Examples -//! -//! ``` -//! use opentelemetry::{baggage::BaggageExt, Key, propagation::TextMapPropagator}; -//! use opentelemetry_sdk::propagation::BaggagePropagator; -//! use std::collections::HashMap; -//! -//! // Example baggage value passed in externally via http headers -//! let mut headers = HashMap::new(); -//! headers.insert("baggage".to_string(), "user_id=1".to_string()); -//! -//! let propagator = BaggagePropagator::new(); -//! // can extract from any type that impls `Extractor`, usually an HTTP header map -//! let cx = propagator.extract(&headers); -//! -//! // Iterate over extracted name-value pairs -//! for (name, value) in cx.baggage() { -//! // ... -//! } -//! -//! // Add new baggage -//! let cx_with_additions = cx.with_baggage(vec![Key::new("server_id").i64(42)]); -//! -//! // Inject baggage into http request -//! propagator.inject_context(&cx_with_additions, &mut headers); -//! -//! let header_value = headers.get("baggage").expect("header is injected"); -//! assert!(header_value.contains("user_id=1"), "still contains previous name-value"); -//! assert!(header_value.contains("server_id=42"), "contains new name-value pair"); -//! ``` use once_cell::sync::Lazy; use opentelemetry::{ baggage::{BaggageExt, KeyValueMetadata}, diff --git a/opentelemetry-sdk/src/propagation/trace_context.rs b/opentelemetry-sdk/src/propagation/trace_context.rs index f7735614c7..b93f3926ff 100644 --- a/opentelemetry-sdk/src/propagation/trace_context.rs +++ b/opentelemetry-sdk/src/propagation/trace_context.rs @@ -1,22 +1,6 @@ //! # W3C Trace Context Propagator //! -//! The `traceparent` header represents the incoming request in a -//! tracing system in a common format, understood by all vendors. -//! Here’s an example of a `traceparent` header. -//! -//! `traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01` -//! -//! The `traceparent` HTTP header field identifies the incoming request in a -//! tracing system. It has four fields: -//! -//! - version -//! - trace-id -//! - parent-id -//! - trace-flags -//! -//! See the [w3c trace-context docs] for more details. -//! -//! [w3c trace-context docs]: https://w3c.github.io/trace-context/ + use once_cell::sync::Lazy; use opentelemetry::{ propagation::{text_map_propagator::FieldIter, Extractor, Injector, TextMapPropagator}, @@ -33,8 +17,31 @@ const TRACESTATE_HEADER: &str = "tracestate"; static TRACE_CONTEXT_HEADER_FIELDS: Lazy<[String; 2]> = Lazy::new(|| [TRACEPARENT_HEADER.to_owned(), TRACESTATE_HEADER.to_owned()]); -/// Propagates `SpanContext`s in [W3C TraceContext] format. +/// Propagates `SpanContext`s in [W3C TraceContext] format under `traceparent` and `tracestate` header. +/// +/// The `traceparent` header represents the incoming request in a +/// tracing system in a common format, understood by all vendors. +/// Here’s an example of a `traceparent` header. +/// +/// `traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01` +/// +/// The `traceparent` HTTP header field identifies the incoming request in a +/// tracing system. It has four fields: +/// +/// - version +/// - trace-id +/// - parent-id +/// - trace-flags +/// +/// The `tracestate` header provides additional vendor-specific trace +/// identification information across different distributed tracing systems. +/// Here's an example of a `tracestate` header +/// +/// `tracestate: vendorname1=opaqueValue1,vendorname2=opaqueValue2` +/// +/// See the [w3c trace-context docs] for more details. /// +/// [w3c trace-context docs]: https://w3c.github.io/trace-context/ /// [W3C TraceContext]: https://www.w3.org/TR/trace-context/ #[derive(Clone, Debug, Default)] pub struct TraceContextPropagator {