1use 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#[derive(Debug, Clone, Default)]
25pub struct TraceArgs {
26 pub dataflow: Option<String>,
29 pub node: Option<String>,
31 pub since: Option<HlcTimestamp>,
33 pub limit: Option<u32>,
35 pub json: bool,
37}
38
39#[derive(Debug, Clone)]
41pub struct TraceReport {
42 pub spans: Vec<TraceSpan>,
44}
45
46pub 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
96fn 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
142fn 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
159fn short_id(id: &str) -> String {
162 id.chars().take(12).collect()
163}
164
165const fn status_word(status: SpanStatus) -> &'static str {
167 match status {
168 SpanStatus::Ok => "ok",
169 SpanStatus::Error => "error",
170 SpanStatus::Unset => "unset",
171 _ => "unknown",
174 }
175}
176
177fn 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}