سمات OpenTelemetry gen_ai: 60 سيتم إيقاف دعمها في 2026

كل سمة gen_ai.* في @opentelemetry/semantic-conventions أصبحت مهجورة (deprecated) بدءاً من الإصدار v1.42.0. لقد قمت بمراجعة جميع الثوابت الـ 60 عبر ستة إصدارات: 8 منها كانت مجرد تغيير في المسميات، و2 تم حذفهما تماماً، بينما حافظت الـ 50 الأخرى على نفس قيمة السلسلة النصية (string value) بالضبط وتغير فقط المستودع (repository) الذي يملكها.

ملخص

تحذيرات opentelemetry gen_ai attributes deprecated التي تظهر في المحرر الخاص بك هي في الغالب مجرد ضوضاء، ولكن ليس بشكل كامل.

في 2026-06-12، قام إصدار semantic-conventions v1.42.0 بجعل مساحة الأسماء GenAI بالكامل مهجورة ونقلها إلى مستودع مخصص.¹ وتبع ذلك حزمة npm في 2026-07-06.

لقد سحبت ستة إصدارات منشورة من الحزمة وحسبت علامات الهجر (deprecation tags). القفزة كانت مفاجئة: 10 ثوابت مهجورة في الإصدار 1.41.1، ثم 60 في الإصدار 1.42.0.

10 فقط من تلك الـ 60 تمثل مشكلة حقيقية. ثماني سمات تم تغيير مسمياتها واثنتان تم حذفهما دون بديل. أما الـ 50 الأخرى فهي تصدر نفس السلسلة النصية التي كانت تصدرها دائماً.

الجزء المربك هو: حتى تاريخ 2026-09-24 لا توجد حزمة بديلة على npm أو PyPI للانتقال إليها. يخبرك إشعار الهجر بالذهاب إلى مكان لم يتم إطلاقه بعد.

ما ستتعلمه

• ما الذي تغير بالضبط في semantic-conventions v1.42.0، مقتبساً من ملاحظات الإصدار
• عدد حالات الهجر المقاسة عبر ستة إصدارات منشورة على npm
• أي 8 سمات gen_ai.* تم تغيير مسمياتها، وأي 2 تم حذفهما
• لماذا لا تحتاج الـ 50 حالة هجر الأخرى إلى أي تغيير في الكود على الإطلاق
• أنه لا تزال لا توجد حزمة بديلة للاستيراد منها
• لماذا لا يحذرك tsc --strict من أي من هذا
• سكربت يمكنك تشغيله لمراجعة الإصدار المثبت لديك

ماذا حدث فعلياً في v1.42.0

تم نقل الاصطلاحات الدلالية (semantic conventions) الخاصة بـ gen_ai من المستودع الأساسي لـ OpenTelemetry إلى مستودع GenAI مخصص، وتم وضع علامة "مهجور" على كل ما ترك خلفه. تدرج ملاحظات الإصدار v1.42.0 هذا تحت بند "التغييرات الجوهرية" (Breaking changes).¹

نص الإصدار محدد بشأن النطاق:

جميع سمات gen_ai.* والمقاييس والأحداث والـ spans التي تم تعريفها سابقاً تحت model/gen-ai/ و model/openai/ و model/mcp/ (والموثقة تحت docs/gen-ai/) أصبحت مهجورة في هذا المستودع وانتقلت إلى مستودع OpenTelemetry GenAI semantic conventions.

لاحظ وجود model/mcp/ في تلك القائمة. اصطلاحات Model Context Protocol انتقلت في نفس الـ commit، لذا فإن MCP tool spans هي جزء من نفس عملية الانتقال مثل العميل (agent) الذي يستدعيها.

موقع التوثيق يؤكد ذلك. كل صفحة تحت /docs/specs/semconv/gen-ai/ تظهر الآن بالعنوان "Moved: Generative AI semantic conventions" ومعها بنر يقول أن الصفحة "لم تعد مدعومة في هذا المستودع".²

يصف المستودع الجديد نفسه بأنه يوسع الاصطلاحات الأساسية باصطلاحات خاصة بـ GenAI، باستخدام Weaver لإدارة التبعية بينهما.³ فصل مجال سريع التطور عن مستودع يلتزم بمعايير استقرار صارمة هو مقايضة مبررة.

التكلفة هي أن الحزمة الأساسية تشحن الآن 60 ثابتاً تشير جميعها إلى مكان آخر.

عدد حالات الهجر المقاسة، إصداراً تلو الآخر

