تتبع استدعاءات أدوات Claude Agent باستخدام OpenTelemetry (2026)

عندما يتصرف وكيل استدعاء الأدوات (tool-calling agent) بشكل خاطئ — يتم اختيار أداة خاطئة، أو يستغرق الاستدعاء ثماني ثوانٍ، أو تكلف العملية عشرة أضعاف ما توقعت — فإن تتبع console.log البسيط نادراً ما يخبرك بأي خطوة تسببت في ذلك. تمنح الاصطلاحات الدلالية (semantic conventions) لـ GenAI في OpenTelemetry عمليات تشغيل الوكيل شكلاً قياسياً: span واحد لكل استدعاء نموذج، وspan واحد لكل استدعاء أداة، وspan أب واحد للعملية بأكملها، وجميعها تحمل نفس أسماء سمات gen_ai.* بغض النظر عن النموذج أو الإطار الذي تستخدمه¹.

ملخص

ستقوم ببناء وكيل TypeScript صغير يستدعي Claude API باستخدام أداة واحدة، وتغلفه بثلاثة أنواع من spans الخاصة بـ OpenTelemetry: invoke_agent للعملية بأكملها، وchat لكل استدعاء نموذج، وexecute_tool لكل استدعاء أداة. يحمل كل span سمات gen_ai.* الحالية — بما في ذلك gen_ai.provider.name، التي حلت محل gen_ai.system بهدوء في المواصفات² — ويقوم SpanProcessor مخصص بقراءة سمات استخدام التوكنات (token-usage) مباشرة من الـ spans المنتهية لطباعة تكلفة دولارية حقيقية لكل استدعاء. لا يوجد جامع (collector)، لا Docker، ولا SDK من مورد — فقط @opentelemetry/API ومصدرر console. بيئة التشغيل: @anthropic-ai/sdk@0.111.0، @opentelemetry/API@1.9.1، Node.js 20+. وقت البناء: 25-30 دقيقة.

ما ستتعلمه

• كيف تقوم الاصطلاحات الدلالية لـ OpenTelemetry GenAI بتسمية الـ spans والسمات لاستدعاءات النماذج، وتشغيل الوكلاء، واستدعاءات الأدوات¹
• كيفية تسجيل Node tracer provider وطباعة spans حقيقية في الـ console بدون أي بنية تحتية خارجية
• كيفية تغليف حلقة استدعاء أدوات Claude في spans من نوع invoke_agent وchat وexecute_tool التي تتداخل بشكل صحيح عبر حدود await
• كيفية قراءة سمات gen_ai.usage.* من span منتهي وتحويلها إلى تكلفة دولارية فعلية باستخدام SpanProcessor مخصص
• لماذا لم تعد gen_ai.system هي السمة المطلوب استخدامها، وما الذي حل محلها
• كيفية توجيه هذه الـ spans نفسها إلى backend حقيقي بمجرد انتهائك من مرحلة النمذجة الأولية (prototyping)

المتطلبات الأساسية

• Node.js 20 أو أحدث (Node 24 هو خط Active LTS الحالي وقت كتابة هذا المقال؛ انتقل Node 22 إلى Maintenance LTS في 2025-10-21)³
• @anthropic-ai/sdk@0.111.0 — الـ SDK الأساسي لـ Messages API، وليس Agent SDK؛ هذه حلقة استدعاء أدوات بسيطة بدون تدخل إطار عمل للوكلاء⁴
• @opentelemetry/API@1.9.1، و@opentelemetry/sdk-trace-node@2.9.0، و@opentelemetry/resources@2.9.0⁴
• TypeScript 7.0.2 مع تفعيل strict وnoUncheckedIndexedAccess⁴
• مفتاح ANTHROPIC_API_KEY إذا كنت تريد تشغيل هذا على API المباشر — الكود أدناه تم التحقق من أنواعه مقابل الـ SDK الحقيقي ومنطق التتبع فيه تم تنفيذه من البداية للنهاية مقابل استجابات وهمية (stubbed responses)؛ انظر إلى قسم التحقق لمعرفة ما تم تشغيله بالضبط وما لم يتم تشغيله

لماذا لا نكتفي بتسجيل استدعاءات الأدوات؟

سطر السجل (log line) يخبرك بأن شيئاً ما حدث. أما الـ span فيخبرك أين يقع بالنسبة لكل شيء آخر — أي استدعاء نموذج تبعه، وأي استدعاء أداة تسبب فيه، وكم استغرق من الوقت بالنسبة للأب الخاص به، وكيف يتصل بـ spans من أجزاء أخرى من نظامك إذا كنت تستخدم OpenTelemetry لأي شيء آخر.

