مراقبة وكيل البرمجة في المؤسسة: القياس عن بُعد وضوابط الحماية ولوحة المعلومات

مراقبة وكيل البرمجة (Claude Code وCodex وCursor): قياس OpenTelemetry الموثَّق وhooks للحماية ولوحة معلومات استخدام في Dynatrace.
Superviser un agent de code en entreprise : télémétrie, garde-fous et tableau de bord

مراقبة وكيل البرمجة مثل Claude Code أو Codex أو Cursor تصبح مسألة تشغيلية بمجرد أن تنتقل الأداة من جهاز مبادر واحد إلى أجهزة مئة مطوّر. فالوكيل ينفّذ أوامر shell ويعدّل الملفات ويستدعي خوادم MCP ويستهلك رموزًا (tokens) مدفوعة. ودون قياس عن بُعد (telemetry) لا يعرف فريق المنصة من يستخدمه ولا ما ينفّذه ولا كم يكلّف، ويكتشف الانحرافات عند وصول الفاتورة أو وقوع الحادثة.

الخبر الجيد: يوثّق الناشرون الثلاثة اليوم تصديرًا إلى OpenTelemetry وآلية hooks. والخبر السيئ: لا تغطي الأدوات الإشارات نفسها، ولا تُضبط في المكان نفسه، وليست قيمها الافتراضية واحدة في ما يخص البيانات الحساسة.

يقارن هذا الدليل ما هو موثَّق فعلًا، ويقترح بنية جمع مشتركة نحو Dynatrace SaaS أو Dynatrace Managed، ويقدّم استعلامات أول لوحة معلومات للاستخدام. القدرات المذكورة مأخوذة من وثائق الناشرين المطّلع عليها في أكتوبر 2026، وهي تتطور بسرعة.

مراقبة وكيل البرمجة: ما الذي يوثّقه كل ناشر؟

جلسة Codex CLI في طرفية: ترويسة تعرض النموذج ومجلد العمل، وطلب شرح قاعدة شيفرة، ثم خطة محدَّثة من خمس خطوات قابلة للتأشير
Source : github.com

تبدو جلسة وكيل البرمجة على هذا النحو: نموذج ومجلد عمل وطلب، ثم سلسلة من القرارات واستدعاءات الأدوات. وهذه السلسلة هي ما يجب جعله قابلًا للملاحظة.

Claude Code

  • الإشارات: مقاييس (منها claude_code.session.count وclaude_code.token.usage وclaude_code.cost.usage بالدولار الأمريكي وclaude_code.lines_of_code.count) وأحداث عبر بروتوكول السجلات (tool_decision وtool_result وapi_request وpermission_mode_changed وmcp_server_connection…). التتبعات في مرحلة بيتا وتتطلب CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 إضافةً إلى CLAUDE_CODE_ENABLE_TELEMETRY=1.
  • الإعداد المركزي: ملف الإعدادات المُدارة، /etc/claude-code/managed-settings.json على Linux. تُتجاهل متغيرات التصدير الموضوعة في ملف .claude/settings.json داخل مستودع: فلا يستطيع المستودع إعادة توجيه القياس عن بُعد.
  • البيانات الحساسة: محتوى الموجّهات (prompts) وتفاصيل الأدوات (أوامر Bash وأسماء خوادم MCP وأدواتها) ومحتوى النتائج معطّلة افتراضيًا (OTEL_LOG_USER_PROMPTS وOTEL_LOG_TOOL_DETAILS وOTEL_LOG_TOOL_CONTENT). ويُعد البريد الإلكتروني للمستخدم من السمات القياسية متى كان متاحًا.

Codex

  • الإشارات: أحداث سجلات (codex.tool_decision وcodex.tool_result وcodex.api_request وcodex.user_prompt…) ومقاييس مثل codex.tool.call وcodex.tool.call.duration_ms. توجد المفتاحان otel.trace_exporter وotel.metrics_exporter؛ وقيمة الثاني الافتراضية statsig.
  • الإعداد: قسم [otel] في ~/.codex/config.toml، وهو معطّل افتراضيًا؛ وفي المؤسسات طبقة مُدارة /etc/codex/managed_config.toml.
  • البيانات الحساسة: log_user_prompt = false افتراضيًا، فتكون الموجّهات محجوبة.

