trace_id, span_id, service.name, name, start_time_unix_nano, end_time_unix_nano, and status_code. A stream named default wins over other streams that qualify, and the stream name breaks the remaining ties. An organization without such a stream gets empty results. Only traces that survived tail sampling are readable.
All calls require streams.query, or sys.telemetry.read in the system scope.
List trace summaries
A filter is an object with
field, op, and value, and a request carries at most 32 filters. All filters must match. The operator in takes values, a list of values, in place of value.
A filter names its field as the stream names it, such as
service.name or name; no other name stands for a field. The operators eq, ne, and like are aliases of =, !=, and contains. A JSON field is not filterable.
trace_id, duration_ns, span_count, and error_count are compared on the trace. Every other field belongs to a span: a filter on it matches a trace when one of its spans passes the filter, and != matches a trace when none of its spans has the value. A span without the field does not have the value.
in matches any of its values: from 1 to 64 values, each up to 512 bytes and of the field’s type. A value listed twice counts once. On a span field, in matches a trace when one of its spans has one of the values.
where says what the list of filters cannot: alternatives. It is a JSON object in one of four forms:
filters, q, and where hold together. A filter in the tree keeps its meaning: one on a span field matches a trace when one of its spans passes it, and != when none of its spans has the value. A trace matches {"or": [A, B]} when it matches A or matches B. The filters of filters and where count together toward the limit of 32. A tree looks for text at most 8 times, nests groups at most 8 deep, and has at least one condition in each group.
checkout or more than 50 spans.
A cursor binds the page to the query that issued it. Repeating a request with a cursor and a different limit, sort, q, filters, or where answers 400.
service and operation of the root span, the start time in nanoseconds, the duration in milliseconds, the number of spans, and the number of error spans. has_more is true when next_cursor is set.
Count traces over time
q, filters, and where of the list, and matches the same traces. The caller chooses the buckets.
Query parameters
A request covers at most 512 buckets from
origin_micros to to.
buckets lists only the buckets that hold a trace, oldest first. total is the number of traces that started in the bucket. errors is the number of those traces with at least one error span. p50_ns, p95_ns, and p99_ns are the median, 95th, and 99th percentile durations of those traces in nanoseconds. They are estimates and are absent when no duration was counted.
The count reads the trace summaries, and the spans when a filter is on a span field. The list returns one summary for each trace. A summary that a retried write stored twice counts twice.
When the count is not available, the call still answers 200. buckets is then empty, and unavailable gives the reason.
List spans
q, filters, and where of the trace list, and reads them for each span: a filter on a span field holds for the span itself, and != keeps a span without the field. duration_ns is the span’s own duration. span_count and error_count are those of the trace the span belongs to. A span matches {"or": [A, B]} when it matches A or matches B.
Query parameters
status is OK, ERROR, or UNSET. kind numbers the span kind as OTLP does: 1 internal, 2 server, 3 client, 4 producer, 5 consumer. parent_span_id, kind, and http_status_code are absent when the span has none. The call runs as a tracked query and is admitted like any other query.
Read one trace
trace_id has 1 to 128 characters from A-Z, a-z, 0-9, -, and _.
Query parameters
The response is limited to 100,000 spans and 32 MiB.
truncated is true when a limit cut the span list.
trace_flags, trace_state, resource, scope, the dropped_*_count counters, schema_version, and semantic_conventions_version.
Find the spans that link to a trace
from and to as the trace detail, and searches that window.
spans lists up to 200 linking spans, newest first, and more is true when more spans link to the trace. linked_span_id is the span of this trace that the link points at, and attributes holds the attributes of the link.
The search reads the links of every span in the window as text, within the time budget of the trace count. When it cannot finish, the call still answers 200 with an empty spans and an unavailable reason: time_budget, busy, or scan_limit, as for the trace count.
Errors