تقوم الاصطلاحات الدلالية لـ GenAI بتوحيد هذا الشكل خصيصاً لعمل LLM: الـ span من نوع chat يحمل دائماً gen_ai.request.model وgen_ai.usage.output_tokens بنفس أسماء السمات سواء كنت تستدعي Claude أو GPT أو Gemini، لذا فإن لوحة التحكم (dashboard) المبنية لمورد واحد تعمل غالباً مع الآخرين أيضاً¹. هذه القابلية للنقل هي الهدف الأساسي من الاصطلاح الدلالي — ولهذا السبب توجد المواصفات كمفردات مشتركة بدلاً من أن يخترع كل مورد لغته الخاصة.

لا تزال اصطلاحات GenAI في تطور — حتى منتصف عام 2026 ظلت في حالة "تطوير" (Development) بشكل عام، رغم أن الـ spans الأساسية لاستدعاءات العميل خرجت من الحالة التجريبية في وقت سابق من العام⁵. توقع استمرار تغير أسماء السمات في الهوامش؛ تم التحقق من هذا البرنامج التعليمي مقابل المواصفات المنشورة في 2026-07-15، وقد حدث تغيير واحد بالفعل يربك الكثير من البرامج التعليمية الحالية: gen_ai.system اختفت من السجل الحالي، وحلت محلها gen_ai.provider.name².

الخطوة 1: إعداد المشروع

mkdir claude-agent-tracing && cd claude-agent-tracing
npm init -y
npm install @anthropic-ai/sdk@0.111.0 @opentelemetry/API@1.9.1 \
  @opentelemetry/sdk-trace-node@2.9.0 @opentelemetry/resources@2.9.0
npm install -D TypeScript@7.0.2 tsx@4.23.1 @types/node@26.1.1

أضف "type": "module" إلى package.json — كل حزمة هنا تشحن بصيغة ESM، وخلط أنظمة الوحدات (module systems) هو المكان الذي تفشل فيه معظم هذه البرامج التعليمية. ثم أنشئ tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  }
}

إعداد moduleResolution: "bundler" هو ما يجعل الأمر بسيطاً — فهو يسمح لـ tsc بحل صادرات حزمة الـ SDK بنفس الطريقة التي يفعلها tsx عند التشغيل، لذا فإن ما يتم التحقق من نوعه هو ما يعمل فعلياً.

الخطوة 2: تسجيل tracer

// tracing.ts
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-node";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { trace } from "@opentelemetry/API";
import { CostLoggingProcessor } from "./cost-processor.js";

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    "service.name": "weather-agent",
  }),
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()),
    new CostLoggingProcessor(),
  ],
});

provider.register();

export const tracer = trace.getTracer("weather-agent", "1.0.0");

يقوم SimpleSpanProcessor بتصدير كل span في اللحظة التي ينتهي فيها، وهو ما تريده لعرض توضيحي في الـ terminal — في بيئة الإنتاج ستستخدم BatchSpanProcessor ومصدر OTLP بدلاً من ذلك، وهو بالضبط شكل خط الأنابيب القائم على Collector6. يأخذ spanProcessors مصفوفة، لذا لا شيء يمنعك من تشغيل مصدر console ومعالج مخصص جنباً إلى جنب — هذا هو دور CostLoggingProcessor، وستقوم بكتابته في الخطوة 5.

الخطوة 3: بناء حلقة الوكيل المزودة بأدوات القياس

يمتلك الوكيل أداة واحدة (get_weather، تعيد بيانات ثابتة حتى لا يعتمد البرنامج التعليمي على API حقيقي للطقس) وحلقة تستدعي Claude، وتنفذ أي استدعاءات أدوات يطلبها، وتكرر ذلك حتى يتوقف Claude عن الطلب. كل طبقة تحصل على الـ span الخاص بها:

// agent.ts
import Anthropic from "@anthropic-ai/sdk";
import type { MessageParam, Tool } from "@anthropic-ai/sdk/resources/messages";
import { tracer } from "./tracing.js";
import { SpanStatusCode, type Span } from "@opentelemetry/API";
import { randomUUID } from "node:crypto";

const MODEL = "claude-sonnet-5";

const WEATHER_TOOL: Tool = {
  name: "get_weather",
  description: "Get the current weather for a city.",
  input_schema: {
    type: "object",
    properties: {
      city: { type: "string", description: "City name, e.g. 'Cairo'" },
    },
    required: ["city"],
  },
};

