Skip to main content

risingwave_common/util/
tracing.rs

1// Copyright 2023 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15pub mod layer;
16pub mod log_filter;
17
18use std::collections::HashMap;
19use std::pin::Pin;
20use std::task::{Context, Poll};
21
22use opentelemetry::propagation::TextMapPropagator;
23use opentelemetry_sdk::propagation::TraceContextPropagator;
24use tracing_opentelemetry::OpenTelemetrySpanExt;
25
26/// Context for tracing used for propagating tracing information in a distributed system.
27///
28/// Generally, the caller of a service should create a tracing context from the current tracing span
29/// and pass it to the callee through the network. The callee will then attach its local tracing
30/// span as a child of the tracing context, so that the external tracing service can associate them
31/// in a single trace.
32///
33/// The tracing context must be serialized and deserialized when passing through the network.
34/// There're two ways to do this:
35///
36/// - For RPC calls with clear caller/callee relationship, the tracing context can be serialized
37///   into the W3C trace context format and passed in HTTP headers seamlessly with a service
38///   middleware. For example, the DDL requests from the frontend to the meta service.
39/// - For RPC calls with no clear caller/callee relationship or with asynchronous semantics, the
40///   tracing context should be passed manually as a protobuf field in the request and response for
41///   better lifetime management. For example, the exchange services between streaming actors or
42///   batch stages, and the `create_task` requests from the frontend to the batch service.
43///
44/// See [Trace Context](https://www.w3.org/TR/trace-context/) for more information.
45#[derive(Debug, Clone)]
46pub struct TracingContext(opentelemetry::Context);
47
48type Propagator = TraceContextPropagator;
49
50impl TracingContext {
51    /// Create a new tracing context from a tracing span.
52    pub fn from_span(span: &tracing::Span) -> Self {
53        Self(span.context())
54    }
55
56    /// Create a new tracing context from the current tracing span considered by the subscriber.
57    pub fn from_current_span() -> Self {
58        Self::from_span(&tracing::Span::current())
59    }
60
61    /// Create a no-op tracing context.
62    pub fn none() -> Self {
63        Self(opentelemetry::Context::new())
64    }
65
66    /// Attach the given span as a child of the context. Returns the attached span.
67    pub fn attach(&self, span: tracing::Span) -> tracing::Span {
68        // `set_parent` may fail if the subscriber doesn't support OpenTelemetry.
69        let _ = span.set_parent(self.0.clone());
70        span
71    }
72
73    /// Convert the tracing context to the W3C trace context format.
74    fn to_w3c(&self) -> HashMap<String, String> {
75        let mut fields = HashMap::new();
76        Propagator::new().inject_context(&self.0, &mut fields);
77        fields
78    }
79
80    /// Create a new tracing context from the W3C trace context format.
81    fn from_w3c(fields: &HashMap<String, String>) -> Self {
82        let context = Propagator::new().extract(fields);
83        Self(context)
84    }
85
86    /// Convert the tracing context to the protobuf format.
87    pub fn to_protobuf(&self) -> HashMap<String, String> {
88        self.to_w3c()
89    }
90
91    /// Create a new tracing context from the protobuf format.
92    pub fn from_protobuf(fields: &HashMap<String, String>) -> Self {
93        Self::from_w3c(fields)
94    }
95
96    /// Convert the tracing context to the W3C trace context format in HTTP headers.
97    pub fn to_http_headers(&self) -> http::HeaderMap {
98        let map = self.to_w3c();
99        http::HeaderMap::try_from(&map).unwrap_or_default()
100    }
101
102    /// Create a new tracing context from the W3C trace context format in HTTP headers.
103    ///
104    /// Returns `None` if the headers are invalid.
105    pub fn from_http_headers(headers: &http::HeaderMap) -> Option<Self> {
106        let mut map = HashMap::new();
107
108        // See [Trace Context](https://www.w3.org/TR/trace-context/) for these header names.
109        for key in ["traceparent", "tracestate"] {
110            let value = headers.get(key)?.to_str().ok()?;
111            map.insert(key.to_owned(), value.to_owned());
112        }
113
114        Some(Self::from_w3c(&map))
115    }
116}
117
118/// Extension trait allowing [`futures::Stream`]s to be instrumented with a [`tracing::Span`].
119#[easy_ext::ext(InstrumentStream)]
120impl<T> T
121where
122    T: futures::Stream + Sized,
123{
124    /// Instruments the stream with the given span. Alias for
125    /// [`tracing_futures::Instrument::instrument`].
126    ///
127    /// The span will be entered and exited every time the stream is polled. The span will be
128    /// closed only when the stream is dropped.
129    ///
130    /// If the stream is long-lived, consider [`InstrumentStream::instrument_with`] instead to
131    /// avoid accumulating too many events in the span.
132    pub fn instrument(self, span: tracing::Span) -> tracing_futures::Instrumented<Self> {
133        tracing_futures::Instrument::instrument(self, span)
134    }
135
136    /// Instruments the stream with spans created by the given closure **every time an item is
137    /// yielded**.
138    pub fn instrument_with<S>(self, make_span: S) -> WithInstrumented<Self, S>
139    where
140        S: FnMut() -> tracing::Span,
141    {
142        WithInstrumented::new(self, make_span)
143    }
144}
145
146pin_project_lite::pin_project! {
147    /// A [`futures::Stream`] that has been instrumented with
148    /// [`InstrumentStream::instrument_with`].
149    #[derive(Debug, Clone)]
150    pub struct WithInstrumented<T, S> {
151        #[pin]
152        inner: T,
153        make_span: S,
154        current_span: Option<tracing::Span>,
155    }
156}
157
158impl<T, S> WithInstrumented<T, S> {
159    /// Creates a new [`WithInstrumented`] stream.
160    fn new(inner: T, make_span: S) -> Self {
161        Self {
162            inner,
163            make_span,
164            current_span: None,
165        }
166    }
167
168    /// Returns the inner stream.
169    pub fn into_inner(self) -> T {
170        self.inner
171    }
172}
173
174impl<T, S> futures::Stream for WithInstrumented<T, S>
175where
176    T: futures::Stream + Sized,
177    S: FnMut() -> tracing::Span,
178{
179    type Item = T::Item;
180
181    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
182        let this = self.project();
183
184        let poll = {
185            let _entered = this.current_span.get_or_insert_with(this.make_span).enter();
186            this.inner.poll_next(cx)
187        };
188
189        if poll.is_ready() {
190            // Drop the span when a new item is yielded.
191            *this.current_span = None;
192        }
193
194        poll
195    }
196}