Skip to main content

Module trace

ytsaurus_client

Module trace 

Source
Expand description

The trace a request belongs to. The trace a request belongs to, carried to the cluster in a traceparent header.

The cluster is already instrumented: the proxy opens a span for every request it serves, and each of those spans either starts a trace of its own or continues one the caller named. Naming it is this whole module — a request sent with a traceparent shows up under the caller’s trace rather than as an orphan, so a launch that took four minutes can be looked at beside whatever asked for it.

The header is the W3C one:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             ^^ ^^ 32 hex: the trace  ^^ 16 hex: the caller's span  ^^ flags

All three official clients send exactly that: FormatTraceParentHeader in the C++ wrapper (yt/cpp/mapreduce/http/helpers.cpp), injectTracing in the Go SDK (yt/go/yt/internal/httpclient/client.go), and generate_traceparent in the Python wrapper (yt/python/yt/wrapper/). What the proxy accepts is TryParseTraceParent in yt/yt/core/http/helpers.cpp, and it is slightly wider than the standard: the version may be left off entirely — which is what the Go SDK does — and the flags are read as a byte with bit 0 sampled, bit 1 debug.

§Finding the trace afterwards

The cluster spells a trace id as one of its own GUIDs — 8e9bcc43-5c2be9b4-56f18c4e-117ea314 — and the header spells the same 128 bits as 32 hex digits. They are the same four 32-bit groups in the same order, so the only difference is the dashes and the leading zeros the cluster drops (WriteGuidToBuffer in library/cpp/yt/misc/guid.cpp, and FormatTraceParentHeader, which pads them back). TraceContext::yt_trace_id does that conversion, so the id can be pasted into the cluster’s own log search rather than translated by hand.

§Watched rather than assumed

A proxy puts the trace id it decided on into the X-YT-Trace-Id of the response, which makes every question above answerable with one request. On a local cluster, sending traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 to /api/v4/exists comes back with X-YT-Trace-Id: 4bf92f35-77b34da6-a3ce929d-e0e4736 — the same id, the cluster’s spelling, a leading zero dropped. The version-less form and uppercase hex are adopted the same way; a header that does not parse is answered 200 with an id the proxy invented, which is the whole reason TraceContext::parse refuses one rather than passing it on.

Structs§

TraceContext
The trace a request belongs to.