function getWeather(city: string): string {
  const fixtures: Record<string, string> = {
    Cairo: "32°C, clear skies",
    Dublin: "14°C, light rain",
  };
  return fixtures[city] ?? `${city}: 21°C, partly cloudy`;
}

/** Runs each tool call inside its own `execute_tool {name}` span. */
function runTool(name: string, id: string, input: unknown): string {
  return tracer.startActiveSpan(`execute_tool ${name}`, (span: Span) => {
    span.setAttribute("gen_ai.operation.name", "execute_tool");
    span.setAttribute("gen_ai.tool.name", name);
    span.setAttribute("gen_ai.tool.call.id", id);
    try {
      const city = (input as { city: string }).city;
      const result = getWeather(city);
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

/** Runs one model turn inside a `chat {model}` span with GenAI attributes. */
async function chatTurn(
  client: Anthropic,
  messages: MessageParam[],
): Promise<Anthropic.Message> {
  return tracer.startActiveSpan(`chat ${MODEL}`, async (span: Span) => {
    span.setAttribute("gen_ai.operation.name", "chat");
    span.setAttribute("gen_ai.provider.name", "anthropic");
    span.setAttribute("gen_ai.request.model", MODEL);
    try {
      const response = await client.messages.create({
        model: MODEL,
        max_tokens: 1024,
        tools: [WEATHER_TOOL],
        messages,
      });

      span.setAttribute("gen_ai.response.model", response.model);
      span.setAttribute("gen_ai.usage.input_tokens", response.usage.input_tokens);
      span.setAttribute("gen_ai.usage.output_tokens", response.usage.output_tokens);
      if (response.usage.cache_creation_input_tokens) {
        span.setAttribute(
          "gen_ai.usage.cache_creation.input_tokens",
          response.usage.cache_creation_input_tokens,
        );
      }
      if (response.usage.cache_read_input_tokens) {
        span.setAttribute(
          "gen_ai.usage.cache_read.input_tokens",
          response.usage.cache_read_input_tokens,
        );
      }
      if (response.stop_reason) {
        span.setAttribute("gen_ai.response.finish_reasons", [response.stop_reason]);
      }
      span.setStatus({ code: SpanStatusCode.OK });
      return response;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

/** Root span for the whole agent turn — one or more chat turns plus any tool calls. */
export async function runAgent(client: Anthropic, userMessage: string): Promise<string> {
  return tracer.startActiveSpan(`invoke_agent weather-assistant`, async (root: Span) => {
    root.setAttribute("gen_ai.operation.name", "invoke_agent");
    root.setAttribute("gen_ai.agent.name", "weather-assistant");
    root.setAttribute("gen_ai.conversation.id", randomUUID());

    const messages: MessageParam[] = [{ role: "user", content: userMessage }];

    try {
      for (let turn = 0; turn < 4; turn++) {
        const response = await chatTurn(client, messages);
        messages.push({ role: "assistant", content: response.content });

        if (response.stop_reason !== "tool_use") {
          const text = response.content
            .filter((b): b is Anthropic.TextBlock => b.type === "text")
            .map((b) => b.text)
            .join("\n");
          root.setStatus({ code: SpanStatusCode.OK });
          return text;
        }

        const toolResults: Anthropic.ToolResultBlockParam[] = [];
        for (const block of response.content) {
          if (block.type === "tool_use") {
            const result = runTool(block.name, block.id, block.input);
            toolResults.push({
              type: "tool_result",
              tool_use_id: block.id,
              content: result,
            });
          }
        }
        messages.push({ role: "user", content: toolResults });
      }
      throw new Error("Agent did not finish within the turn budget");
    } catch (err) {
      root.recordException(err as Error);
      root.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      root.end();
    }
  });
}

هناك تفصيلان يستحقان الذكر. أولاً، tracer.startActiveSpan يأخذ callback غير متزامن (async) هنا، ولا يزال التداخل يعمل بشكل صحيح عبر كل await — حيث يقوم مدير السياق في Node بنشر الـ span النشط من خلال AsyncLocalStorage، لذا فإن الـ span من نوع chat الذي يبدأ داخل callback الخاص بـ runAgent، والـ span من نوع execute_tool الذي يبدأ داخل حلقة بعد ذلك، كلاهما يلتقطان الأب الصحيح تلقائياً. أنت لا تمرر span أو كائن سياق (context object) يدوياً أبداً.

ثانياً، كل اسم لسمة (attribute) في الـ span هنا هو عبارة عن سلسلة نصية بسيطة — "gen_ai.usage.input_tokens"، وليس ثابتاً مستورداً. يمكنك استيراد ثوابت مثل ATTR_GEN_AI_USAGE_INPUT_TOKENS من @opentelemetry/semantic-conventions@1.43.0، ولكن فقط من المسار الفرعي /incubating — فحص الحزمة مباشرة يظهر أن ثوابت GenAI موجودة في experimental_attributes، ويتم إعادة تصديرها من خلال @opentelemetry/semantic-conventions/incubating، وليس من خلال التصدير الرئيسي المستقر للحزمة⁷. كتابة السلاسل النصية يدوياً تتجنب الاعتماد على استيراد مُصنف كـ "قيد التطوير" (incubating) لـ 13 اسماً من السمات التي يحددها هذا البرنامج التعليمي، رغم أن الثوابت خيار معقول إذا كنت تفضل أن يقوم tsc باكتشاف أي خطأ إملائي في اسم السمة بدلاً منك.

الخطوة 4: التشغيل وقراءة التتبع (trace)

قم بتوصيل نقطة دخول حقيقية:

// index.ts
import "./tracing.js"; // side-effecting import: register the tracer FIRST
import Anthropic from "@anthropic-ai/sdk";
import { runAgent } from "./agent.js";

const client = new Anthropic();

const answer = await runAgent(client, "What's the weather in Cairo?");
console.log("\n=== Final answer ===");
console.log(answer);

export ANTHROPIC_API_KEY=sk-ant-...
npx tsx index.ts

لاحظ ترتيب الاستيراد في index.ts: يأتي ./tracing.js أولاً، في سطر مستقل، رغم أن agent.ts يستورده أيضاً. من الناحية التقنية، تقوم مواصفات ES module بتقييم التبعيات قبل تشغيل الكود العلوي للوحدة المستوردة، لذا فإن الاستيراد غير المباشر من agent.ts سيسجل الـ tracer في الوقت المناسب في كلتا الحالتين — لكن الاعتماد على ذلك أمر هش بمجرد أن يقوم شخص ما بإعادة ترتيب الاستيرادات أثناء إعادة هيكلة الكود (refactor). استيراد tracing.js بشكل صريح، وأولاً، في كل نقطة دخول هو النمط الذي لا يتسبب في أعطال لاحقاً.

بما أن خط الإنتاج الآلي هذا لا يملك ANTHROPIC_API_KEY فعال، فقد تم التحقق من منطق التتبع نفسه مقابل عميل وهمي (stubbed client) يعيد استجابات تجريبية مصممة تماماً مثل الـ API الحقيقي — نفس حقول usage و stop_reason و content التي يعيدها الـ SDK الحقيقي. إليك مخرجات الكونسول الحقيقية من ذلك التشغيل، والتي تظهر span واحد من نوع chat، و span واحد من نوع execute_tool، و span ثانٍ من نوع chat، والـ span الرئيسي invoke_agent، بترتيب انتهائها:

{
  name: 'chat claude-sonnet-5',
  traceId: 'bfae7c5f1f4e5ca6ccd96ed8c6eb1c2a',
  attributes: {
    'gen_ai.operation.name': 'chat',
    'gen_ai.provider.name': 'anthropic',
    'gen_ai.request.model': 'claude-sonnet-5',
    'gen_ai.response.model': 'claude-sonnet-5',
    'gen_ai.usage.input_tokens': 512,
    'gen_ai.usage.output_tokens': 41,
    'gen_ai.response.finish_reasons': [ 'tool_use' ]
  },
  status: { code: 1 }
}
{
  name: 'execute_tool get_weather',
  traceId: 'bfae7c5f1f4e5ca6ccd96ed8c6eb1c2a',
  attributes: {
    'gen_ai.operation.name': 'execute_tool',
    'gen_ai.tool.name': 'get_weather',
    'gen_ai.tool.call.id': 'toolu_01demo'
  },
  status: { code: 1 }
}
{
  name: 'chat claude-sonnet-5',
  traceId: 'bfae7c5f1f4e5ca6ccd96ed8c6eb1c2a',
  attributes: {
    'gen_ai.operation.name': 'chat',
    'gen_ai.provider.name': 'anthropic',
    'gen_ai.request.model': 'claude-sonnet-5',
    'gen_ai.response.model': 'claude-sonnet-5',
    'gen_ai.usage.input_tokens': 568,
    'gen_ai.usage.output_tokens': 19,
    'gen_ai.response.finish_reasons': [ 'end_turn' ]
  },
  status: { code: 1 }
}
{
  name: 'invoke_agent weather-assistant',
  traceId: 'bfae7c5f1f4e5ca6ccd96ed8c6eb1c2a',
  attributes: {
    'gen_ai.operation.name': 'invoke_agent',
    'gen_ai.agent.name': 'weather-assistant',
    'gen_ai.conversation.id': '1d6f4098-6663-4f30-a0a4-70f06fba80c4'
  },
  status: { code: 1 }
}

=== Final answer ===
It's 32°C and clear in Cairo right now.

(تم اختصار الحقول التي تهمنا في هذا الشرح — مخرجات ConsoleSpanExporter الحقيقية تتضمن أيضاً spanId و parentSpanContext و duration و instrumentationScope في كل span.) تشترك جميع الـ spans الأربعة في traceId واحد، وهو ما يجعل هذا "تتبعاً" (trace) بدلاً من أربعة أسطر سجلات غير مرتبطة — و parentSpanContext.spanId في كل من الـ spans الثلاثة التابعة (الظاهرة في المخرجات غير المختصرة) يطابق الـ id الخاص بـ span الـ invoke_agent، مما يؤكد أن التداخل من الخطوة 3 يعمل فعلياً عند التشغيل، وليس فقط في هيكل الكود. status: { code: 1 } تعني SpanStatusCode.OK — القيمة 0 تعني غير محدد، و 2 تعني خطأ.

الخطوة 5: تحويل سمات الـ span إلى قيمة مالية

الفائدة من وضع gen_ai.usage.* على الـ span بدلاً من مجرد تسجيلها بشكل منفصل: أي معالج (processor) لاحق — سواء كان هذا المعالج أو معالج OTel Collector حقيقي — يمكنه حساب تكلفة المكالمة دون لمس كود التطبيق الخاص بك على الإطلاق.

// cost-processor.ts
import type { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-node";

// Verified against platform.claude.com/docs/en/about-claude/pricing (2026-07-15).
// USD per million tokens. Sonnet 5 is in its introductory pricing window
// through 2026-08-31; it becomes $3 / $15 after that.
const PRICE_PER_MTOK: Record<string, { input: number; output: number }> = {
  "claude-sonnet-5": { input: 2, output: 10 },
  "claude-opus-4-8": { input: 5, output: 25 },
  "claude-haiku-4-5": { input: 1, output: 5 },
};

export class CostLoggingProcessor implements SpanProcessor {
  onStart(): void {}

  onEnd(span: ReadableSpan): void {
    if (!span.name.startsWith("chat ")) return;

    const model = span.attributes["gen_ai.response.model"] as string | undefined;
    const inputTokens = span.attributes["gen_ai.usage.input_tokens"] as number | undefined;
    const outputTokens = span.attributes["gen_ai.usage.output_tokens"] as number | undefined;
    const rates = model ? PRICE_PER_MTOK[model] : undefined;
    if (!rates || inputTokens === undefined || outputTokens === undefined) return;

    const cost =
      (inputTokens / 1_000_000) * rates.input + (outputTokens / 1_000_000) * rates.output;

    console.log(
      `[cost] ${span.name}: ${inputTokens} in + ${outputTokens} out tokens ≈ $${cost.toFixed(6)}`,
    );
  }

  shutdown(): Promise<void> {
    return Promise.resolve();
  }

  forceFlush(): Promise<void> {
    return Promise.resolve();
  }
}

قم بتشغيل نفس العرض التوضيحي مرة أخرى وستظهر سطران إضافيان، يتم حسابهما مباشرة عند انتهاء كل span من نوع chat:

[cost] chat claude-sonnet-5: 512 in + 41 out tokens ≈ $0.001434
[cost] chat claude-sonnet-5: 568 in + 19 out tokens ≈ $0.001326

هذا يمثل تقريباً 0.0028 دولار للتشغيل الكامل المكون من جولتين — عملية بحث واحدة عن الطقس، وإجابة نهائية واحدة. هناك نقطة هامة يجب معرفتها قبل أن تتفاجأ بفاتورة حقيقية: بمجرد أن تكون tools غير فارغة، يضيف Claude عبئاً ثابتاً من توكنات "مطالبة النظام" (system-prompt) لكل مكالمة — من 354 إلى 474 توكن لـ Sonnet 5، اعتماداً على tool_choice⁴. هذا غير مرئي في المطالبة التي كتبتها، ولكنه حقيقي، ويتم فوترته، وهو بالضبط نوع الأشياء التي لن تلاحظها إلا من خلال مراقبة gen_ai.usage.input_tokens على الـ span بدلاً من تقدير عدد التوكنات من نص رسالتك الخاص.

التحقق

ما تم تشغيله فعلياً: ملفات tracing.ts و cost-processor.ts و agent.ts و index.ts — الملفات الأربعة معاً، بما يطابق ما هو معروض أعلاه، بالإضافة إلى نظام اختبار داخلي خامس يقوم بعمل stub لـ client.messages.create — تم فحص أنواعها باستخدام tsc --noEmit (strict: true, noUncheckedIndexedAccess: true) مقابل حزم @anthropic-ai/sdk@0.111.0 و @opentelemetry/* الحقيقية والمثبتة بالإصدارات المحددة في المتطلبات الأساسية. لم تظهر أي أخطاء.

تم تنفيذ منطق التتبع نفسه عبر tsx مقابل client.messages.create وهمي يعيد استجابتين تجريبيتين مصممتين مثل الـ API الحقيقي (نفس حقول usage و stop_reason و content) — هذا هو التشغيل الذي جاءت منه مخرجات الكونسول في الخطوة 4، وتم إعادة إنتاجها حرفياً، بما في ذلك حسابات التكلفة التي تم التحقق منها يدوياً: 512 / 1e6 × 2 + 41 / 1e6 × 10 = 0.001434، 568 / 1e6 × 2 + 19 / 1e6 × 10 = 0.001326.

ما لم يتم تشغيله: مكالمة client.messages.create() الحية مقابل API Claude الحقيقي في index.ts. خط إنتاج الكتابة الآلي هذا لا يملك ANTHROPIC_API_KEY. إذا كنت تملك واحداً، فإن تشغيل npx tsx index.ts يجب أن يتصرف بشكل مطابق لمخرجات الخطوة 4 — نفس شكل الـ span، ونفس أسماء السمات — مع أعداد توكنات حقيقية واستجابة نموذج حقيقية بدلاً من البيانات التجريبية.

استكشاف الأخطاء وإصلاحها

تُطبع الـ spans بدون أب (parent)، رغم أنك استدعيتها داخل runAgent. من المحتمل أنك تستدعي tracer.startSpan() بدلاً من tracer.startActiveSpan(). تقوم startSpan بإنشاء span ولكنها لا تجعله السياق النشط، لذا فإن أي شيء يبدأ بعدها لن يجد أباً ليرتبط به. تقوم startActiveSpan بكلا الأمرين في استدعاء واحد — استخدمها إلا إذا كان لديك سبب محدد لعدم القيام بذلك.

الـ span من نوع chat يفتقد لـ gen_ai.usage.* تماماً. تأكد من أنك تقرأ response.usage، وليس شيئاً من استجابة HTTP الخام — نوع Message في الـ SDK يقوم بالفعل بتحليل usage.input_tokens و usage.output_tokens كأرقام، لذا إذا كانت قيمتها undefined، فمن المحتمل أن كائن الاستجابة نفسه ليس هو ما تعتقده (على سبيل المثال، خطأ تم التقاطه ومعاملته كاستجابة).

أسطر التكلفة لا تُطبع أبداً. يتم تفعيل CostLoggingProcessor.onEnd فقط للـ spans التي تبدأ باسم chat * — إذا قمت بتغيير اسم الـ span، فقم بتحديث فحص startsWith أيضاً. تأكد أيضاً من أن المعالج مسجل بالفعل: تأخذ spanProcessors في NodeTracerProvider مصفوفة، ونسيان إضافة معالجك المخصص بجانب console exporter هو طريقة سهلة لفقدانه بصمت (لا يوجد خطأ، فقط لا تظهر أسطر التكلفة).

الـ spans من نوع execute_tool تتداخل تحت الـ span الخاطئ من نوع chat، أو لا تتداخل على الإطلاق. هذا يعني عادةً أن استدعاء الأداة يتم إطلاقه من خارج حلقة for في runAgent — على سبيل المثال، في Promise.all التي تشغل أدوات متعددة دون تغليف كل واحدة منها في استدعاء tracer.startActiveSpan خاص بها من داخل السياق النشط. يحتاج كل استدعاء أداة إلى بدء الـ span الخاص به بينما لا يزال سياق الأب نشطاً في السلسلة غير المتزامنة (async chain) الحالية.