Cursor

  • الإشارات: تصدير OpenTelemetry مقصور على خطة Enterprise وينفَّذ من خوادم Cursor. مقاييس cursor.token.usage وcursor.tool.calls (مع cursor.tool.kind بقيمة builtin أو mcp) وcursor.cost.usage التي تُقدَّم كتقدير لا كفاتورة؛ وسجلات لاستدعاءات API والأخطاء والـ hooks.
  • الإعداد: Team Settings > OpenTelemetry Export. النقل عبر OTLP/HTTP protobuf فقط، إلى عنوان HTTPS عام؛ ويضيف Cursor /v1/metrics و/v1/logs.
  • البيانات الحساسة: عائلة conversation_content معطّلة افتراضيًا ولا تشمل اليوم سوى Cloud Agents وGrok Bot.

ما الذي نتتبعه وما الذي لا نتتبعه

ابدأ من أسئلة التشغيل لا من قائمة السمات:

  • الاعتماد: الجلسات لكل فريق ولكل أسبوع؛
  • التكلفة: الرموز والتكلفة التقديرية لكل فريق ولكل نموذج؛
  • الإجراءات: الأدوات المقبولة والمرفوضة، ومن رفضها (الإعداد أو hook أو المستخدم)؛
  • التصعيد: الانتقال إلى وضع صلاحيات أوسع؛
  • السلامة: أخطاء API واستدعاءات الأدوات الفاشلة.

لا حاجة إلى محتوى الموجّهات والنتائج للإجابة عن هذه الأسئلة. أبقِه معطّلًا، وأعلم الفرق بما يُجمع، واستخدم أسماء مستعارة للهوية إذا لم تحتج اللوحة إلى الاسم.

بنية جمع مشتركة

اجمع الأجهزة نحو مجمّع OpenTelemetry (Collector) مؤسسي يرشّح ويُثري ويصدّر إلى Dynatrace:

مخطط من وثائق OpenTelemetry: تطبيق مزوَّد بـ OpenTelemetry SDK يرسل بروتوكول OTLP إلى مجمّع OpenTelemetry Collector الذي يصدّر إلى نظام خلفي
Source : opentelemetry.io

قيدان في Dynatrace يوجّهان الإعدادات. واجهة OTLP API لا تقبل gRPC بل HTTP فقط. ويجب أن تكون المقاييس بنمط الفروق (delta temporality)، وهو الافتراضي في Claude Code وصيغة Cursor؛ والموضوع مفصَّل في مقالنا عن زمنية مقاييس OTLP.

الخطوة 1: Claude Code عبر الإعدادات المُدارة

مقتطفات من الوثائق: ملف managed-settings.json الخاص بـ Claude Code مع CLAUDE_CODE_ENABLE_TELEMETRY ومتغيرات OTEL_ للتصدير، ثم قسم [otel] في config.toml الخاص بـ Codex مع environment وexporter وlog_user_prompt

يستخدم مثال الوثائق gRPC نحو المجمّع، وهذا مناسب لأن المجمّع يترجم إلى HTTP. أما لبوابة HTTP:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel-gw.example.internal:4318",
    "OTEL_RESOURCE_ATTRIBUTES": "department=engineering,team.id=platform"
  }
}

عندما يُعرَّف OTEL_EXPORTER_OTLP_ENDPOINT في الإعدادات المُدارة، يزيل Claude Code عند الإقلاع نقاط النهاية الخاصة بكل إشارة التي عرّفها المطورون. ويضيف OTEL_RESOURCE_ATTRIBUTES الفريق إلى كل مقياس وكل حدث (أزواج clé=valeur مفصولة بفواصل ودون مسافات).

الخطوة 2: Codex، قسم [otel]

[otel]
environment = "prod"
log_user_prompt = false
exporter = { otlp-http = {
  endpoint = "https://otel-gw.example.internal:4318/v1/logs",
  protocol = "binary"
}}

