guinea_trace/point.rs
1use std::fmt;
2
3/// Which bus carried a publication.
4#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
5pub enum Bus {
6 /// Every window hears it.
7 Global,
8 /// One window's own.
9 Window,
10}
11
12/// How a stored value changed.
13#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
14pub enum StoreOp {
15 Set,
16 Delete,
17 /// Everything under the path went at once.
18 DeletePrefix,
19}
20
21/// An observable point, with what identifies it.
22///
23/// Names are short type names: `processes::Kill`, not a crate path.
24///
25/// New kinds of point come in patch releases, so a match on it outside this
26/// crate needs an arm for the ones it doesn't know yet:
27///
28/// ```compile_fail
29/// use guinea_trace::Point;
30///
31/// fn known(point: &Point) -> bool {
32/// match point {
33/// Point::Action { .. }
34/// | Point::Send { .. }
35/// | Point::Handle { .. }
36/// | Point::Spawn { .. }
37/// | Point::Settled { .. }
38/// | Point::Cancelled { .. }
39/// | Point::Source { .. }
40/// | Point::Arrived { .. }
41/// | Point::Pull { .. }
42/// | Point::Closed { .. }
43/// | Point::Publish { .. }
44/// | Point::Deliver { .. }
45/// | Point::Push { .. }
46/// | Point::Navigate { .. }
47/// | Point::Tick { .. }
48/// | Point::Store { .. }
49/// | Point::Render { .. }
50/// | Point::Log { .. }
51/// | Point::Span { .. }
52/// | Point::Note(_) => true,
53/// }
54/// }
55/// ```
56#[derive(Clone, Debug, PartialEq)]
57#[non_exhaustive]
58pub enum Point {
59 /// The UI asked a feature for something.
60 Action { message: &'static str },
61 /// A message was queued for an actor.
62 Send {
63 actor: &'static str,
64 message: &'static str,
65 },
66 /// An actor handled a message.
67 Handle {
68 actor: &'static str,
69 message: &'static str,
70 },
71 /// An actor started background work whose result will come back as
72 /// `output`. `actor` is the address it will come back to, by the id the
73 /// snapshot lists it under: what a task belongs to is what that actor
74 /// belongs to.
75 Spawn {
76 actor: &'static str,
77 actor_id: u64,
78 output: &'static str,
79 },
80 /// Background work finished, and its result is on its way to the actor.
81 Settled {
82 actor: &'static str,
83 actor_id: u64,
84 output: &'static str,
85 took_us: u64,
86 },
87 /// Background work was dropped where it last awaited, because the actor
88 /// that started it is gone. Nothing comes back.
89 Cancelled {
90 actor: &'static str,
91 actor_id: u64,
92 output: &'static str,
93 took_us: u64,
94 },
95 /// An actor opened a source whose items will come to it as `output`.
96 /// Recorded under what opened it, which is done with it once it is open:
97 /// the items are not its work.
98 Source {
99 actor: &'static str,
100 actor_id: u64,
101 output: &'static str,
102 },
103 /// An item came from a source, as `output`. A root, as a timer's tick
104 /// is; `source` is the id of the [`Point::Source`] it came from.
105 Arrived {
106 actor: &'static str,
107 actor_id: u64,
108 output: &'static str,
109 source: u64,
110 },
111 /// A source is making its next item, which will come as `output`: what
112 /// its stream does meanwhile is recorded under this. A root, as
113 /// [`Point::Arrived`] is; `source` is the id of the [`Point::Source`].
114 /// Open from when the source is asked for the item until it has it, runs
115 /// dry or is dropped.
116 Pull {
117 actor: &'static str,
118 actor_id: u64,
119 output: &'static str,
120 source: u64,
121 },
122 /// A source ended: it ran dry, or `gone` - the actor that opened it is
123 /// gone and the source was dropped where it last awaited.
124 Closed {
125 actor: &'static str,
126 actor_id: u64,
127 output: &'static str,
128 took_us: u64,
129 gone: bool,
130 },
131 /// An event went out.
132 Publish {
133 event: &'static str,
134 bus: Bus,
135 subscribers: usize,
136 },
137 /// An event reached a subscriber that is not an actor.
138 Deliver { event: &'static str, bus: Bus },
139 /// A reducer was changed.
140 Push { reducer: &'static str },
141 /// A router moved.
142 Navigate { root: String, to: String },
143 /// A timer fired; `timer` is its id, as the application's timers list
144 /// it.
145 Tick { timer: u64 },
146 /// A persisted value changed.
147 Store {
148 op: StoreOp,
149 path: String,
150 /// The declared field the path belongs to, `Settings.theme`, when
151 /// the store knows it.
152 field: Option<String>,
153 /// Whether the change came from outside the process, an edited file.
154 outside: bool,
155 },
156 /// A page or layout drew itself, and how long that took. Recorded only
157 /// for the frames worth looking at - see `observability::Rendering`.
158 Render {
159 segment: &'static str,
160 took_us: u64,
161 },
162 /// An ordinary `tracing` event the application wrote.
163 Log {
164 level: tracing::Level,
165 target: &'static str,
166 /// Where it was written, as the compiler named the file: relative to
167 /// the workspace root for the application's own crates.
168 file: Option<&'static str>,
169 line: Option<u32>,
170 module: Option<&'static str>,
171 /// The message, then the other fields as `name=value`.
172 text: String,
173 },
174 /// A `tracing` span the application opened - an `#[instrument]`ed
175 /// function, say. Open until the span closes, and current while it is
176 /// entered; what it took is the time it was entered, not the time it
177 /// waited in between.
178 Span {
179 name: &'static str,
180 /// The level it was opened at, as [`Point::Log`]'s.
181 level: tracing::Level,
182 target: &'static str,
183 /// Where it was written; see [`Point::Log`].
184 file: Option<&'static str>,
185 line: Option<u32>,
186 module: Option<&'static str>,
187 /// Its fields as `name=value`, as they were when it opened.
188 fields: String,
189 },
190 /// Anything else worth a line.
191 Note(String),
192}
193
194impl Point {
195 /// A short name for the kind of point, for filtering.
196 pub fn kind(&self) -> &'static str {
197 match self {
198 Point::Action { .. } => "action",
199 Point::Send { .. } => "send",
200 Point::Handle { .. } => "handle",
201 Point::Spawn { .. } => "spawn",
202 Point::Settled { .. } => "settled",
203 Point::Cancelled { .. } => "cancelled",
204 Point::Source { .. } => "source",
205 Point::Arrived { .. } => "arrived",
206 Point::Pull { .. } => "pull",
207 Point::Closed { .. } => "closed",
208 Point::Publish { .. } => "publish",
209 Point::Deliver { .. } => "deliver",
210 Point::Push { .. } => "push",
211 Point::Navigate { .. } => "navigate",
212 Point::Tick { .. } => "tick",
213 Point::Store { .. } => "store",
214 Point::Render { .. } => "render",
215 Point::Log { .. } => "log",
216 Point::Span { .. } => "span",
217 Point::Note(_) => "note",
218 }
219 }
220}
221
222impl fmt::Display for Bus {
223 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
224 f.write_str(match self {
225 Bus::Global => "global",
226 Bus::Window => "window",
227 })
228 }
229}
230
231impl fmt::Display for StoreOp {
232 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
233 f.write_str(match self {
234 StoreOp::Set => "set",
235 StoreOp::Delete => "delete",
236 StoreOp::DeletePrefix => "delete_prefix",
237 })
238 }
239}
240
241impl fmt::Display for Point {
242 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
243 match self {
244 Point::Action { message } => write!(f, "action {message}"),
245 Point::Send { actor, message } => write!(f, "send {message} → {actor}"),
246 Point::Handle { actor, message, .. } => write!(f, "{actor} handles {message}"),
247 Point::Spawn { actor, output, .. } => write!(f, "{actor} starts work for {output}"),
248 Point::Settled {
249 actor,
250 output,
251 took_us,
252 ..
253 } => write!(
254 f,
255 "{actor} has its {output} after {:.1} ms",
256 *took_us as f64 / 1000.0
257 ),
258 Point::Cancelled {
259 actor,
260 output,
261 took_us,
262 ..
263 } => write!(
264 f,
265 "{actor} is gone: {output} cancelled after {:.1} ms",
266 *took_us as f64 / 1000.0
267 ),
268 Point::Source { actor, output, .. } => write!(f, "{actor} opens a source of {output}"),
269 Point::Arrived { actor, output, .. } => write!(f, "{output} arrives at {actor}"),
270 Point::Pull { actor, output, .. } => {
271 write!(f, "{actor}'s source makes the next {output}")
272 }
273 Point::Closed {
274 actor,
275 output,
276 took_us,
277 gone: true,
278 ..
279 } => write!(
280 f,
281 "{actor} is gone: its source of {output} closed after {:.1} ms",
282 *took_us as f64 / 1000.0
283 ),
284 Point::Closed {
285 actor,
286 output,
287 took_us,
288 ..
289 } => write!(
290 f,
291 "{actor}'s source of {output} ran dry after {:.1} ms",
292 *took_us as f64 / 1000.0
293 ),
294 Point::Publish {
295 event,
296 bus,
297 subscribers,
298 } => write!(f, "publish {event} on the {bus} bus to {subscribers}"),
299 Point::Deliver { event, bus } => write!(f, "deliver {event} from the {bus} bus"),
300 Point::Push { reducer } => write!(f, "push into {reducer}"),
301 Point::Navigate { root, to } => write!(f, "{root} navigates to {to}"),
302 Point::Tick { timer } => write!(f, "timer #{timer}"),
303 Point::Render { segment, took_us } => {
304 write!(f, "{segment} drew itself in {:.1} ms", *took_us as f64 / 1000.0)
305 }
306 Point::Store {
307 op,
308 path,
309 field,
310 outside,
311 } => {
312 let who = if *outside { "disk" } else { "store" };
313 let verb = match op {
314 StoreOp::Set => "sets",
315 StoreOp::Delete => "deletes",
316 StoreOp::DeletePrefix => "clears",
317 };
318 write!(f, "{who} {verb} {path}")?;
319 match field {
320 Some(field) => write!(f, " ({field})"),
321 None => Ok(()),
322 }
323 }
324 Point::Log {
325 level,
326 target,
327 text,
328 ..
329 } => write!(f, "{level} {target}: {text}"),
330 Point::Span { name, fields, .. } if fields.is_empty() => f.write_str(name),
331 Point::Span { name, fields, .. } => write!(f, "{name} {fields}"),
332 Point::Note(text) => f.write_str(text),
333 }
334 }
335}