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}