لقد قمت بتنزيل ستة إصدارات منشورة من @opentelemetry/semantic-conventions من npm، وقمت بتحليل build/src/experimental_attributes.d.ts، وحسبت كتل JSDoc التي تحمل علامة @deprecated مباشرة فوق ثابت gen_ai.* مُصدّر.

version   total  deprecated  live
1.34.0       38           6    32
1.37.0       42          10    32
1.40.0       56          10    46
1.41.1       60          10    50
1.42.0       60          60     0
1.43.0       60          60     0

هناك أمران بارزان.

نما مساحة الأسماء (namespace) بسرعة ثم توقفت. فقد انتقلت من 38 سمة إلى 60 سمة بين الإصدارين 1.34.0 و 1.41.1، ثم استقرت — لأن العمل الجديد بعد الإصدار 1.42.0 يتم في المستودع الآخر، وليس هنا.

أما عملية الإلغاء (deprecation) فهي بمثابة منحدر حاد وليست تدريجية. فقد تم إلغاء عشرة ثوابت عبر عدة إصدارات بالطريقة المعتادة. ثم تم إلغاء جميع الـ 60 ثابتًا في إصدار واحد.

تواريخ نشر الحزم من سجل npm، للإصدارات المذكورة أعلاه: 1.40.0 في 2026-02-26، و 1.41.1 في 2026-05-12، و 1.42.0 في 2026-07-06، و 1.43.0 في 2026-07-09. لا تزال علامة latest في npm تشير إلى 1.43.0، بينما يظهر في تنقل موقع المواصفات بالفعل "Semantic conventions 1.44.0" — مما يعني أن حزمة JavaScript تتأخر عن المواصفات بإصدار واحد.²

أي سمات gen_ai تم تغيير اسمها فعليًا

هناك ثماني سمات gen_ai.* لها بدائل مسمى، لذا فهذه هي السمات التي تتطلب تغييرًا في الكود. توضح علامة @deprecated الموجودة على كل ثابت البديل الخاص به، مما يجعل استخراج القائمة عملية آلية بدلاً من أن تكون مجرد تقدير شخصي:

تشترك الصفوف الخمسة الخاصة بـ OpenAI في نمط يستحق الملاحظة. ثلاثة منها تتخلى عن البادئة gen_ai. تمامًا وتنتقل إلى مساحة أسماء openai. في المستوى الأعلى. أي لوحة تحكم تقوم بالتصفية بناءً على gen_ai.* ستتوقف بصمت عن رؤية هذه الحقول بمجرد تحديث مكتبة القياس (instrumentation library).

تغيير gen_ai.system إلى gen_ai.provider.name هو التغيير الأكثر احتمالاً للتسبب في مشاكل، لأن gen_ai.system هو الحقل الذي تستخدمه للتجميع عندما تريد تفصيل التكلفة أو زمن الاستجابة حسب مورد النموذج.

هناك ملاحظة واحدة بشأن جميع الثمانية: الثوابت البديلة ملغاة أيضًا. يحمل gen_ai.provider.name إشعار نقل خاص به في الإصدار 1.43.0، وكذلك الحال بالنسبة لـ gen_ai.usage.input_tokens و gen_ai.usage.output_tokens. أنت تقوم بالانتقال إلى اسم صحيح ولكنه لم يعد مدعومًا في هذه الحزمة.

السمتان اللتان تمت إزالتهما دون وجود بديل لهما

يحمل ثابتان علامة مختلفة: "تمت الإزالة، لا يوجد بديل في الوقت الحالي."

• gen_ai.prompt
• gen_ai.completion

كانت هذه حقول prompt و completion المسطحة والكاملة. نقلت الاصطلاحات التقاط الرسائل إلى سمات gen_ai.input.messages و gen_ai.output.messages المهيكلة، والتي ظهرت لأول مرة في الحزمة في الإصدار 1.37.0 جنبًا إلى جنب مع gen_ai.provider.name و gen_ai.system_instructions.

تعامل مع هذا كعملية إزالة وليس تغيير اسم. كانت السمات القديمة عبارة عن سلاسل نصية واحدة؛ أما الجديدة فهي قوائم رسائل مهيكلة، والتقاط المحتوى اختياري. نسخ قيمة من واحدة إلى الأخرى لا يعتبر عملية انتقال (migration).

لماذا لا يحتاج 50 من أصل 60 من عمليات الإلغاء إلى تغيير في الكود

