در traceparent، شناسهٔ کل مسیر با شناسهٔ درخواستِ هر مرحله یکی نیست. چند سرویس می‌توانند trace-id مشترک داشته باشند، اما parent-id خروجی باید به عملیاتِ فرستنده مربوط شود. در تمرین این صفحه، سه سرویسِ فرضی A، B و C را با یک parser محدودِ نسخهٔ00 دنبال می‌کنیم. هیچ درخواست HTTP یا سامانهٔ tracing اجرا نمی‌شود؛ خروجی، دفترِ ساختگیِ رابطهٔ والد و فرزند است.
چهار خانهٔ header را جدا بخوانیم
Recommendation نسخهٔ ثابتِ W3C در ۲۳نوامبر۲۰۲۱، برای traceparent فیلدهای version، trace-id، parent-id و trace-flags را تعریف می‌کند. در نسخهٔ00، trace-id دارای۳۲ رقمِ hex کوچک و parent-id دارای۱۶ رقم است؛ هر کدام که تماماً صفر باشند نامعتبرند. flags هم دو رقمِ hex است. نامِ header با مقدارِ داخل آن فرق دارد؛ parser ما فقط value را می‌گیرد.
کد به قالبِ دقیقِ۵۵نویسه‌ایِ نسخهٔ00 محدود شده است. hex بزرگ، جداکنندهٔ نامناسب، طولِ اضافه و شناسهٔ صفر را رد می‌کند. نسخهٔff ممنوع است؛ نسخهٔ دیگری مانند01 در ابزار حاضر unsupported_version می‌گیرد. این برچسب، ادعای نامعتبر بودنِ همهٔ نسخه‌های آینده در استاندارد نیست.
سه سرویس، یک trace و سه own span
برای ساده‌بودنِ مشاهده، trace-id را با رقم‌های۱ و spanهای A، B و C را با تکرار a، b و c ساخته‌ایم. این‌ها شناسه‌های آموزشی و قطعی‌اند؛ مولدِ شناسهٔ تصادفی یا تضمینِ یکتاییِ واقعی نیستند. در شروعِ این مدل، A والدِ ورودی ندارد و own span خودش را برای خروجی به B می‌فرستد.
| سرویسِ فرضی | parent ورودی | own span | parent خروجی |
|---|---|---|---|
| A | ندارد؛ آغازِ fixture | aaaaaaaaaaaaaaaa | همان spanِ A |
| B | spanِ A | bbbbbbbbbbbbbbbb | spanِ B |
| C | spanِ B | cccccccccccccccc | در این fixture خروجی ندارد |
trace-id در دو headerِ A→B و B→C برابر است. اما parent-id دوم دیگر spanِ A نیست؛ B نباید فقط header ورودی را بدون تغییر به‌عنوان رابطهٔ عملیاتِ خودش کپی کند. برابریِ trace-id کمک می‌کند آن‌ها را به یک مسیر وصل کنیم؛ تغییر parent-id، نسبتِ مرحله‌ها را حفظ می‌کند.
parent-id همیشه root نیست
نامِ parent ممکن است این تصور را بسازد که فیلد همیشه به آغازِ کل جریان اشاره می‌کند. در این مثال، برای C والد همان B است و A جدِ آن مسیر است. اگر فقط یک correlation_id مشترک در همهٔ لاگ‌ها داشته باشیم، کنار هم قراردادنِ رخدادها ممکن است، ولی رابطهٔ دقیقِ این دو گام از آن عدد به‌تنهایی به‌دست نمی‌آید.
دفترِ سه‌مرحله‌ای در JSON، parent ورودی و own span و parent خروجی را صریح نگه می‌دارد. assertها بررسی می‌کنند own spanِ B با parent ورودی آن فرق دارد و parent ورودی C از خروجی B آمده است. فقط نمایشِ دو رشتهٔ شبیه به هم را نتیجهٔ موفق نمی‌نامیم.
sampled را با mask بخوانیم
flags یک bit field است. برای فهمیدنِ sampled، کد کم‌ارزش‌ترین بیت را با ANDِ۱ بررسی می‌کند. در دو آزمایشِ جدا،09 و01 هر دو آن بیت را دارند؛08 ندارد. مقایسهٔ کل عدد با۱ می‌توانست09 را اشتباه تفسیر کند. قالبِ header و معنای بیت باید جدا کنترل شوند.
این flag توصیه یا شاهدِ احتمالِ ثبتِ بیرون از header است؛ روشن‌بودنش تضمین نمی‌کند backend واقعاً trace را ذخیره کرده یا دادهٔ کامل در دسترس است. کدِ سازندهٔ خروجیِ ما فقط01یا00 تولید می‌کند و پردازشِ کاملِ همهٔ extensionها و tracestate را پیاده نمی‌کند.
قالب درست، مجوز نیست
شش ورودیِ ناسازگار یا پشتیبانی‌نشده واقعاً آزموده شده‌اند: trace صفر، parent صفر، hex بزرگ، طولِ اضافه، نسخهٔff و نسخهٔ01. این ردها را با آزمونِ امنیتِ کاملِ میزبان یکی نگیرید. headerِ درست‌قالب، هویتِ معتبرِ کاربر، اجازهٔ خواندن یا صحتِ عملیاتِ تجاری را اثبات نمی‌کند.
منبع W3C ورودِ دادهٔ شخصی و حساس به traceparent و tracestate را مجاز نمی‌داند. نمونه‌های این مقاله هیچ IP، نام، کلید یا متنِ مشتری ندارند. داشتنِ یک شناسهٔ بلندِ hex نباید بهانهٔ قراردادنِ محتوای خصوصی در آن باشد؛ سیاستِ نگهداری و عبور از مرزِ اعتماد به طراحیِ واقعی نیاز دارد.
جای این ابزار در بررسیِ اتصال
نسخهٔ اجرا Python۳٫۱۲٫۱۴ است و همهٔ تبدیلات فقط روی رشته‌های اصیل انجام می‌شوند. راهنمای ممیزیِ ایجنت اقدام، مجوز و نتیجه را دنبال می‌کند؛ قراردادِ خطای برنامه هم کدِ دامنه و correlation_id را تعریف می‌کند. traceparent جای هیچ‌کدام نیست.
اگر مسیرِ اتصال در راهکارهای اپرا چند مرحله دارد، نقاطِ عبور و شناسهٔ پیگیریِ مجاز را در نیازسنجی روشن کنید. این نوشته فعال‌بودنِ tracing در محصول یا امکانِ مشاهدهٔ دادهٔ سامانه‌های دیگر را اعلام نمی‌کند؛ تمرین کمک می‌کند «یک مسیر» را با «یک والد برای همهٔ گام‌ها» اشتباه نگیریم.
فایل تمرین و منبع
کد کامل تمرینِ محلی و کنترل‌های آن · نمونه‌های اصیل و نتیجهٔ اجرای واقعیِ همین کد
منابع در 2026-11-04 خوانده شدند؛ این تاریخ، تاریخ انتشار منبع نیست. مثال‌ها و فایل‌های این راهنما آموزشی و ساختهٔ تحریریه‌اند.