انشره في /etc/codex/managed_config.toml ليسري على كل تشغيل.

الخطوة 3: Cursor، من وحدة تحكم الفريق

في Team Settings > OpenTelemetry Export: أنشئ الوجهة بعنوان URL الأساسي دون /v1 وترويسة مصادقة، ثم شغّل Test connection ثم Enable. ينطلق التصدير من خوادم Cursor، من عناوين IP مصدر ثابتة منشورة في الوثائق: يجب أن تكون بوابتك قابلة للوصول من الإنترنت مع TLS.

الخطوة 4: المجمّع نحو Dynatrace

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  attributes/pseudo:
    actions:
      - key: user.email
        action: hash
  batch: {}
exporters:
  otlphttp:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [attributes/pseudo, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [attributes/pseudo, batch]
      exporters: [otlphttp]

قيمة DT_ENDPOINT هي https://<env-id>.live.dynatrace.com/api/v2/otlp في SaaS وhttps://<votre-domaine>/e/<env-id>/api/v2/otlp في Managed. يحمل الرمز المميّز النطاقين metrics.ingest وlogs.ingest (وopenTelemetryTrace.ingest إن فعّلت التتبعات). الإعداد التفصيلي موجود في دليلنا لمجمّع OpenTelemetry نحو Dynatrace.

ضوابط الحماية عبر hooks

القياس عن بُعد يرصد، أما الـ hooks فتمنع. تتيح الأدوات الثلاث حدثًا قبل تنفيذ أي أمر:

  • Claude Code: الـ hook PreToolUse مع matcher (مثل Bash)؛ ورمز الخروج 2 يحجب استدعاء الأداة. وفي الإعدادات المُدارة يقصر allowManagedHooksOnly الـ hooks على تلك التي تعتمدها المؤسسة.
  • Codex: الـ hook PreToolUse؛ ويتم الرفض عبر permissionDecision: "deny" أو رمز الخروج 2. ويُضبط allow_managed_hooks_only = true في requirements.toml. وتحذّر الوثائق من أن خطأً أو مهلة منتهية أو ردًا مشوَّهًا قد يترك الأداة تمر.
  • Cursor: beforeShellExecution وbeforeMCPExecution في hooks.json؛ الرمز 2 يحجب، وبقية رموز الفشل تترك التنفيذ يمر (fail-open). وتوضع hooks المؤسسة في /etc/cursor/hooks.json على Linux.

احتفظ بالقاسم المشترك: الـ hook الذي ينهار ليس hook يحجب. لذلك راقب الـ hooks أيضًا: يُصدر Claude Code الحدث hook_execution_complete ويصدر Cursor الحدث cursor.hook.execution_complete. وبالنسبة إلى خوادم MCP التي تستدعيها هذه الوكلاء، راجع دليلنا عن عزل خوادم MCP من نوع STDIO.

لوحة معلومات الاستخدام في Dynatrace SaaS

ابدأ بمعاينة الشكل الفعلي للأحداث المستلَمة: fetch logs | filter isNotNull(event.name) | limit 20. أسماء السمات أدناه هي الواردة في وثائق Claude Code؛ تحقق منها في بيئتك.

// Coût estimé et requêtes par équipe, 7 jours
fetch logs, from: now() - 7d
| filter event.name == "api_request"
| summarize cout_usd = sum(toDouble(cost_usd)), requetes = count(), by: { team.id }

// Outils refusés, et par quelle source
fetch logs, from: now() - 7d
| filter event.name == "tool_decision" and decision == "reject"
| summarize refus = count(), by: { tool_name, source }

// Passages à un mode de permission plus large
fetch logs, from: now() - 7d
| filter event.name == "permission_mode_changed"
| summarize changements = count(), by: { from_mode, to_mode }

بالنسبة إلى مقاييس Cursor وCodex، تشير وثائق Dynatrace إلى أنه قد تُضاف لاحقة تلقائيًا إلى المفتاح (مثل .count للعدّاد): تحقق من المفتاح الدقيق قبل بناء بلاطة timeseries. أسس هذه الأوامر في بطاقتنا عن DQL: filter وsummarize وtimeseries.

يستقبل Dynatrace Managed المقاييس نفسها عبر OTLP API ويستكشفها بـ metric selector وData Explorer؛ أما استعلامات DQL على السجلات أعلاه فتتطلب Grail، أي Dynatrace SaaS.

كيف نتحقق من أن كل شيء يعمل

  1. Claude Code: شغّل جلسة؛ تشير الوثائق إلى أن claude_code.session.count تُصدَر عند البدء. وإذا كان التصدير للسجلات فقط، أرسل موجّهًا وابحث عن الحدث user_prompt.
  2. Codex: غيّر exporter مؤقتًا إلى otlp-http على جهاز اختبار وتحقق من وصول أحداث codex.api_request.
  3. Cursor: يتحقق الزر Test connection من العنوان والمصادقة؛ ثم يبدأ التصدير خلال دقيقة تقريبًا.
  4. في المجمّع: يعرض المصدِّر debug المضاف مؤقتًا كل دفعة مستلَمة.

أفضل الممارسات

  • إعداد مركزي (إعدادات مُدارة أو ملف مُدار أو وحدة تحكم الفريق)، لا إعداد لكل مستودع أبدًا.
  • المحتوى معطّل افتراضيًا؛ وتفعيله مؤقتًا وموثَّقًا لأغراض تحقيق.
  • سمة الفريق على كل إشارة لبناء لوحات لكل فريق دون هوية اسمية.
  • تنبيهات على الاتجاهات (التكلفة والرفض والتصعيد)، لا على كل حدث.
  • اختبار الـ hooks عند الفشل: تحقق مما يحدث عندما ينهار السكربت أو يتجاوز مهلته.

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

هل نحتاج إلى مجمّع Collector أم يمكن الإرسال مباشرة إلى Dynatrace؟

الإرسال المباشر ممكن إذا كانت الأداة تتحدث OTLP/HTTP وتقبل ترويسة المصادقة المطلوبة. لكن يبقى المجمّع موصى به: فهو يحوّل gRPC إلى HTTP ويخفي الهويات بأسماء مستعارة ويركّز رمز Dynatrace.

هل تتيح هذه البيانات قياس الإنتاجية؟

إنها تقيس الاستخدام (الجلسات والأسطر المعدَّلة وعمليات commit) لا القيمة المنتَجة. استعملها لإدارة السعة والتكلفة، لا لتقييم الأشخاص.

ما الفرق عن مراقبة وكيل ذكاء اصطناعي من تطويرنا؟

هنا يوفّر الناشر أدوات القياس: أنت تختار ما تفعّله لا ما يُصدَر. أما الوكيل الذي تطوّره بنفسك فتنطبق عليه اصطلاحات GenAI في OpenTelemetry، كما في دليلنا لمراقبة وكلاء MCP.

الخلاصة

تتلخص مراقبة وكيل البرمجة في المؤسسة في ثلاث خطوات: تفعيل القياس عن بُعد الذي يوثّقه الناشر من إعداد مركزي، وتمريره عبر مجمّع يحمي البيانات، ووضع hooks تُراقَب إخفاقاتها أيضًا. ابدأ بالاعتماد والتكلفة، ثم أضف الرفض والتصعيد، ثم نبّه على الاتجاهات.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لناشري الأدوات المذكورة. Dynatrace علامة تجارية لشركة Dynatrace LLC. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك. المصادر: مراقبة Claude Code والإعداد المتقدم لـ Codex وOpenTelemetry Export في Cursor؛ وتتطور هذه القدرات مع كل إصدار.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Empoisonnement d'outils MCP : le détecter avec les traces et les logs

تسميم أدوات MCP: كيف تكشفه بالتتبعات والسجلات

Next Post
Garde-fous agents IA en production : NeMo Guardrails, Llama Guard et OpenShell côté exploitation

ضوابط حماية وكلاء الذكاء الاصطناعي في الإنتاج: NeMo Guardrails وLlama Guard وOpenShell من منظور التشغيل

Related Posts