Dekoder traceparent — W3C Trace Context

Czym jest nagłówek traceparent?

# The header as it travels on the wire
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate:  rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

# Read the four fields apart
#   version     00
#   trace-id    4bf92f3577b34da6a3ce929d0e0e4736   (16 bytes, whole request)
#   parent-id   00f067aa0ba902b7                   (8 bytes, calling span)
#   trace-flags 01                                 (bit 0 set = sampled)

# Send one yourself
$ curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
       https://example.com/api

Kluczowe funkcje

Przykłady traceparent, zdekodowane

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

version 00 · trace-id 4bf92f3577b34da6a3ce929d0e0e4736 · parent-id 00f067aa0ba902b7 · trace-flags 01 (sampled)

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00

Nagłówek poprawny · bit sampled wyzerowany

00-00000000000000000000000000000000-00f067aa0ba902b7-01

Nieprawidłowy — trace-id z samych zer

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

x-datadog-trace-id 11803532876627986230 · _dd.p.tid 4bf92f3577b34da6

Jak korzystać z dekodera traceparent

1. 1

   Wklej nagłówek traceparent

   Wystarczy wstawić surową wartość nagłówka — na przykład 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. Dekodowanie odbywa się w trakcie pisania, nie trzeba niczego klikać.

2. 2

   Odczytaj cztery pola osobno

   Version, trace-id, parent-id i trace-flags trafiają do własnych wierszy, każdy z przyciskiem kopiowania, dzięki czemu sam trace ID można przenieść do zapytania bez ręcznego zaznaczania 32 znaków.

3. 3

   Sprawdź flagi bit po bicie

   Bajt trace-flags zostaje rozłożony na wszystkie osiem bitów wraz z ich maskami, więc sampled i flaga random-trace-id z poziomu Level 2 są widoczne osobno, a nie ukryte w dwuznakowej wartości.

4. 4

   Przelicz na format swojego backendu

   Pod spodem generowane są identyfikatory Datadog, AWS X-Ray oraz obie postacie B3, łącznie z dziesiętnym trace ID z dolnych 64 bitów, którego oczekuje Datadog, i tagiem z górnych 64 bitów podróżującym obok niego.

5. 5

   Dodaj tracestate i udostępnij wynik

   Wklejenie nagłówka tracestate wypisuje jego człony z osobną walidacją każdego z nich i licznikiem względem limitu 32 członów, a przycisk Kopiuj link zapisuje dokładny stan w adresie URL, który da się wkleić do zgłoszenia.

Najczęstsze błędy przy traceparent

if (traceFlags === 0x01) { record(); }

if (traceFlags & 0x01) { record(); }

x-datadog-trace-id: 100985939111033328018442752961257817910

x-datadog-trace-id: 11803532876627986230
x-datadog-tags: _dd.p.tid=4bf92f3577b34da6

if (version !== '00') throw new Error('bad traceparent');

if (version !== '00' && header.length >= 55) { /* parse the known prefix */ }

traceparent: 00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Co można zrobić dekoderem traceparent

Ustal, dlaczego ślad nie ma spanów

Wystarczy wkleić przychodzący nagłówek i odczytać bit sampled. Gdy jest wyzerowany, ślad i tak nie miał być rejestrowany, a odpowiedź leży po stronie wywołującego, nie instrumentacji — rozróżnienie, które oszczędza mnóstwo czasu poświęcanego na audyt własnej konfiguracji samplera.

Znajdź ślad, którego backend nie widzi

Gdy trace ID skopiowany z logów aplikacji niczego nie zwraca w Datadog, winny jest zwykle format. Przeliczenie go tutaj pokazuje dziesiętny identyfikator z dolnych 64 bitów, którego oczekuje API, wraz z tagiem z górnych 64 bitów, który musi mu towarzyszyć.

Zweryfikuj nagłówki wstrzykiwane przez bramę

Proxy i service mesh generują kontekst śladu na wejściu. Wklejenie tego, co faktycznie dotarło, pozwala potwierdzić długość, małe litery w zapisie szesnastkowym i niezerowe identyfikatory, zanim uzna się, że wina leży dalej.

Odtwórz produkcyjny ślad ręcznie

Nagłówek z prawdziwego żądania można odtworzyć wobec środowiska testowego, żeby przejść tym samym śladem. Żądanie da się zbudować kreatorem poleceń curl i wkleić nagłówek prosto do niego.

Wyjaśnij zespołowi kontekst śladu

Tabele anatomii pól i wartości trace-flags na tej stronie są statycznym materiałem referencyjnym, na który można wskazać, a gotowe przyciski pokazują każdy rodzaj błędu bez psucia jakiejkolwiek usługi.

Jak działa walidator W3C Trace Context

Gramatyka czterech pól

