Skip to main content

astrs_cli/command/
trace.rs

1//! `astrs trace` (blueprint §13, §17): a minimal causal span listing.
2//!
3//! ```text
4//!   astrs trace [dataflow] [--node n]  ─► GetTraces  ─► TraceData{spans}
5//! ```
6//!
7//! This is deliberately the whole feature: a summary table (or `--json`)
8//! over whatever [`astrs_wire::ControlReply::TraceData`] answers with. A
9//! full tracing UI (causal graphs, cross-daemon span joins) is out of
10//! scope for this wave — see `astrs-coordinator`'s `handlers::misc::get_traces`
11//! for exactly how far span collection reaches today (coordinator-local,
12//! honestly empty until something feeds it) and this crate's final report
13//! for what wiring a real feed would take.
14
15use std::io::Write;
16
17use astrs_time::HlcTimestamp;
18use astrs_wire::{ControlReply, ControlRequest, NodeId, SpanStatus, TraceSpan};
19
20use crate::command::client::{Client, DataflowRef, Endpoint, reply_name, runtime};
21use crate::error::CliError;
22
23/// `astrs trace` arguments.
24#[derive(Debug, Clone, Default)]
25pub struct TraceArgs {
26    /// The dataflow to trace; `None` traces every dataflow the coordinator
27    /// knows about.
28    pub dataflow: Option<String>,
29    /// Only spans from this node.
30    pub node: Option<String>,
31    /// Only spans starting at or after this HLC timestamp.
32    pub since: Option<HlcTimestamp>,
33    /// Stop after this many spans.
34    pub limit: Option<u32>,
35    /// Emit JSON rather than a summary table.
36    pub json: bool,
37}
38
39/// What `astrs trace` printed.
40#[derive(Debug, Clone)]
41pub struct TraceReport {
42    /// The spans the coordinator answered with, oldest first.
43    pub spans: Vec<TraceSpan>,
44}
45
46/// Runs `astrs trace`.
47///
48/// # Errors
49///
50/// - [`CliError::BadArgument`] for an unusable `--node`.
51/// - [`CliError::UnknownDataflow`] if a named dataflow resolves to nothing.
52/// - As [`Client::connect`]/[`Client::request`] otherwise.
53pub fn run(
54    out: &mut dyn Write,
55    endpoint: &Endpoint,
56    args: &TraceArgs,
57) -> Result<TraceReport, CliError> {
58    let node = match &args.node {
59        Some(text) => Some(NodeId::new(text).map_err(|error| CliError::BadArgument {
60            flag: "node",
61            value: text.clone(),
62            reason: error.to_string(),
63        })?),
64        None => None,
65    };
66    let runtime = runtime()?;
67    let spans = runtime.block_on(async {
68        let mut client = Client::connect(endpoint).await?;
69        let dataflow = match &args.dataflow {
70            Some(text) => Some(client.resolve(&DataflowRef::parse(text)).await?),
71            None => None,
72        };
73        match client
74            .request(
75                "trace",
76                &ControlRequest::GetTraces {
77                    dataflow,
78                    node,
79                    since: args.since,
80                    limit: args.limit,
81                },
82            )
83            .await?
84        {
85            ControlReply::TraceData { traces } => Ok(traces.spans),
86            other => Err(CliError::UnexpectedReply {
87                request: "trace",
88                reply: reply_name(&other),
89            }),
90        }
91    })?;
92    print_trace(out, &spans, args.json);
93    Ok(TraceReport { spans })
94}
95
96/// Prints a summary table, or the spans verbatim as JSON.
97fn print_trace(out: &mut dyn Write, spans: &[TraceSpan], json: bool) {
98    if json {
99        let rendered: Vec<serde_json::Value> = spans.iter().map(span_json).collect();
100        let _ = writeln!(
101            out,
102            "{}",
103            serde_json::to_string_pretty(&serde_json::json!({ "spans": rendered }))
104                .unwrap_or_else(|_| "{}".to_owned())
105        );
106        let _ = out.flush();
107        return;
108    }
109    if spans.is_empty() {
110        let _ = writeln!(
111            out,
112            "no spans (span collection is coordinator-local and empty until a feed is wired)"
113        );
114        let _ = out.flush();
115        return;
116    }
117    let name_width = spans
118        .iter()
119        .map(|span| span.name.len())
120        .max()
121        .unwrap_or(0)
122        .max("NAME".len());
123    let _ = writeln!(
124        out,
125        "{:<16} {:<name_width$} {:<8} {:<12} {:<12}",
126        "TRACE", "NAME", "STATUS", "NODE", "DURATION"
127    );
128    for span in spans {
129        let _ = writeln!(
130            out,
131            "{:<16} {:<name_width$} {:<8} {:<12} {:<12}",
132            short_id(&span.trace_id),
133            span.name,
134            status_word(span.status),
135            span.node.as_ref().map_or("-", NodeId::as_str),
136            duration_of(span).map_or_else(|| "-".to_owned(), |d| format!("{d:.3}s")),
137        );
138    }
139    let _ = out.flush();
140}
141
142/// One span as a JSON object.
143fn span_json(span: &TraceSpan) -> serde_json::Value {
144    serde_json::json!({
145        "trace_id": span.trace_id,
146        "span_id": span.span_id,
147        "parent_span_id": span.parent_span_id,
148        "name": span.name,
149        "status": status_word(span.status),
150        "dataflow": span.dataflow.map(|id| id.to_string()),
151        "node": span.node.as_ref().map(NodeId::as_str),
152        "start": span.start.to_string(),
153        "end": span.end.map(|end| end.to_string()),
154        "duration_secs": duration_of(span),
155        "attributes": span.attributes,
156    })
157}
158
159/// A short, still-distinguishing prefix of a hex trace/span id, so the
160/// table stays readable.
161fn short_id(id: &str) -> String {
162    id.chars().take(12).collect()
163}
164
165/// A stable lower-case word for a span's status.
166const fn status_word(status: SpanStatus) -> &'static str {
167    match status {
168        SpanStatus::Ok => "ok",
169        SpanStatus::Error => "error",
170        SpanStatus::Unset => "unset",
171        // `SpanStatus` is `#[non_exhaustive]`; an unknown status is shown
172        // rather than hidden.
173        _ => "unknown",
174    }
175}
176
177/// The span's wall-clock duration, in seconds, when it has closed.
178///
179/// [`HlcTimestamp`]'s ordering is causal, not purely physical, so this is a
180/// display convenience, not a latency measurement to alarm on.
181fn duration_of(span: &TraceSpan) -> Option<f64> {
182    let end = span.end?;
183    Some(
184        end.physical_duration_since(&span.start)
185            .unwrap_or_default()
186            .as_secs_f64(),
187    )
188}
189
190#[cfg(test)]
191mod tests {
192    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
193
194    use super::*;
195
196    fn span(name: &str, status: SpanStatus, start: u64, end: Option<u64>) -> TraceSpan {
197        let span = TraceSpan::new(
198            "0123456789abcdef0123456789abcdef",
199            "abcdef0123456789",
200            name,
201            HlcTimestamp::new(start, 0),
202        )
203        .with_status(status);
204        match end {
205            Some(end) => span.with_end(HlcTimestamp::new(end, 0)),
206            None => span,
207        }
208    }
209
210    #[test]
211    fn trace_reports_a_dead_cluster_rather_than_hanging() {
212        let endpoint = Endpoint::new(
213            std::net::SocketAddr::from(([127, 0, 0, 1], 1)),
214            astrs_wire::AuthToken::ZERO,
215        );
216        let error = run(&mut Vec::new(), &endpoint, &TraceArgs::default()).unwrap_err();
217        assert!(matches!(error, CliError::NoCluster { .. }), "{error}");
218    }
219
220    #[test]
221    fn an_unusable_node_flag_is_refused_before_the_dial() {
222        let endpoint = Endpoint::new(
223            std::net::SocketAddr::from(([127, 0, 0, 1], 1)),
224            astrs_wire::AuthToken::ZERO,
225        );
226        let args = TraceArgs {
227            node: Some("not a node".to_owned()),
228            ..TraceArgs::default()
229        };
230        let error = run(&mut Vec::new(), &endpoint, &args).unwrap_err();
231        assert!(
232            matches!(error, CliError::BadArgument { flag: "node", .. }),
233            "{error}"
234        );
235    }
236
237    #[test]
238    fn an_empty_span_list_says_so_rather_than_printing_a_bare_header() {
239        let mut out = Vec::new();
240        print_trace(&mut out, &[], false);
241        let text = String::from_utf8(out).unwrap();
242        assert!(text.contains("no spans"), "{text}");
243    }
244
245    #[test]
246    fn the_table_lists_every_span_with_its_status_and_duration() {
247        let spans = vec![
248            span("publish", SpanStatus::Ok, 0, Some(2_000_000_000)),
249            span("deliver", SpanStatus::Error, 5, None),
250        ];
251        let mut out = Vec::new();
252        print_trace(&mut out, &spans, false);
253        let text = String::from_utf8(out).unwrap();
254        assert!(text.contains("publish"), "{text}");
255        assert!(text.contains("deliver"), "{text}");
256        assert!(text.contains("ok"), "{text}");
257        assert!(text.contains("error"), "{text}");
258        assert!(text.contains("2.000s"), "{text}");
259    }
260
261    #[test]
262    fn json_output_carries_every_span_field() {
263        let spans = vec![span("publish", SpanStatus::Ok, 0, Some(1_000_000_000))];
264        let mut out = Vec::new();
265        print_trace(&mut out, &spans, true);
266        let text = String::from_utf8(out).unwrap();
267        let value: serde_json::Value = serde_json::from_str(&text).unwrap();
268        assert_eq!(value["spans"][0]["name"], "publish");
269        assert_eq!(value["spans"][0]["status"], "ok");
270    }
271
272    #[test]
273    fn a_span_never_closed_shows_no_duration() {
274        let s = span("hung", SpanStatus::Unset, 0, None);
275        assert_eq!(duration_of(&s), None);
276    }
277}