Setting the file. One moment.
Skill 52 · Exploring APM Traces
Subchapter 52.1
references/spans-and-fields.mdMarkdown7 KBView on GitHub
| Field | Type | Description |
|---|---|---|
uuid | string | Internal row UUID (rarely useful for analysis) |
trace_id | hex string | 32-char hex ID linking every span in one trace |
span_id | hex string | 16-char hex ID for this span |
parent_span_id | hex string | Parent span’s hex ID. Zero-padded "00000000…" for root spans |
name | string | Operation name (e.g. HTTP GET /api/users, db.query) |
kind | int 0–5 | OpenTelemetry span kind (see enum below) |
service_name | string | Service that emitted the span |
status_code | int 0–2 | OpenTelemetry status (see enum below). 2 is the only error indicator |
timestamp | ISO 8601 | Start time |
end_time | ISO 8601 | End time |
duration_nano | int | Duration in nanoseconds (1s = 1_000_000_000) |
is_root_span | bool | Convenience flag for the trace entry — prefer this over comparing parent ID |
matched_filter | int 0/1 | 1 if this span matched the query-apm-spans filter; 0 if it only shares a trace with a match (root/prefetched sibling). Always present; only meaningful from query-apm-spans |
attributes | map | Span-level OTel attributes the span set, e.g. http.method, db.statement, net.peer.name. A string-keyed map |
self_time_nano | int | apm-trace-get only. Duration not covered by child spans (interval union — overlapping/parallel children counted once). Leaf: own duration. Parent: the unaccounted gap — sort by this to find where wall-clock actually went |
Returned in the payload: span-level attributes (above) — read them straight off the span.
Not returned in the payload: resource attributes (k8s labels, service.version, deployment metadata). Discover them via apm-attributes-list (type resource) and fetch values via apm-attribute-values-list.
| Value | Label | Meaning |
|---|---|---|
0 | Unspecified | Default when no kind is set |
1 | Internal | Internal operation, no remote boundary |
2 | Server | Inbound side of a synchronous remote call |
3 | Client | Outbound side of a synchronous remote call |
4 | Producer | Producer side of an async messaging system |
5 | Consumer | Consumer side of an async messaging system |
A synchronous downstream call typically pairs a Client span on the caller with a matching Server span on the callee.
| Value | Label | Meaning |
|---|---|---|
0 | Unset | No status reported |
1 | OK | Operation completed without error |
2 | Error | Operation failed |
UI filter chips for status_code = OK match {0, 1}, but the underlying integer column only stores the raw value. When filtering programmatically, treat any span with status_code == 2 as the error set.
type value | Filters on |
|---|---|
span | Built-in span fields: trace_id, span_id, duration, name, kind, status_code, is_root_span |
span_attribute | Span-level attributes (e.g. http.method, db.statement) |
span_resource_attribute | Resource-level attributes (e.g. k8s.pod.name, service.version) |
duration filters take values in nanoseconds (the column is duration_nano). The frontend translates 1000ms → 1_000_000_000 before sending.
is_root_span filters take true/false — filter true to isolate entry/request spans (e.g. request counts for RED metrics).