Skip to main content

grow_apache_skywalking/
native.rs

1// Service code (Apache SkyWalking): the native query model and its SPEC §5 conversion.
2//! The native SkyWalking query model (GraphQL: spans, traces, topology) and its conversion into
3//! the SPEC §5 trace model. Native trace ids are opaque strings (`<hex>.<n>.<ms>`) and are kept
4//! verbatim; native span ids become `"<segmentId>-<spanId>"`.
5
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8
9use crate::tracing::{
10    sort_spans, AttrValue, Attributes, DependencyLink, Span, SpanEvent, SpanKind, SpanLink,
11    SpanStatus, StatusCode, Trace,
12};
13
14/// A `{key, value}` pair (span tags, log tags, log data).
15#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
16pub struct KeyValue {
17    /// Key.
18    pub key: String,
19    /// Value (non-string values are stringified, `null` → `""`).
20    pub value: String,
21}
22
23impl KeyValue {
24    /// A pair.
25    pub fn new(key: impl Into<String>, value: impl Into<String>) -> Self {
26        KeyValue {
27            key: key.into(),
28            value: value.into(),
29        }
30    }
31}
32
33/// Cross-segment reference of a native span.
34#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
35#[serde(rename_all = "camelCase")]
36pub struct NativeSpanRef {
37    /// Trace id.
38    pub trace_id: String,
39    /// Segment id of the parent.
40    pub parent_segment_id: String,
41    /// Span id of the parent within its segment.
42    pub parent_span_id: i64,
43    /// `CROSS_PROCESS` or `CROSS_THREAD`.
44    #[serde(rename = "type")]
45    pub ref_type: String,
46}
47
48/// A log entry recorded on a native span.
49#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
50pub struct NativeSpanLog {
51    /// Epoch milliseconds.
52    pub time: i64,
53    /// Log fields.
54    pub data: Vec<KeyValue>,
55}
56
57/// A span as stored by SkyWalking (agents, `/v3/segments`); identity = `(segment_id, span_id)`.
58#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase")]
60pub struct NativeSpan {
61    /// Opaque native trace id, or a hex id from an OTel context.
62    pub trace_id: String,
63    /// Segment id.
64    pub segment_id: String,
65    /// Span id within the segment.
66    pub span_id: i64,
67    /// Parent within the segment; `-1` = segment root (parent in `refs`).
68    pub parent_span_id: i64,
69    /// Cross-segment references.
70    pub refs: Vec<NativeSpanRef>,
71    /// Service name.
72    pub service_code: String,
73    /// Instance name.
74    pub service_instance_name: String,
75    /// Epoch milliseconds.
76    pub start_time: i64,
77    /// Epoch milliseconds.
78    pub end_time: i64,
79    /// Endpoint (operation) name.
80    pub endpoint_name: String,
81    /// `Entry`, `Exit` or `Local`.
82    #[serde(rename = "type")]
83    pub span_type: String,
84    /// Remote address.
85    pub peer: String,
86    /// Component name.
87    pub component: String,
88    /// Error flag.
89    pub is_error: bool,
90    /// Layer (`Http`, `Database`, …).
91    pub layer: String,
92    /// Tags.
93    pub tags: Vec<KeyValue>,
94    /// Span logs.
95    pub logs: Vec<NativeSpanLog>,
96}
97
98/// A native trace: every segment's spans.
99#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
100#[serde(rename_all = "camelCase")]
101pub struct NativeTrace {
102    /// Trace id (verbatim).
103    pub trace_id: String,
104    /// Spans of every segment.
105    pub spans: Vec<NativeSpan>,
106}
107
108/// A node of the service topology.
109#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
110#[serde(rename_all = "camelCase")]
111pub struct TopologyNode {
112    /// Service id.
113    pub id: String,
114    /// Service name.
115    pub name: String,
116    /// Node type (component), may be empty.
117    #[serde(rename = "type")]
118    pub node_type: String,
119    /// `false` for virtual nodes (e.g. `User`).
120    pub is_real: bool,
121    /// Layers.
122    pub layers: Vec<String>,
123}
124
125/// An edge of the service topology.
126#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
127#[serde(rename_all = "camelCase")]
128pub struct TopologyCall {
129    /// Edge id.
130    pub id: String,
131    /// Source node id.
132    pub source: String,
133    /// Target node id.
134    pub target: String,
135    /// `CLIENT` / `SERVER` / `PROXY`.
136    pub detect_points: Vec<String>,
137    /// Components seen at the source.
138    pub source_components: Vec<String>,
139    /// Components seen at the target.
140    pub target_components: Vec<String>,
141}
142
143/// `getGlobalTopology` / `getServiceTopology` result.
144#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
145pub struct Topology {
146    /// Nodes.
147    pub nodes: Vec<TopologyNode>,
148    /// Edges.
149    pub calls: Vec<TopologyCall>,
150}
151
152/// GraphQL selection used for native spans.
153pub const NATIVE_SPAN_FIELDS: &str = "traceId segmentId spanId parentSpanId refs{traceId parentSegmentId parentSpanId type} serviceCode serviceInstanceName startTime endTime endpointName type peer component isError layer tags{key value} logs{time data{key value}}";
154
155pub(crate) fn str_of(v: &Value, key: &str) -> String {
156    v.get(key)
157        .and_then(Value::as_str)
158        .unwrap_or_default()
159        .to_owned()
160}
161
162pub(crate) fn i64_of(v: &Value, key: &str, fallback: i64) -> i64 {
163    v.get(key)
164        .and_then(|x| x.as_i64().or_else(|| x.as_f64().map(|f| f as i64)))
165        .unwrap_or(fallback)
166}
167
168pub(crate) fn objects(v: Option<&Value>) -> impl Iterator<Item = &Value> {
169    v.and_then(Value::as_array)
170        .into_iter()
171        .flatten()
172        .filter(|x| x.is_object())
173}
174
175pub(crate) fn strings(v: Option<&Value>) -> Vec<String> {
176    v.and_then(Value::as_array)
177        .into_iter()
178        .flatten()
179        .filter_map(Value::as_str)
180        .map(str::to_owned)
181        .collect()
182}
183
184/// Decodes a `[{key, value}]` list (non-string values are stringified, `null` → `""`).
185pub fn key_values(value: Option<&Value>) -> Vec<KeyValue> {
186    objects(value)
187        .map(|kv| KeyValue {
188            key: str_of(kv, "key"),
189            value: match kv.get("value") {
190                Some(Value::String(s)) => s.clone(),
191                None | Some(Value::Null) => String::new(),
192                Some(other) => other.to_string(),
193            },
194        })
195        .collect()
196}
197
198/// Decodes one native span from a GraphQL response (missing fields get neutral defaults).
199pub fn decode_native_span(raw: &Value) -> NativeSpan {
200    NativeSpan {
201        trace_id: str_of(raw, "traceId"),
202        segment_id: str_of(raw, "segmentId"),
203        span_id: i64_of(raw, "spanId", 0),
204        parent_span_id: i64_of(raw, "parentSpanId", -1),
205        refs: objects(raw.get("refs"))
206            .map(|r| NativeSpanRef {
207                trace_id: str_of(r, "traceId"),
208                parent_segment_id: str_of(r, "parentSegmentId"),
209                parent_span_id: i64_of(r, "parentSpanId", 0),
210                ref_type: str_of(r, "type"),
211            })
212            .collect(),
213        service_code: str_of(raw, "serviceCode"),
214        service_instance_name: str_of(raw, "serviceInstanceName"),
215        start_time: i64_of(raw, "startTime", 0),
216        end_time: i64_of(raw, "endTime", 0),
217        endpoint_name: str_of(raw, "endpointName"),
218        span_type: str_of(raw, "type"),
219        peer: str_of(raw, "peer"),
220        component: str_of(raw, "component"),
221        is_error: raw.get("isError") == Some(&Value::Bool(true)),
222        layer: str_of(raw, "layer"),
223        tags: key_values(raw.get("tags")),
224        logs: objects(raw.get("logs"))
225            .map(|l| NativeSpanLog {
226                time: i64_of(l, "time", 0),
227                data: key_values(l.get("data")),
228            })
229            .collect(),
230    }
231}
232
233/// Decodes a list of native spans into a [`NativeTrace`]; `None` when empty.
234pub fn native_trace_from_spans(raw: Option<&Value>) -> Option<NativeTrace> {
235    let spans: Vec<NativeSpan> = raw
236        .and_then(Value::as_array)
237        .into_iter()
238        .flatten()
239        .map(decode_native_span)
240        .collect();
241    let trace_id = spans.first()?.trace_id.clone();
242    Some(NativeTrace { trace_id, spans })
243}
244
245/// Decodes a topology result.
246pub fn decode_topology(raw: &Value) -> Topology {
247    Topology {
248        nodes: objects(raw.get("nodes"))
249            .map(|n| TopologyNode {
250                id: str_of(n, "id"),
251                name: str_of(n, "name"),
252                node_type: str_of(n, "type"),
253                is_real: n.get("isReal") == Some(&Value::Bool(true)),
254                layers: strings(n.get("layers")),
255            })
256            .collect(),
257        calls: objects(raw.get("calls"))
258            .map(|c| TopologyCall {
259                id: str_of(c, "id"),
260                source: str_of(c, "source"),
261                target: str_of(c, "target"),
262                detect_points: strings(c.get("detectPoints")),
263                source_components: strings(c.get("sourceComponents")),
264                target_components: strings(c.get("targetComponents")),
265            })
266            .collect(),
267    }
268}
269
270/// Composite SPEC span id of a native span: `<segmentId>-<spanId>`.
271pub fn native_span_key(segment_id: &str, span_id: i64) -> String {
272    format!("{segment_id}-{span_id}")
273}
274
275fn kind_of(span_type: &str) -> SpanKind {
276    match span_type {
277        "Entry" => SpanKind::Server,
278        "Exit" => SpanKind::Client,
279        "Local" => SpanKind::Internal,
280        _ => SpanKind::Unspecified,
281    }
282}
283
284fn ms_to_micros(ms: i64) -> u64 {
285    (ms.max(0) as u64).saturating_mul(1000)
286}
287
288/// Converts a native span into the SPEC §5 model. Ids are kept verbatim: `span_id =
289/// "<segmentId>-<spanId>"`; the parent is the same segment's `parentSpanId` when ≥ 0, else
290/// `refs[0]` (`"<parentSegmentId>-<parentSpanId>"`); further refs become links. `kind`: Entry →
291/// server, Exit → client, Local → internal. Times ms → µs. Status `error` when `isError`.
292/// Attributes = tags plus `sw.component`, `sw.layer`, `sw.peer`, `sw.service_instance` (when
293/// set). Span logs become events (name = the `event` data value, else `log`).
294pub fn native_span_to_span(span: &NativeSpan) -> Span {
295    let mut attributes = Attributes::new();
296    for kv in &span.tags {
297        attributes.insert(kv.key.clone(), AttrValue::String(kv.value.clone()));
298    }
299    for (key, value) in [
300        ("sw.component", &span.component),
301        ("sw.layer", &span.layer),
302        ("sw.peer", &span.peer),
303        ("sw.service_instance", &span.service_instance_name),
304    ] {
305        if !value.is_empty() {
306            attributes.insert(key.to_owned(), AttrValue::String(value.clone()));
307        }
308    }
309    let start = ms_to_micros(span.start_time);
310    let end = ms_to_micros(span.end_time.max(span.start_time));
311    let parent_span_id = if span.parent_span_id >= 0 {
312        Some(native_span_key(&span.segment_id, span.parent_span_id))
313    } else {
314        span.refs
315            .first()
316            .map(|r| native_span_key(&r.parent_segment_id, r.parent_span_id))
317    };
318    let skip = usize::from(span.parent_span_id < 0);
319    Span {
320        trace_id: span.trace_id.clone(),
321        span_id: native_span_key(&span.segment_id, span.span_id),
322        parent_span_id,
323        name: span.endpoint_name.clone(),
324        kind: kind_of(&span.span_type),
325        service_name: span.service_code.clone(),
326        start_micros: start,
327        end_micros: end,
328        duration_micros: end - start,
329        status: SpanStatus {
330            code: if span.is_error {
331                StatusCode::Error
332            } else {
333                StatusCode::Unset
334            },
335            message: None,
336        },
337        attributes,
338        events: span
339            .logs
340            .iter()
341            .map(|log| {
342                let attributes: Attributes = log
343                    .data
344                    .iter()
345                    .map(|kv| (kv.key.clone(), AttrValue::String(kv.value.clone())))
346                    .collect();
347                let name = log
348                    .data
349                    .iter()
350                    .find(|kv| kv.key == "event")
351                    .map(|kv| kv.value.clone())
352                    .unwrap_or_else(|| "log".to_owned());
353                SpanEvent {
354                    name,
355                    time_micros: ms_to_micros(log.time),
356                    attributes,
357                }
358            })
359            .collect(),
360        links: span
361            .refs
362            .iter()
363            .skip(skip)
364            .map(|r| SpanLink {
365                trace_id: r.trace_id.clone(),
366                span_id: native_span_key(&r.parent_segment_id, r.parent_span_id),
367                attributes: [(
368                    "sw.ref_type".to_owned(),
369                    AttrValue::String(r.ref_type.clone()),
370                )]
371                .into_iter()
372                .collect(),
373            })
374            .collect(),
375    }
376}
377
378/// Converts a native trace into a SPEC [`Trace`] (spans sorted); `None` when empty.
379pub fn native_trace_to_trace(trace: &NativeTrace) -> Option<Trace> {
380    if trace.spans.is_empty() {
381        return None;
382    }
383    let mut spans: Vec<Span> = trace.spans.iter().map(native_span_to_span).collect();
384    sort_spans(&mut spans);
385    Some(Trace {
386        trace_id: trace.trace_id.clone(),
387        spans,
388    })
389}
390
391/// Topology → dependency links (`parent` = source node name, `child` = target node name,
392/// `call_count` = 0 because the topology carries no call counts). Sorted by parent, child.
393pub fn topology_to_dependencies(topology: &Topology) -> Vec<DependencyLink> {
394    let name = |id: &str| {
395        topology
396            .nodes
397            .iter()
398            .find(|n| n.id == id)
399            .map(|n| n.name.clone())
400            .unwrap_or_else(|| id.to_owned())
401    };
402    let mut links: Vec<DependencyLink> = topology
403        .calls
404        .iter()
405        .map(|c| DependencyLink {
406            parent: name(&c.source),
407            child: name(&c.target),
408            call_count: 0,
409        })
410        .collect();
411    links.sort_by(|a, b| a.parent.cmp(&b.parent).then_with(|| a.child.cmp(&b.child)));
412    links
413}