مراقبة Claude Agent SDK باستخدام OpenTelemetry (٢٠٢٦)

[Alex]: أهلاً بكم من جديد في البودكاست الذكي من نيرد ليفل تك! أنا أليكس، مروض الكود المقيم وخبير OpenTelemetry. [Jamie]: وأنا جيمي، شريكتكم في التقديم الفضولية التي لا تزال تعتقد أن "telemetry" تبدو كشيء تستخدمه ناسا لتتبع الأقمار الصناعية المفقودة. [تضحك] ولكن مهلاً، اليوم سنغوص في تفاصيل شيء أكثر روعة—مراقبة Claude Agent SDK باستخدام OpenTelemetry! [Alex]: هذا صحيح! إذا كنت قد تساءلت يوماً كيف ترى فعلياً ما تفعله وكلاء Claude في الخلفية—أو إذا كنت تريد فقط لوحات بيانات أفضل لتعرضها على مديرك—فأنت في المكان الصحيح. [Jamie]: حسناً يا أليكس، هيئ لنا المشهد: ما هي القابلية للمراقبة (observability) في عالم وكلاء الذكاء الاصطناعي، ولماذا يجب أن يهتم أي شخص بها؟ [Alex]: سؤال رائع يا جيمي. القابلية للمراقبة هي أساساً فن "الرؤية من الداخل" في الكود الخاص بك—معرفة ما يفعله وكلاؤك، وكم يكلفونك، وأين يختبئ التأخير (latency). تخيلي الأمر وكأنكِ تملكين نظارات أشعة سينية لمسارات الذكاء الاصطناعي الخاصة بكِ. [Jamie]: أوه، مثلما أحاول إصلاح ثلاجتي الذكية وأتمنى لو تخبرني ببساطة ما المشكلة بدلاً من وميض أضواء عشوائية في وجهي؟ [Alex]: بالضبط! باستثناء أنكِ هنا، بدلاً من الأضواء الوامضة، ستحصلين على آثار (traces)، وسجلات (logs)، ومقاييس (metrics)—كل ذلك بفضل سحر OpenTelemetry. واليوم، نركز على التتبع (tracing): تتبع كل خطوة يتخذها وكيل Claude، من طلبات النموذج إلى استدعاءات الأدوات، وصولاً إلى الـ hooks. [Jamie]: إذاً، التتبع يشبه إلى حد ما وصفاً تفصيلياً لقصة حياة الوكيل الخاص بي؟ [Alex]: أصبتِ! ومع Claude Agent SDK، يمكنكِ الآن تصدير كل ذلك كآثار OpenTelemetry. ولكن—وهنا المفاجأة—التتبع يكون معطلاً بشكل افتراضي ويحتاج إلى بعض "المصافحات السرية" لتفعيله. [Jamie]: أوه، مصافحات سرية! أخبرني، ماذا أحتاج؟ [Alex]: تحتاجين إلى ضبط متغيرين للبيئة: `CLAUDE_CODE_ENABLE_TELEMETRY=١` لتشغيل المفتاح الرئيسي، و `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=١` لأن التتبع لا يزال في المرحلة التجريبية (beta). بعد ذلك، وجهي `OTEL_TRACES_EXPORTER` إلى نقطة نهاية المجمع (collector endpoint) الخاصة بكِ. هذا هو المكان الذي تُرسل إليه الآثار لعرضها. [Jamie]: وكل هذا بلغة Node.js، صحيح؟ لأننا نعيش في المستقبل؟ [Alex]: بالتأكيد! الـ SDK مصمم لـ Node.js 18 وما فوق، ولكن تم اختباره حتى Node 22.22.3. إنه أساساً "تسلا" الـ SDKs الخاصة بالوكلاء—أنيق، سريع، ولكن من الأفضل أن تملكي الكابلات الصحيحة. [Jamie]: [تضحك] إذاً إذا أردت رؤية ما يفعله الوكيل الخاص بي، كيف يبدو ذلك فعلياً؟ هل نتحدث عن جدار من JSON؟ لوحة بيانات جميلة؟ أم... المزيد من الأضواء الوامضة؟ [Alex]: [يضحك] من الناحية المثالية، لوحة بيانات جميلة! ولكن يمكنكِ البدء ببساطة: فقط قومي بتشغيل خادم HTTP محلي يطبع تلك الآثار بتنسيق JSON قابل للقراءة. الأمر يشبه إلقاء نظرة على مذكرات الوكيل—لا حاجة لخلفية تجارية (backend). [Jamie]: انتظر، هل يمكنني حقاً فعل ذلك دون دفع مبالغ لـ Jaeger أو أي أداة مؤسسية؟ [Alex]: بكل تأكيد! بالنسبة للمطورين ذوي الميزانية المحدودة، سيفي سكريبت Node.js بالغرض باستخدام وحدة HTTP المدمجة في Node. فقط تذكري استخدام بروتوكول `httpjson`—وإلا ستجدين نفسكِ تحدقين في كتل ثنائية (binary blobs)، ولا أحد يريد ذلك. [Jamie]: حسناً، اشرح لي ما الذي يتم تتبعه فعلياً. ماذا يوجد في "شجرة النطاقات" (span tree) التي تستمر في ذكرها؟ [Alex]: ملاحظة جيدة! عندما تقومين بتشغيل وكيل Claude مع تفعيل التتبع، تصبح كل دورة للوكيل عبارة عن نطاق جذر (root span) يسمى `claude_code.interaction`. وتحته، تحصلين على نطاقات فرعية (child spans) لكل طلب نموذج (`claude_code.llm_request`)، ولكل استدعاء أداة (`claude_code.tool`)، وإذا كنتِ تشعرين بالمغامرة، تنفيذات الـ hooks (`claude_code.hook`). [Jamie]: انتظر، لذا إذا كان الوكلاء يطلبون حالة الطقس ويستدعون أداة، سأرى كل ذلك كنطاقات منفصلة؟ [Alex]: بالضبط. تخيليها كشجرة عائلة، ولكن بدلاً من "الجد بوب"، لديكِ "tool.execution". وكل نطاق يأتي محملاً بالسمات: النموذج المستخدم، المدة، عدد التوكنز، التكلفة، وأكثر من ذلك. [Jamie]: وهذا مفيد لأن...؟ [Alex]: لأن إحصائيات الملخص في الـ SDK تخبركِ فقط بالتكلفة الإجمالية أو المدة. ولكن ماذا لو أردتِ معرفة أي استدعاء أداة استغرق وقتاً أطول، أو ما إذا كان النموذج قد اضطر لإعادة المحاولة قبل النجاح؟ النطاقات تمنحكِ هذه الدقة. [Jamie]: فهمت—لذا الأمر ليس مجرد "كلفني الوكيل ٣ سنتات"، بل "استدعاء أداة الطقس كلف سنتاً واحداً واستغرق ثانيتين لأن برلين غائمة وبطيئة". [Alex]: [يضحك] تماماً! وإذا كانت لوحات البيانات الخاصة بكِ معدة بشكل صحيح، يمكنكِ تتبع اختناقات الأداء أو ارتفاعات التكلفة في وقت قصير جداً. [Jamie]: سمعت شيئاً عن الاصطلاحات الدلالية (semantic conventions) لـ OpenTelemetry GenAI. هل تتبع آثار Claude SDK تلك القواعد؟ [Alex]: آه، سؤال المليون دولار. الإجابة هي: نوعاً ما. أسماء النطاقات—مثل `claude_code.interaction`—هي أسماء خاصة بشركة Anthropic، وليست الأسماء القياسية لـ GenAI. ولكن، هناك مجموعة من السمات في تلك النطاقات—مثل `gen_ai.system` و `gen_ai.request.model` و `gen_ai.response.id`—متوافقة مع مواصفات GenAI. [Jamie]: لذا، إذا كانت الخلفية (backend) الخاصة بي تبحث عن نطاقات GenAI هذه بالاسم، فقد ترتبك؟ [Alex]: بالضبط. إذا كنتِ تصممين لوحة البيانات بناءً على أسماء النطاقات وحدها، فستفقدينها. ولكن إذا صممتِها بناءً على سمات GenAI تلك، ستجدين ما تحتاجينه. الأمر يشبه البحث عن التفاح من خلال لونه، وليس من خلال الملصق الموجود على القشرة. [Jamie]: [تضحك] وأراهن أن الملصقات تكون دائماً قديمة على أي حال. [Alex]: دائماً. في الواقع، إحدى السمات—`gen_ai.system`—تم تغيير اسمها في أحدث مواصفات GenAI إلى `gen_ai.provider.name` ولكن وثائق Anthropic لم تواكب ذلك بعد. تأكدي دائماً مما تتوقعه الخلفية الخاصة بكِ! [Jamie]: حسناً، آخر سؤال ملح: إذا أردت تتبع منطق التطبيق الخاص بي ورؤية وكيل Claude كجزء من التتبع العام، هل هذا ممكن؟ [Alex]: نعم! إذا كنتِ تستخدمين OpenTelemetry بالفعل في تطبيقكِ، يمكنكِ تغليف استدعاء `query()` الخاص بالوكيل داخل النطاق الخاص بكِ. سيقوم الـ SDK بنقل سياق التتبع (trace context)، لذا ستظهر نطاقات الوكيل كأطفال لتتبع تطبيقكِ الرئيسي. الأمر يشبه إضافة مغامرات وكيلكِ إلى ألبوم صور عائلة تطبيقكِ. [Jamie]: أحببت ذلك! لذا، باختصار: قومي بتفعيل المفاتيح الصحيحة، وجهزي بيئتكِ، ويمكنكِ الرؤية داخل وكلاء Claude كما لم تفعلي من قبل. لا مزيد من الطيران الأعمى! [Alex]: بالضبط. وإذا تعثرتِ يوماً، تذكري فقط: قومي دائماً بنشر `...process.env` عند إعداد بيئتكِ. وإلا، قد يفقد وكيلكِ مفاتيحه، ومحفظته، ووصول API كلها في وقت واحد. [Jamie]: ليس يوماً جيداً أبداً عندما تفقد مفتاح API الخاص بكِ. [تضحك] حسناً، انتهت حلقة اليوم من البودكاست الذكي من نيرد ليفل تك! إذا أعجبكم هذا الغوص العميق، اشتركوا واتركوا لنا تقييماً—وأخبرونا عما تريدون منا أن نكون "نيردي" بشأنه في المرة القادمة. [Alex]: شكراً لاستماعكم! انطلقوا وقوموا بتركيب أدوات القياس في كل شيء—وكلاؤكم سيشكرونكم. [تتلاشى موسيقى الخاتمة]