Kolejność jest taka: version, myślnik, trace-id, myślnik, parent-id, myślnik, trace-flags — w całości małymi literami w zapisie szesnastkowym. Version ma 2 cyfry, trace-id 32, parent-id 16, a trace-flags 2 — 52 cyfry szesnastkowe plus 3 myślniki, dokładnie 55 znaków dla wersji 00. Wielkie litery w zapisie szesnastkowym unieważniają nagłówek, choć wartość wygląda poprawnie, a trace-id i parent-id złożone z samych zer są jawnie nieprawidłowe, a nie puste.

Trace-flags to pole bitowe

Bit 0 (maska 0x01) to sampled: ustawiony oznacza, że wywołujący mógł zarejestrować dane śladu. Bit 1 (maska 0x02), wprowadzony w Level 2, to random-trace-id: gdy jest ustawiony, co najmniej siedem skrajnie prawych bajtów trace-id musiało zostać wylosowanych z rozkładem równomiernym, co pozwala systemom niżej w łańcuchu próbkować lub dzielić ruch po tych bajtach. Bity od 2 do 7 są zarezerwowane, trzeba je ignorować przy odbiorze i zerować w żądaniach wychodzących. Ponieważ bity zarezerwowane mogą być obecne, pole trzeba sprawdzać operacją bitową AND — porównanie na równość z 0x01 błędnie zaraportuje próbkowany ślad, który niesie też bit zarezerwowany.

Zgodność w przód z przyszłymi wersjami

Version to dzisiaj 00, a ff jest zakazane, ale parser odrzucający wszystko inne działa źle. Specyfikacja prosi odbiorców, aby przy wyższej wersji spróbowali analizy, o ile nagłówek jest co najmniej tak długi jak znany format: odczytali pola, które rozpoznają, i tolerowali dodatkowe dane na końcu, zamiast rozpoczynać ślad od nowa. Ten dekoder trzyma się tej reguły: przyszła wersja zostaje przeanalizowana poprawnie i oznaczona jako ostrzeżenie, a nie błąd.

Limity tracestate, które bolą na produkcji

Najwyżej 32 człony listy — to twarda granica gramatyczna, więc dłuższa lista czyni nagłówek nieprawidłowym, a odbiorcy go odrzucają. Każdy klucz ma najwyżej 256 znaków i zaczyna się od małej litery lub cyfry; od Level 2 znak @ jest zwykłym znakiem klucza, a nie separatorem najemcy. Każda wartość to od 1 do 256 drukowalnych znaków ASCII, nigdy z przecinkiem ani znakiem równości. Powtórzone klucze są nieprawidłowe, ale puste człony listy są wprost dozwolone — przecinek pozostawiony na końcu przez pośrednika, który usunął wpis, wciąż daje prawidłowy nagłówek. Osobna sprawa: dostawcy powinni propagować co najmniej 512 znaków połączonego nagłówka; gdy muszą przyciąć, żeby zmieścić się w tym budżecie, jako pierwsze powinny wypadać wpisy dłuższe niż 128 znaków — dlatego dane rozgadanego dostawcy znikają wcześniej niż dane oszczędnego.

Dobre praktyki pracy z Trace Context

Sprawdzaj flagi operacją bitową AND

Należy pisać flags & 0x01 zamiast flags == 0x01. Sześć z ośmiu bitów jest zarezerwowanych na przyszłość, a porównanie na równość zacznie błędnie raportować próbkowane ślady w chwili, gdy którykolwiek z nich pojawi się w praktyce.

Traktuj identyfikator z samych zer jak zepsuty potok

To nie jest pusta wartość, którą można tolerować. Warto odrzucić nagłówek i odszukać komponent, który nie zainicjował swojego tracera albo wstrzykuje wartość zastępczą.

Przy wyzerowanym bicie sampled patrz wyżej w łańcuchu

Samplery dziedziczące decyzję po rodzicu propagują wybór wywołującego. Gdy brakuje śladów, najpierw trzeba ustalić, która usługa przysyła span nadrzędny z wyłączonym próbkowaniem, a dopiero potem audytować własną konfigurację.

Utrzymuj tracestate krótkim

Limit 32 członów to twarda granica gramatyczna — po jego przekroczeniu nagłówek jest nieprawidłowy. Osobna sprawa: gwarantowana propagacja obejmuje tylko 512 znaków połączonego nagłówka, a przycinanie usuwa najpierw wpisy dłuższe niż 128 znaków. Cokolwiek ma przetrwać długi łańcuch wywołań, nie należy do tracestate.

Nigdy nie zapisuj trace ID jako liczby w JavaScripcie

128-bitowy trace ID, a nawet 64-bitowy identyfikator Datadog przekraczają Number.MAX_SAFE_INTEGER. Trzeba trzymać je jako łańcuchy i przeliczać przez BigInt, gdy potrzebna jest arytmetyka, inaczej ostatnie cyfry po cichu się popsują.

Najczęściej zadawane pytania o dekoder traceparent