---
title: "الفرق بين Trace ID وSpan ID من ترويسة traceparent حقيقية"
description: "معرّف التتبّع (Trace ID) يسمّي طلبًا واحدًا في كل خدمة يصل إليها، ولا يتغيّر. معرّف Span يسمّي خطوة واحدة، لذا تُنشئ كل خدمة معرّفًا جديدًا."
canonical: "https://logbrew.co/ar/guides/trace-id"
last_updated: "2026-11-21"
---

# الفرق بين Trace ID وSpan ID من ترويسة traceparent حقيقية

معرّف التتبّع (Trace ID) يسمّي طلبًا واحدًا في كل خدمة يصل إليها، ولا يتغيّر. معرّف Span يسمّي خطوة واحدة، لذا تُنشئ كل خدمة معرّفًا جديدًا.

اختُبر في 21 نوفمبر 2026 باستخدام Node.js 22.18.0 و@logbrew/node 0.1.30 وPython 3.13.9 وFastAPI 0.165.0 وuvicorn 0.54.0 وlogbrew-fastapi 0.1.14 وcurl 8.7.1 وlogbrew CLI 0.1.96

بقلم [Furkan Erday](https://github.com/furkanerday). Furkan Erday مؤسس LogBrew، ويبني LogBrew كل يوم باستخدام Claude Code وCodex.

Canonical: https://logbrew.co/ar/guides/trace-id

## ماذا فعلت كل ترويسة traceparent بالتتبّع

| الترويسة التي أرسلها curl | بقي معرّف التتبّع نفسه | السجلان يشتركان في معرّف تتبّع واحد |
| --- | --- | --- |
| صالحة، العلامات `01` | نعم | نعم |
| صالحة، العلامات `00` | نعم | نعم |
| معرّف تتبّع بأحرف كبيرة | نعم، بأحرف صغيرة | نعم |
| معرّف تتبّع كله أصفار | تتبّع جديد | نعم |
| الإصدار `ff` | تتبّع جديد | نعم |
| بلا ترويسة | تتبّع جديد | نعم |

6 طلبات إلى خدمة Node.js تستدعي خدمة FastAPI، باستخدام @logbrew/node 0.1.30 وlogbrew-fastapi 0.1.14.

## فكّ ترويسة traceparent

### قسّم الترويسة عند الشرطات

تحمل `traceparent` 4 حقول بالنظام الست عشري وبأحرف صغيرة، تفصل بينها `-`. وهي الإصدار، ومعرّف التتبّع، ومعرّف الأب، وعلامات التتبّع. هذه هي الترويسة التي أرسلها curl إلى خدمة `checkout` لدينا.

المخرجات

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
```

### اقرأ الإصدار

`00` هو الإصدار الوحيد في توصية W3C Trace Context، و`ff` غير صالح. عندما أرسلنا `ff` تجاهلت حزمتا SDK الترويسة وبدأتا تتبّعًا جديدًا.

### اقرأ معرّف التتبّع

الأحرف الـ32 التالية هي معرّف التتبّع `9095c7b7bf222836f82c2c415bc2bd65`، أي 16 بايت بالنظام الست عشري. يسمّي الطلب كله، وتمرّره كل خدمة دون تغيير. معرّف التتبّع الذي كله أصفار غير صالح.

### اقرأ معرّف الأب

الأحرف الـ16 التالية هي معرّف الأب `fe8e70882fecdf07`، أي 8 بايت بالنظام الست عشري. إنه معرّف Span الخاص بالمستدعي، لذا يتغيّر عند كل قفزة. معرّف الأب الذي كله أصفار غير صالح.

### اقرأ علامات التتبّع

آخر حرفين هما العلامات، وللبت 0 وحده معنى. `01` تعني أن المستدعي ربما سجّل التتبّع، و`00` تعني أنه لم يسجّله. حتى مع `00` أرسلت حزمتا SDK الـSpans الخاصة بهما، وعرض LogBrew التتبّع.

## مرّر التتبّع من Node.js إلى Python

### ثبّت حزمتي SDK

تعمل خدمة `checkout` على Node.js مع `@logbrew/node`. وهي تستدعي `payments`، وهو تطبيق FastAPI مع `logbrew-fastapi`. استخدم في كل منهما مفتاح خادم من مشروعك في LogBrew.

```bash
npm install @logbrew/sdk @logbrew/node
python3 -m pip install logbrew-sdk logbrew-fastapi
```

### غلّف خادم Node.js والاستدعاء الذي يجريه

تقرأ `withLogBrewHttpHandler()` الترويسة `traceparent` من كل طلب وتبدأ Span. وتبدأ `fetchWithLogBrewSpan()` Span فرعيًا للاستدعاء وتكتب `traceparent` جديدة بمعرّف ذلك الـSpan. يقرأ الغلاف المفتاح من `LOGBREW_SERVER_API_KEY`.

```bash
import { createServer } from "node:http";
import { fetchWithLogBrewSpan, withLogBrewHttpHandler } from "@logbrew/node";

const server = createServer(withLogBrewHttpHandler(async (req, res, logbrew) => {
  logbrew.client.log(`evt_checkout_${Date.now()}`, new Date().toISOString(), {
    message: "checkout started for order 1042",
    level: "info",
    logger: "checkout"
  });
  const reply = await fetchWithLogBrewSpan("http://127.0.0.1:28702/payments/1042", {
    method: "POST"
  }, {
    client: logbrew.client,
    trace: logbrew.trace,
    routeTemplate: "/payments/:orderId"
  });
  res.writeHead(reply.status, { "content-type": "application/json" });
  res.end(await reply.text());
}));

server.listen(28701, "127.0.0.1");
```

### أضف LogBrew إلى تطبيق FastAPI

تقرأ `init_logbrew()` الترويسة `traceparent` من كل طلب وتبدأ Span فرعيًا. ويضيف `logbrew.logging_handler` معرّف التتبّع ومعرّف Span الخاصين بالطلب إلى كل سجل.

```bash
import logging
import os

from fastapi import FastAPI
from logbrew_fastapi import init_logbrew

app = FastAPI()
logbrew = init_logbrew(
    app, api_key=os.environ["LOGBREW_SERVER_API_KEY"], service_name="payments"
)
logger = logging.getLogger("payments")
logger.setLevel(logging.INFO)
logger.addHandler(logbrew.logging_handler)


@app.post("/payments/{order_id}")
def authorize(order_id: str):
    logger.warning("card declined for order %s", order_id)
    return {"orderId": order_id, "status": "declined"}
```

## اعثر على تتبّع سطر في السجل

### أرسل طلبًا واحدًا عبر الخدمتين

أرسل curl ترويسة `traceparent`، كما يمكن أن يفعل متصفح أو بوابة أمام `checkout`. ومن دون الترويسة تبدأ `checkout` تتبّعًا جديدًا.

```bash
curl -X POST http://127.0.0.1:28701/checkout \
  -H 'traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01'
```

المخرجات

```text
{"orderId":"1042","status":"declined"}
```

### قارن الترويسة عند كل قفزة

طبعنا الترويسة في كل خدمة. احتفظت `checkout` بمعرّف التتبّع، ووضعت في معرّف الأب معرّف Span الاستدعاء الخاص بها، `1a95bcb4e3fcb3ce`. وقرأت `payments` تلك الترويسة وبدأت تحتها الـSpan `bc7e3f490d4a4d00`.

المخرجات

```text
checkout got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-fe8e70882fecdf07-01
checkout sent traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
payments got traceparent: 00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01
```

### اعثر على كل سجلات التتبّع

انسخ معرّف التتبّع من أي سطر في السجل ومرّره إلى `--trace`. أعادت واجهة سطر الأوامر سجل كل خدمة. وفي لوحة التحكم، الصق معرّف التتبّع في مربع البحث في السجلات.

```bash
logbrew read logs --project "<project_id>" --trace 9095c7b7bf222836f82c2c415bc2bd65
```

المخرجات

```text
Logs (2)
- warning card declined for order 1042 service=payments trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
- info checkout started for order 1042 service=checkout trace=9095c7b7bf222836f82c2c415bc2bd65 [unversioned / production]
```

### افتح التتبّع

يحتوي التتبّع على 3 Spans، منها 2 من `checkout` و1 من `payments`. وفي لوحة التحكم، الصق معرّف التتبّع في مربع البحث في الاستكشاف، ثم افتح التتبّع.

```bash
logbrew read trace 9095c7b7bf222836f82c2c415bc2bd65 --project "<project_id>"
```

المخرجات

```text
Trace 9095c7b7bf222836f82c2c415bc2bd65 spans=3 [unversioned / production]
- POST /payments/{order_id}
- POST /payments/:orderId
- POST /checkout
```

## ما رأيناه عندما اختبرناه

شغّلنا `checkout` على Node.js 22.18 مع @logbrew/node 0.1.30، و`payments` على Python 3.13.9 مع FastAPI 0.165.0 وuvicorn 0.54.0 وlogbrew-fastapi 0.1.14. وأرسلت الخدمتان إلى خادم LogBrew محلي. أرسل curl 6 طلبات إلى `checkout`، 5 منها بترويسة `traceparent` مختلفة، وواحد بلا ترويسة.

في كل طلب اشتركت سجلات الخدمتين في معرّف تتبّع واحد. عندما كانت الترويسة صالحة كان هو معرّف التتبّع الذي أرسله curl. وعندما كانت غير صالحة أو غائبة، بدأت `checkout` تتبّعًا جديدًا ومرّرته.

|  | `span_id` | `parent_span_id` |
| --- | --- | --- |
| طلب `checkout` | `5569d78d6d163d95` | `fe8e70882fecdf07` |
| استدعاء `checkout` لـ`payments` | `1a95bcb4e3fcb3ce` | `5569d78d6d163d95` |
| طلب `payments` | `bc7e3f490d4a4d00` | `1a95bcb4e3fcb3ce` |

- `checkout`
  - `level`: `info`
  - الرسالة: `checkout started for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `5569d78d6d163d95`
- `payments`
  - `level`: `warning`
  - الرسالة: `card declined for order 1042`
  - `trace_id`: `9095c7b7bf222836f82c2c415bc2bd65`
  - `span_id`: `bc7e3f490d4a4d00`

## الفرق بين Trace ID وSpan ID

معرّف التتبّع 16 بايت، يُكتب في 32 حرفًا بالنظام الست عشري. ومعرّف Span 8 بايتات، يُكتب في 16 حرفًا. وتعدّ مواصفة واجهة التتبّع البرمجية في OpenTelemetry المعرّفَ صالحًا فقط إذا كان بايت واحد منه على الأقل غير صفري، وتكتب كليهما بأحرف ست عشرية صغيرة.

في OpenTelemetry يحمل سياق Span معرّف التتبّع، ومعرّف Span، وعلامات التتبّع، وحالة التتبّع. تحمل `traceparent` أول 3 منها. وتحمل ترويسة `tracestate` حالة التتبّع، وهي قائمة تضم حتى 32 إدخالًا من المزوّدين. لا تكتب أيّ من حزمتي SDK من LogBrew الترويسة `tracestate`.

|  | معرّف التتبّع | معرّف Span |
| --- | --- | --- |
| عدد الأحرف الست عشرية | `32` | `16` |
| ثابت عند كل قفزة | نعم | لا |
| صالح إذا كان كله أصفارًا | لا | لا |

## عندما تكون الترويسة خاطئة

لا تسمح التوصية إلا بالأحرف الست عشرية الصغيرة، وتمنع الإصدار `ff` والمعرّفات التي كلها أصفار. وعلى الخدمة التي تتلقى ترويسة كهذه أن تتجاهلها وتبدأ تتبّعًا جديدًا. وقد فعلت حزمتا SDK ذلك مع `ff` ومع معرّف تتبّع أو معرّف أب كله أصفار.

قبلت حزمتا SDK معرّف تتبّع بأحرف كبيرة ومرّرتاه بأحرف صغيرة. أرسل أحرفًا صغيرة، لأن الخدمة الصارمة تبدأ تتبّعًا جديدًا بدلًا منه.

من دون ترويسة بدأت `checkout` تتبّعًا بالعلامات `01`، وبدأت `payments` تتبّعًا بالعلامات `00`. واحتفظ LogBrew بالتتبّعين.

| بقي معرّف التتبّع نفسه | `@logbrew/node` | `logbrew-fastapi` |
| --- | --- | --- |
| معرّف تتبّع بأحرف كبيرة | نعم | نعم |
| الإصدار `ff` | لا | لا |
| معرّف تتبّع كله أصفار | لا | لا |
| معرّف أب كله أصفار | لا | لا |

## أسئلة شائعة

### ما هو Trace ID؟

معرّف التتبّع (Trace ID) معرّف من 16 بايت، يُكتب في 32 حرفًا ست عشريًا صغيرًا. يسمّي طلبًا واحدًا في كل خدمة يصل إليها الطلب. وتمرّره كل خدمة في ترويسة `traceparent`.

### ما الفرق بين Trace ID وSpan ID؟

معرّف التتبّع هو نفسه في كل خدمات الطلب الواحد. ومعرّف Span يسمّي خطوة واحدة في خدمة واحدة. حصل طلبنا على معرّف تتبّع واحد و3 معرّفات Span.

### ما هي ترويسة traceparent؟

`traceparent` هي ترويسة HTTP في توصية W3C Trace Context. تحمل الإصدار، ومعرّف التتبّع، ومعرّف Span الخاص بالمستدعي، وعلامات التتبّع، كما في `00-9095c7b7bf222836f82c2c415bc2bd65-1a95bcb4e3fcb3ce-01`.

### ماذا يعني 01 في نهاية traceparent؟

`01` تضبط علامة sampled، أي أن المستدعي ربما سجّل التتبّع. و`00` تعني أنه لم يسجّله. مرّرت حزمتا SDK من LogBrew القيمتين كلتيهما، واحتفظ LogBrew بالتتبّع.

### كيف أعثر على كل السجلات التي لها معرّف التتبّع نفسه؟

شغّل `logbrew read logs --project "<project_id>" --trace <trace_id>`، أو الصق معرّف التتبّع في مربع البحث في السجلات في لوحة تحكم LogBrew. كل سجل تكتبه حزم SDK أثناء طلب يحمل معرّف التتبّع لذلك الطلب.

### هل ترويسة traceparent حساسة لحالة الأحرف؟

نعم. لا تسمح التوصية إلا بالأحرف الست عشرية الصغيرة. قبلت حزمتا SDK من LogBrew معرّف تتبّع بأحرف كبيرة وحوّلتاه إلى أحرف صغيرة، لكن الخدمة الصارمة تتجاهل الترويسة.

## اعثر على كل سجلات التتبّع ببحث واحد

تقرأ حزم SDK من LogBrew لـNode.js وFastAPI الترويسة `traceparent` وترسلها، ويحتفظ كل سجل بمعرّف التتبّع الخاص بطلبه. ابدأ بخطة مجانية سخية دون بطاقة.

[ابدأ مجانًا](https://logbrew.co/ar)

## المصادر

- [W3C Recommendation, Trace Context, 3.2 Traceparent Header](https://www.w3.org/TR/trace-context/#traceparent-header)
- [W3C Recommendation, Trace Context, 4.3 A traceparent is received](https://www.w3.org/TR/trace-context/#a-traceparent-is-received)
- [@logbrew/node on npm](https://www.npmjs.com/package/@logbrew/node)
- [LogBrewCo/sdk, logbrew-fastapi README](https://github.com/LogBrewCo/sdk/blob/main/python/logbrew_fastapi/README.md)

## إرشادات أخرى للوكلاء وPython وNode.js وReact

- [أضف خادم MCP إلى Claude Code وCodex](https://logbrew.co/ar/guides/mcp-server-claude-code-codex)
- [استخدم AGENTS.md في Claude Code وCodex](https://logbrew.co/ar/guides/agents-md)
- [أصلح خطأ Claude overloaded 529 وخطأ rate limit 429](https://logbrew.co/ar/guides/claude-overloaded-rate-limit-error)
- [إعداد Python logging بمستويات السجل الصحيحة والتقاط الاستثناءات](https://logbrew.co/ar/guides/python-logging)
- [التسجيل المنظّم بتنسيق سجل ومستويات سجل يمكنك البحث فيها حسب الحقل](https://logbrew.co/ar/guides/structured-logging)
- [إعداد السجلات في Node.js باستخدام Pino أو Winston دون أن تفقد أي خطأ](https://logbrew.co/ar/guides/node-logging)
- [أعدّ سجلات Django واحفظ تتبّع المكدّس لكل خطأ 500](https://logbrew.co/ar/guides/django-logging)
- [أعدّ سجلات FastAPI وعالج الأخطاء دون فقدان تتبّع المكدّس](https://logbrew.co/ar/guides/fastapi-logging)
- [أضف حدًّا للأخطاء في React وسجّل الأخطاء التي تفوته](https://logbrew.co/ar/guides/react-error-boundary)
- [أدلة للأخطاء والسجلات والتتبّعات والمقاييس والإصدارات](https://logbrew.co/ar/guides)