حافظت الـ 50 سمة المتبقية على قيمها النصية بدقة؛ فقط المستودع الذي يحددها هو الذي تغير. ولا يذكر وسم @deprecated الخاص بها أي شيء عن بديل — فقط "نُقلت إلى مستودع OpenTelemetry GenAI semantic conventions."

هذا يغطي كامل مفردات العميل (agent): gen_ai.agent.id، و gen_ai.agent.name، و gen_ai.agent.description، و gen_ai.agent.version، و gen_ai.conversation.id، و gen_ai.tool.name، و gen_ai.tool.call.id، و gen_ai.tool.call.arguments، و gen_ai.tool.call.result، و gen_ai.tool.definitions، والبقية.

الحسبة تكتمل: 8 تم تغيير أسمائهم + 2 تم حذفهم + 50 تم نقلهم = 60.

لذا، إذا كنت تستخدم gen_ai.agent.name اليوم، فإن تنسيق البيانات المرسلة لا يتغير. وستظل استعلامات الخلفية (backend queries) متطابقة. ما ستفقده هو وجود ثابت (constant) مدعوم لاستيراده، لأن الحزمة الأساسية لن تكون المكان الذي تعيش فيه هذه الأسماء مستقبلاً.

لغة Python في نفس الموقف. إصدار PyPI الحالي، opentelemetry-semantic-conventions 0.65b0، يحدد 52 ثابتاً من نوع gen_ai.* في _incubating/attributes/gen_ai_attributes.py، وجميع الـ 52 يحملون إشعار إيقاف دعم (deprecation notice) يشير إلى نفس عملية النقل.

هل توجد حزمة بديلة لـ GenAI semantic conventions؟

لا — حتى تاريخ 2026-09-24 لم أتمكن من العثور على حزمة GenAI semantic conventions منشورة بواسطة OpenTelemetry سواء على npm أو PyPI. لقد تحققت من ستة أسماء محتملة على npm واسمين على PyPI؛ وجميعها أعطت نتيجة 404. البحث في سجل npm عن "semantic-conventions genai" لا يعيد سوى حزم من جهات خارجية.

مستودع GenAI نفسه نشط ولكن لم يتم إصدار حزم منه: 601 عملية commit، و 136 مشكلة مفتوحة، و 40 طلب سحب (pull requests) مفتوح، وقسم إصدارات (Releases) فارغ.³

هذه ليست مجرد فجوة JavaScript. هناك مشكلة في opentelemetry-rust توضح الأمر ببساطة:

لا يوجد حالياً أي مسار عملي يمكن اتباعه (على سبيل المثال، لا توجد crate جديدة في Rust تعرض الاصطلاحات الدلالية المنفصلة).

رد أحد المطورين المسؤولين: "سأتحقق من الأمر وأعود بخطة."⁴

هناك نسخة أكثر حدة من هذه المشكلة في ملاحظات الإصدار نفسها. الإصدار v1.42.0 يوجه: "يجب على أدوات القياس (Instrumentations) التي تتبع اصطلاحات المستودع الجديد الرجوع إليه للحصول على schema_url المقابل للاستخدام."¹ ملف README الخاص بالمستودع الجديد يحتوي على قسم "Schema URL"، ومحتواه حالياً هو TODO.³

هل اصطلاحات OpenTelemetry GenAI الدلالية مستقرة؟

لا. كل ثابت gen_ai.* في حزمة JavaScript موجود في experimental_attributes، ولا يمكن الوصول إليه إلا من خلال نقطة الدخول /incubating. نقطة الدخول الرئيسية للحزمة لا تصدر أيًا منها.

لقد تحققت من ذلك في كل إصدار قمت بتحميله، من 1.27.0 إلى 1.43.0: لم تترقَّ سمة واحدة من نوع gen_ai.* إلى المجموعة المستقرة في أي منها.

النتيجة العملية: يمكن أن يتغير الاسم في إصدار فرعي (minor release). وهذا ما حدث بالضبط مع gen_ai.system.

هل لا تزال سمات gen_ai الموقوفة عن الدعم تعمل؟

نعم، وهذا هو الفخ — إيقاف الدعم لا يتسبب في فشل عملية البناء (build). لقد قمت بتثبيت @opentelemetry/semantic-conventions@1.43.0 مع TypeScript 5.9.3، واستوردت ثابتاً موقوف الدعم، وقمت بالتجميع باستخدام strict: true و module: nodenext:

npx tsc -p .
# exit code 0, no diagnostics

قيم وقت التشغيل (runtime values) لم تتأثر:

