Debian Codegraph @

rust/hg-pyo3/src/pytracing.rs

raw
1 #[cfg(feature = "full-tracing")]
2 use full_tracing::setup_tracing_guard;
3 #[cfg(feature = "full-tracing")]
4 use full_tracing::PyTracing;
5 use pyo3::prelude::*;
6 #[cfg(not(feature = "full-tracing"))]
7 use tracing_subscriber::fmt::format::FmtSpan;
8 #[cfg(not(feature = "full-tracing"))]
9 use tracing_subscriber::prelude::*;
10 #[cfg(not(feature = "full-tracing"))]
11 use tracing_subscriber::EnvFilter;
12
13 use crate::utils::new_submodule;
14
15 #[cfg(not(feature = "full-tracing"))]
16 /// Enable an env-filtered logger to stderr
17 fn setup_tracing() {
18 let registry =
19 tracing_subscriber::registry().with(EnvFilter::from_default_env());
20 let fmt_layer = tracing_subscriber::fmt::layer()
21 .with_writer(std::io::stderr)
22 .with_span_events(FmtSpan::CLOSE);
23 registry.with(fmt_layer).init()
24 }
25
26 #[cfg(feature = "full-tracing")]
27 mod full_tracing {
28 use std::sync::Mutex;
29 use std::sync::OnceLock;
30
31 use dashmap::DashMap;
32 use pyo3::prelude::*;
33 use pyo3::types::PyTuple;
34 use tracing::field::Field;
35 use tracing::field::Visit;
36 use tracing::span::Attributes;
37 use tracing::span::Id;
38 use tracing::Subscriber;
39 use tracing_chrome::ChromeLayerBuilder;
40 use tracing_chrome::EventOrSpan;
41 use tracing_chrome::FlushGuard;
42 use tracing_subscriber::layer::Context;
43 use tracing_subscriber::layer::SubscriberExt as _;
44 use tracing_subscriber::registry::LookupSpan;
45 use tracing_subscriber::util::SubscriberInitExt as _;
46 use tracing_subscriber::EnvFilter;
47 use tracing_subscriber::Layer;
48
49 /// A span target name to mark those from Python
50 pub const PYTHON_TARGET_NAME: &str = "from_python";
51
52 /// A mapping of span ids to user-facing trace names.
53 /// See [`PyTracingLayer`] for more info.
54 static ID_TO_NAMES: OnceLock<DashMap<u64, String>> = OnceLock::new();
55
56 /// A Python front-end singleton to hook into the Rust tracing system,
57 /// so that all traces are collected in a single place.
58 #[pyclass]
59 pub struct PyTracing;
60
61 #[pymethods]
62 impl PyTracing {
63 /// Returns a context manager that will correspond to a span `name`
64 /// with level `debug`
65 pub fn span(&self, name: &str) -> PyTracingSpan {
66 let span = tracing::debug_span!(
67 target: PYTHON_TARGET_NAME,
68 "", // The name is useless in this context anyway
69 py_actual_name = name
70 );
71 PyTracingSpan::new(TracingSpanState::Created(span))
72 }
73 }
74
75 /// A simple context manager that corresponds to a tracing span created
76 /// from a Python context.
77 #[pyclass(unsendable)]
78 pub struct PyTracingSpan {
79 inner: Option<TracingSpanState>,
80 }
81
82 impl PyTracingSpan {
83 pub fn new(inner: TracingSpanState) -> Self {
84 Self { inner: Some(inner) }
85 }
86 }
87
88 #[pymethods]
89 impl PyTracingSpan {
90 fn __enter__(&mut self) -> PyResult<()> {
91 if let Some(TracingSpanState::Created(s)) =
92 std::mem::take(&mut self.inner)
93 {
94 let entered = TracingSpanState::Entered(s.entered());
95 self.inner = Some(entered);
96 }
97 Ok(())
98 }
99
100 #[pyo3(signature = (*_args))]
101 fn __exit__(&mut self, _args: &Bound<'_, PyTuple>) {
102 if let Some(TracingSpanState::Entered(s)) =
103 std::mem::take(&mut self.inner)
104 {
105 s.exit();
106 }
107 }
108 }
109
110 /// See [`ChromeTracingGuard`]
111 /// Enable an env-filtered chrome-trace logger to a file.
112 /// Defaults to writing to `./trace-{unix epoch in micros}.json`, but can
113 /// be overridden via the `HG_TRACE_PATH` environment variable.
114 pub fn setup_tracing_guard() -> ChromeTracingGuard {
115 // Expect that if any events are recorded, we probably are going to
116 // record a few. 16 is pretty arbitrary, but seems like a good
117 // balance between not re-sizing for most cases and not
118 // over-provisioning.
119 ID_TO_NAMES.get_or_init(|| DashMap::with_capacity(16));
120 let mut chrome_layer_builder =
121 ChromeLayerBuilder::new().name_fn(Box::new(|event_or_span| {
122 match event_or_span {
123 EventOrSpan::Event(ev) => ev.metadata().name().into(),
124 EventOrSpan::Span(span_ref) => {
125 if span_ref.metadata().target() != PYTHON_TARGET_NAME {
126 // Not a Python span, it has the correct name
127 span_ref.name().into()
128 } else {
129 let id = span_ref.id();
130 ID_TO_NAMES
131 .get()
132 .expect("ID_TO_NAMES should exist")
133 .get(&id.into_u64())
134 .map(|r| r.value().to_string())
135 .unwrap_or_else(|| String::from("unknown"))
136 }
137 }
138 }
139 }));
140
141 // /!\ Keep in sync with rhg
142 if let Ok(path) = std::env::var("HG_TRACE_PATH") {
143 chrome_layer_builder = chrome_layer_builder.file(path);
144 }
145 let (chrome_layer, chrome_layer_guard) = chrome_layer_builder.build();
146 let registry = tracing_subscriber::registry()
147 .with(PyTracingLayer)
148 .with(EnvFilter::from_default_env());
149 let registry = registry.with(chrome_layer);
150 registry.init();
151 // Send this event as soon as possible to get the reference of how much
152 // time has happened since we've started tracing until the first actual
153 // tracing point.
154 tracing::info!(name: "tracing setup", "pyo3 chrome tracing setup done");
155 ChromeTracingGuard::new(chrome_layer_guard)
156 }
157
158 /// A [`Layer`] implementation that intercepts each new [`Span`] and
159 /// remembers dynamic information for those created from Python.
160 ///
161 /// [`tracing`] events and span have a static name (and location, etc.)
162 /// which allows them to be very low overhead. We are however tracing from
163 /// Python, which (of course) has no way of statically communicating
164 /// its names when compiling the Rust code. Thus, we keep track of all
165 /// spans and their dynamic names to map each span id to its name upon
166 /// writing to the trace.
167 pub struct PyTracingLayer;
168
169 impl<S> Layer<S> for PyTracingLayer
170 where
171 S: Subscriber,
172 S: for<'lookup> LookupSpan<'lookup>,
173 {
174 fn on_new_span(
175 &self,
176 attrs: &Attributes<'_>,
177 id: &Id,
178 _ctx: Context<'_, S>,
179 ) {
180 let mut visitor = PyTracingVisitor::new(id.into_u64());
181 attrs.values().record(&mut visitor);
182 }
183 }
184
185 /// A simple [`Visit`] implementation that inserts only Python-created
186 /// events in [`ID_TO_NAMES`].
187 struct PyTracingVisitor {
188 id: u64,
189 }
190
191 impl PyTracingVisitor {
192 pub fn new(id: u64) -> Self {
193 Self { id }
194 }
195 }
196
197 impl Visit for PyTracingVisitor {
198 fn record_debug(
199 &mut self,
200 _field: &Field,
201 _value: &dyn std::fmt::Debug,
202 ) {
203 // Do nothing
204 }
205 fn record_str(&mut self, field: &Field, value: &str) {
206 if field.name() == "py_actual_name" {
207 // This will only be called from the main thread because we
208 // filter out non-Python events
209 ID_TO_NAMES
210 .get()
211 .expect("ID_TO_NAMES should exist")
212 .insert(self.id, value.to_string());
213 }
214 }
215 }
216
217 /// Keeps track of the current state of the span.
218 /// There is no state for "exited" because that simply means
219 /// it's been dropped.
220 pub enum TracingSpanState {
221 /// The span has only been create, but not yet entered
222 Created(tracing::Span),
223 /// The span has been entered
224 Entered(tracing::span::EnteredSpan),
225 }
226
227 /// A Python object whose entire purpose is to keep the [`FlushGuard`] for
228 /// tracing purposes, flushing to the trace file when dropped by
229 /// the Python process finishing.
230 #[pyclass]
231 pub struct ChromeTracingGuard {
232 guard: Mutex<FlushGuard>,
233 }
234
235 impl ChromeTracingGuard {
236 fn new(guard: FlushGuard) -> Self {
237 Self { guard: Mutex::new(guard) }
238 }
239 }
240
241 impl Drop for ChromeTracingGuard {
242 fn drop(&mut self) {
243 self.guard
244 .try_lock()
245 .map(|guard| {
246 guard.flush();
247 })
248 .ok();
249 }
250 }
251 }
252
253 pub fn init_module<'py>(
254 py: Python<'py>,
255 package: &str,
256 ) -> PyResult<Bound<'py, PyModule>> {
257 let m = new_submodule(py, package, "tracing")?;
258 #[cfg(feature = "full-tracing")]
259 m.add("tracer", PyTracing)?;
260 #[cfg(feature = "full-tracing")]
261 m.add("_chrome_tracing_guard", setup_tracing_guard())?;
262 #[cfg(not(feature = "full-tracing"))]
263 setup_tracing();
264 Ok(m)
265 }