gen_ai.operation.name | gen_ai.agent.name

يظهر TypeScript @deprecated كاقتراح من المحرر — خط يتوسط النص في الـ IDE الخاص بك — وليس كخطأ في المترجم (compiler error). إذا لم يفتح أحد في الفريق هذا الملف، ولم يكن تكوين الـ lint لديك يحتوي على قاعدة للـ deprecation، فإن عملية الانتقال بالكامل ستكون غير مرئية لـ CI.

هذا هو مبرر إجراء التدقيق بشكل متعمد بدلاً من انتظار اعتراض عملية البناء (build).

دقق في إصدارك المثبت (pinned version) الخاص بك

يأخذ هذا السكريبت قائمة من الإصدارات، ويقوم بتعبئة كل إصدار من npm، ويعد الثوابت المهجورة (deprecated) من نوع gen_ai.*. وقد أنتج هذا السكريبت الجدول المذكور سابقاً في هذا المنشور.

// semconv-genai-audit.mjs
// Usage: node semconv-genai-audit.mjs 1.41.1 1.42.0 1.43.0
import { mkdtemp, readFile } from 'node:fs/promises';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const run = promisify(execFile);
const versions = process.argv.slice(2);
const FILE = 'package/build/src/experimental_attributes.d.ts';
// one JSDoc block immediately followed by one exported gen_ai constant
const BLOCK =
  /\/\*\*((?:(?!\*\/)[\s\S])*?)\*\/\s*export declare const \w+:\s*"(gen_ai\.[^"]+)"/g;

console.log('version   total  deprecated  live');
for (const v of versions) {
  const dir = await mkdtemp(join(tmpdir(), 'semconv-'));
  await run('npm', ['pack', `@opentelemetry/semantic-conventions@${v}`, '--silent'], { cwd: dir });
  const [tgz] = (await run('ls', [dir])).stdout.trim().split('\n');
  await run('tar', ['xzf', join(dir, tgz), '-C', dir]);
  const src = await readFile(join(dir, FILE), 'utf8');

  let total = 0;
  let deprecated = 0;
  for (const [, doc] of src.matchAll(BLOCK)) {
    total++;
    if (/@deprecated/.test(doc)) deprecated++;
  }
  console.log(
    `${v.padEnd(9)} ${String(total).padStart(5)} ${String(deprecated).padStart(11)} ` +
      `${String(total - deprecated).padStart(5)}`
  );
}

تقوم مرحلة ثانية بتجميع حالات الـ deprecation حسب السبب، وهو ما تم من خلاله استخلاص تقسيم 8/2/50 المذكور أعلاه. انسخ كل شيء فوق سطر console.log('version ...') من السكريبت الأول، واحذف الحلقة (loop)، وأضف هذا:

// semconv-genai-reasons.mjs — reuses the imports, BLOCK regex and `src` from above
const renamed = [];
const removed = [];
const moved = [];

for (const [, doc, attr] of src.matchAll(BLOCK)) {
  const m = doc.match(/@deprecated\s+([^\n*]*)/);
  if (!m) continue;
  const reason = m[1].trim();
  const rename = reason.match(/^Replaced by `([^`]+)`/);

  if (/^Removed/.test(reason)) removed.push(attr);
  else if (rename) renamed.push([attr, rename[1]]);
  else moved.push(attr);
}

console.log(`renamed ${renamed.length}, removed ${removed.length}, moved ${moved.length}`);
for (const [from, to] of renamed) console.log(`  ${from}  ->  ${to}`);

كلا السكريبتين يقرآن تصريحات الأنواع (type declarations) فقط، لذا لا يحتاجان إلى مفتاح API ولا يقومان بأي استدعاءات للنماذج (model calls). قم بتشغيلهما على أي إصدار مثبت فعلياً في ملف الـ lockfile الخاص بك.

اتفاقيات الطرف الثالث تباعدت أكثر مما تعتقد

أثناء التدقيق، تحققت مما تصدره حزم اتفاقيات الموردين (vendor convention packages)، ووجدتها لا تتقارب مع أسماء OTel.

تحدد حزمة @traceloop/ai-semantic-conventions الإصدار 0.27.0 عدد 15 سلسلة نصية من نوع gen_ai.*. ولا يظهر أي من هذه الـ 15 في سجل OTel 1.43.0.

بعضها قريب جداً ولكنه لن يتطابق مع الاستعلام. فهي تكتب رموز التخزين المؤقت (cache tokens) كـ gen_ai.usage.cache_creation_input_tokens، بينما تحدد OTel gen_ai.usage.cache_creation.input_tokens — شرطات سفلية مقابل نقطة.

حقل رموز التفكير (reasoning token) لديها هو gen_ai.usage.reasoning_tokens؛ بينما في OTel هو gen_ai.usage.reasoning.output_tokens. كما تحدد مساحة اسم (namespace) مكونة من تسع سمات gen_ai.guardrail.* لا تحددها OTel على الإطلاق.

أما الموردان الآخران فقد ذهبا إلى أبعد من ذلك ولم يستخدما مساحة الاسم. حزمة @arizeai/openinference-semantic-conventions 2.12.0 وحزمة @langfuse/otel 5.11.1 لا تصدران أي سلاسل نصية من نوع gen_ai.* في حزم الاتفاقيات الخاصة بهما، مفضلتين مفرداتهما الخاصة.

لكي نكون دقيقين بشأن النطاق: هذه هي حزم الاتفاقيات الخاصة بالموردين، وليست كل حزمة instrumentation يشحنونها. لكن الاتجاه واضح بما يكفي. إذا كنت تقوم بتوحيد التتبعات (traces) من أكثر من مصدر واحد، فلا تفترض وجود مفردات مشتركة.

إذا كنت لا تزال في مرحلة إعداد تتبع الوكيل (agent tracing)، فإن آليات إصدار هذه الـ spans مغطاة في تتبع استدعاءات أدوات وكيل Claude باستخدام OpenTelemetry.

تكوين المصدر (exporter configuration) على مستوى SDK موجود في قابليّة ملاحظة Claude Agent SDK باستخدام OpenTelemetry، وجانب خط الأنابيب (pipeline) — تكوين الـ collector والمعالجات — موجود في درس تتبع OpenTelemetry Collector Node.js.

ماذا تفعل هذا الأسبوع

قم بالتدقيق بدلاً من react. قم بتشغيل السكريبت على إصدارك المثبت واحصل على قائمة ملموسة.

أصلح الـ 10 المهمة. ابحث (Grep) في الـ instrumentation الخاص بك عن الأسماء الثمانية التي تم تغييرها والاسمين اللذين تم حذفهما. هذا هو كل التغيير المطلوب في الكود.

ابحث في لوحات البيانات (dashboards) وقواعد التنبيه أيضاً، وليس فقط في الكود المصدري. فجانب الإصدار وجانب الاستعلام يتباعدان بشكل مستقل، والاستعلام المحفوظ الذي يقوم بتصفية gen_ai.system سيعود بصمت بدون نتائج بمجرد تحديث المكتبة.

اترك الـ 50 الأخرى وشأنها. تغيير استيراد ثابت لسمة لم تتغير قيمتها لن يفيدك في شيء وقد يعرضك لخطر الخطأ الإملائي.

لا تبحث عن الحزمة الجديدة. لا توجد حزمة بعد على npm أو PyPI. ثبت إصدار semconv الخاص بك، وحافظ على السلاسل النصية التي تصدرها بالفعل، وارجع للأمر عندما يضع مستودع GenAI علامة إصدار (release tag).

الخلاصة

العنوان العريض — "جميع سمات gen_ai الـ 60 أصبحت مهجورة" — يبدو وكأنه يتطلب عطلة نهاية أسبوع كاملة للهجرة. ولكن بالقياس الدقيق، هو تغيير في عشرة أسطر بالإضافة إلى عملية بحث (grep) في لوحة التحكم.

التكلفة الحقيقية تكمن في مكان آخر. الاتفاقيات التي تعتمد عليها إمكانية مراقبة الوكلاء (agent observability) تعيش الآن في مستودع بدون إصدار محدد، وبدون حزمة منشورة على npm أو PyPI، ومع وجود TODO حيث يجب أن يكون رابط الـ schema. المواصفات تخبر مؤلفي أدوات القياس (instrumentation authors) بالرجوع إلى رابط الـ schema هذا.

حتى يتم حل ذلك، التصرف الصادق هو تثبيت إصدارك، والاستمرار في إرسال النصوص التي ترسلها بالفعل، والتوقف عن التعامل مع الخط المشطوب في محررك وكأنه موعد نهائي.

قراءات ذات صلة

• تتبع استدعاءات أدوات Claude Agent باستخدام OpenTelemetry
• مراقبة Claude Agent SDK باستخدام OpenTelemetry
• دليل تتبع OpenTelemetry Collector لـ Node.js