توزيع Microsoft OpenTelemetry

توزيعة Microsoft OpenTelemetry هي توزيعة موحدة لقابلية الرصد توفر تجربة انضمام واحدة لجمع الآثار والمقاييس والسجلات من التطبيقات الوكالية وغير الوكالية. يدعم قابلية الملاحظة لأجهزة Microsoft Agent 365، وMicrosoft Foundry، وAzure Monitor، وأي خلفية متوافقة مع بروتوكول OpenTelemetry Protocol (OTLP). تدعم التوزيعة .NET وNode.jsو Python، وتستبدل الإعدادات المجزأة عبر عدة مجموعات مراقبة باستلام استيرايد واحد واستدعاء تكوين واحد.

ملحوظة

إذا كنت تحتفظ بتكامل موجود يستخدم Agent 365 Observability SDK السابق، راجع وثائق SDK المتوقفة وأدلة الترحيل.

المزايا الرئيسية

توزيعة Microsoft OpenTelemetry توفر هذه الفوائد:

  • حزمة واحدة، واجهة برمجة تطبيقات واحدة: استبدال عدة حزم من المصدر والأجهزة باعتماد واحد.
  • دعم تعدد الخلفيات: إرسال القياسات أو البيانات إلى Azure Monitor، أو أي نقطة نهاية متوافقة مع بروتوكول OpenTelemetry (OTLP) مثل Datadog أو Grafana أو New Relic، و Microsoft Agent 365 في نفس الوقت.
  • التنفيذات المدمجة: استخدم التنفيذ التلقائي لبروتوكول HTTP، وقواعد البيانات، و Azure SDK (حزمة تطوير البرامج لأزور)، و دالات Azure، وغيرها بدون إعدادات إضافية.
  • القائم على المعايير: بناء على OpenTelemetry، إطار الرصد القياسي في الصناعة.
  • الحد الأدنى من النموذج التجريبي: أضف استيراد واحد واستدعاء وظيفة واحد إلى نقطة دخول التطبيق.

التثبيت والتكوين

توضح لك هذه الإرشادات كيفية إضافة قابلية الملاحظة إلى تطبيقك باستخدام Microsoft OpenTelemetry Distro. تقوم التوزيعة تلقائيًا بجمع الآثار والمقاييس والسجلات باستخدام أدوات القياس المدمجة، وتصدر البيانات إلى Azure Monitor أو أي نقطة نهاية لبروتوكول OpenTelemetry (OTLP)، أو Microsoft Agent 365.

تثبيت المكتبة

لبدء استخدام Microsoft OpenTelemetry Distro، قم بتثبيت المكتبة المناسبة للنظام الأساسي للتطوير باستخدام مدير حزم اللغة.

Prerequisites: Python 3.10 أو أحدث.

pip install microsoft-opentelemetry

الإعداد

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

افتراضيا، يُصدِّر الـ distro باستخدام المسار المفوض، والذي يتطلب الإذن المفوض Agent365.Observability.OtelWrite وموافقة المسؤول. الأمر a365 setup all لا يضبط تلك الصلاحية لوكلاء المخطط، لذا استخدم S2S مع محلل app-only لهؤلاء الوكلاء بدلًا من ذلك. يمكن لمثيل وكيل مسجل التصدير عبر مسار S2S دون إذن إمكانية المراقبة أو موافقة المسؤول.

استدعاء use_microsoft_opentelemetry() لتمكين إمكانية المراقبة.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

للحصول على دقة الرمز المميز المخصصة (بدلا من محلل الرمز المميز الافتراضي)، راجع محلل الرمز المميز اليدوي.

يمكنك تخصيص سلوك المصدر عن طريق تمرير الكوارس الاختيارية a365_* إلى use_microsoft_opentelemetry().

المعامل الوصف Default
a365_use_s2s_endpoint عندما True، يتم استخدام مسار نقطة النهاية بين الخدمات. استخدم مع محلّل الرموز المخصص للتطبيق فقط. False
a365_max_queue_size الحد الأقصى لحجم قائمة الانتظار لمعالج الدفعات. 2048
a365_scheduled_delay_ms التأخير بالمللي ثانية بين دفعات التصدير. 5000
a365_exporter_timeout_ms المهلة بالمللي ثانية لعملية التصدير. 30000
a365_max_export_batch_size الحد الأقصى لحجم الدفعة لعمليات التصدير. 512

نشر السياق

للحفاظ على إمكانية المراقبة عبر عمليات العامل 365 الموزعة، قم بنشر السياق. عند نشر السياق من خلال عواملك وخدماتك، فإنك تضمن ربط التتبعات والسجلات والمقاييس بشكل صحيح عبر دورة حياة الطلب بأكملها. هذا الترابط مطلوب لتجربة مراقبة كاملة وفعالة في Microsoft 365.

سمات الأمتعة

يستخدم BaggageBuilder لتعيين المعلومات السياقية التي تتدفق عبر جميع الامتدادات في الطلب. تنفذ مجموعة تطوير البرمجيات (SDK) عملية SpanProcessor تنسخ جميع إدخالات الأعباء غير الفارغة إلى المقاطع الجديدة دون الكتابة فوق السمات الموجودة.

from microsoft.opentelemetry.a365.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

لتعبئة BaggageBuilder تلقائيًا من TurnContext، استخدم populate المساعد في الحزمة microsoft-opentelemetry. يستخرج هذا المساعد تلقائيا تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من النشاط.

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

البرامج الوسيطة للأمتعة

إذا كان وكيلك يستخدم حزمة تكامل الاستضافة، فسجل البرامج الوسيطة للأمتعة لملء الأمتعة تلقائيا لكل طلب وارد. تزيل هذه الخطوة الحاجة إلى استدعاء BaggageBuilder يدويا في كل معالج نشاط.

في Python، قم بتسجيل البرامج الوسيطة للأمتعة من خلال ObservabilityHostingManager.configure() بدلا من مباشرة على المحول.

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

يتجنب الواجهة البرمجية الوسيطة إعداد المعلومات المصاحبة للردود غير المتزامنة (ContinueConversation الأحداث) لتفادي استبدال المعلومات التي قد تم إعدادها بالفعل في الطلب الأصلي.

التحقق من تدفق البيانات في المنتج

لعرض بيانات الوكلاء في Microsoft Purview أو Microsoft Defender، تأكد من استيفاء المتطلبات التالية:

الأجهزة الأوتوماتيكية

تجمع توزيعة Microsoft OpenTelemetry بين خطوط أنابيب OpenTelemetry القياسية والأجهزة التي تختارها Microsoft. يمكن لتوزيعة النظام جمع تليمترية التطبيقات، وتليمترية البنية التحتية، وتليمترية الوكيل أو تليمترية الذكاء الاصطناعي التوليدي حسب اللغة والتكوين.

الفئة ما الذي يغطيه
خطوط أنابيب الإشارة الآثار، المقاييس، والسجلات.
اكتشاف الموارد سياق التشغيل للخدمة، المضيف، السحابة، وAzure حيث يكون مدعومًا.
أجهزة البنية التحتية تم دعم HTTP، ASP.NET Core، Azure SDK، عملاء قواعد البيانات، وأطر تسجيل التسجيل.
أجهزة الذكاء الاصطناعي التوليدي تم دعم OpenAI، Azure OpenAI، نواة دلالية، LangChain، OpenAI Agents SDK، وAgent Framework.
نطاقات الوكيل اليدوية تم دعم استدعاء الوكيل، تنفيذ الأدوات، الاستدلال، وقياس المخرج.
المصدرون والمعالجون Azure Monitor، Microsoft Agent 365، OTLP، مخرجات وحدة التحكم، معالجات المدى، معالجات السجل، وقارئات المقياس.

تغطية الأجهزة

Language أجهزة التطبيقات الشائعة أدوات العامل المشترك والذكاء الاصطناعي التوليدي
Python موارد OpenTelemetry، المعالجات، القراء، التسجيلات، المقاييس، والتتبعات. ‏‫‎النواة الدلالية،‬ ‏‫‎مجموعة أدوات تطوير البرمجيات لوكلاء OpenAI،‬ ‏‫‎إطار العمل لوكيل البرمجيات،‬ ‏‫‎LangChain،‬ ‏‫‎أمتعة Microsoft Agent 365،‬ ‏‫‎ونطاقات Microsoft Agent 365.‬
Node.js HTTP، Azure SDK، دالات Azure، MongoDB، MySQL، PostgreSQL، Redis، Bunyan، وWinston. مجموعة تطوير البرمجيات لعوامل OpenAI، LangChain، أمتعة Microsoft Agent 365، ونطاق Microsoft Agent 365.
.NET ASP.NET Core، HttpClient، SQL Client، Azure SDK، كشف الموارد، المقاييس، والسجلات. نواة دلالية، OpenAI و Azure OpenAI، Agent Framework، Microsoft Agent 365 baggage، وMicrosoft Agent 365 scopes.

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

أضف مصادر أو أجهزة قياس أو معالجات أو قارئات مخصصة لتطبيق OpenTelemetry عندما يصدر تطبيقك بيانات لا تغطيها الأجهزة المدمجة.

Important

تملأ الأجهزة التلقائية سمات OpenTelemetry القياسية فقط. لا يتضمن جميع السمات التي يتطلبها العامل 365. يجب إضافة سمات خاصة Microsoft من خلال BaggageBuilder. لمعرفة السمات المطلوبة، راجع سمات التحقق من صحة المتجر.

مكتبات أدوات القياس المدمجة

تقوم الأداة التلقائية برصد بيانات التليمترية الصادرة عن الأطر المدعومة وتوجهها عبر خط أنابيب OpenTelemetry الخاص بالتوزيعة. بالنسبة لسيناريوهات الوكيل، قم بتعيين معلومات مثل معرف المستأجر ومعرف الوكيل قبل أن يقوم إطار العمل المزود بالأدوات بإنشاء التتبعات.

اطار Python Node.js .NET
النواة الدلالية مدعوم غير مدعوم مدعوم
حزمة تطوير أوبن آي ووكيلاتها مدعوم مدعوم مدعوم
إطار عمل الوكيل مدعوم غير مدعوم مدعوم
LangChain مدعوم مدعوم غير مدرج

النواة الدلالية

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

OpenAI

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

إطار عمل الوكيل

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

LangChain

ملحوظة

يدعم التهيئة التلقائية لإطار عمل LangChain أيضًا كلاً من LangGraph وDeep Agents. تلتقط نفس الأدوات تلقائيًا بيانات تتبع الاستخدام للعوامل المبنيين باستخدام أي من هذه الأطر.

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

الأدوات اليدوية

استخدم الأجهزة اليدوية عندما لا تصف الآلات الأوتوماتيكية عملية الوكيل بتفصيل كاف. تسمح النطاقات اليدوية للتطبيق بوصف أنشطة الوكيل الشائعة بطريقة متسقة عبر اللغات.

النطاق يستخدم لـ
InvokeAgentScope بدء وإكمال استدعاء الوكيل.
ExecuteToolScope استدعاء باستخدام أداة تم بواسطة وكيل.
InferenceScope عملية استدلال نموذج الذكاء الاصطناعي.
OutputScope ** المخرجات التي يجب تسجيلها بعد اكتمال النطاق الأصلي.

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

استدعاء الوكيل

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

تنفيذ الأدوات

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

with ExecuteToolScope.start(
    request=request,
    details=tool_details,
    agent_details=agent_details,
) as scope:
    result = search_emails(tool_details.arguments)
    scope.record_response(result)

استدلال

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

الإخرَاج

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

يجب أن تحدد وثائق المنتج أي متطلبات تحقق خاصة بالمنتج لهذه النطاقات.

التحقق المحلي من الصحة

يؤكد التحقق المحلي أن التطبيق ينتج بيانات عن بعد قبل التحقق من وجهة خاصة بالمنتج. استخدم مخرجات وحدة التحكم أو نقطة نهاية OTLP محلية للتحقق من إنشاء التتبع والمقاييس والسجلات.

التحقق من الصحة باستخدام نقطة نهاية محلية OTLP

قم بتكوين التوزيعة لإرسال القياسات إلى جامع محلي أو نقطة نهاية متوافقة مع OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

التحقق من الصحة باستخدام المخرجات المحلية

استخدم المخرجات المحلية عندما تريد تأكيد الأجهزة قبل إرسال البيانات إلى وجهة بعيدة.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

راجع المخرجات المحلية للفترات من المصادر المتوقعة، مثل طلبات HTTP، واستدعاءات OpenAI أو Azure OpenAI، ونطاق استدعاء الوكلاء، ونطاق تنفيذ الأدوات، أو نطاقات الاستدلال. يجب أن يتضمن التحقق المخصص للوجهة في وثائق المنتج الخاصة بتلك الوجهة.

إعداد المصادقة يدويا

عند استخدام أداة التصدير Agent 365، يجب استخدام آلية لتقديم رمز مميز للمصادقة. يعمل محلل الرمز المميز لكل دفعة تصدير باستخدام معرف الوكيل ومعرف المستأجر من سياق الأمتعة النشطة. يدعم توزيعة نهجين.

بالنسبة لوكلاء البلو برنت المدعومين بـ Agent 365 والمُعدّة بـ a365 setup all، استخدم S2S مع مُحلِّل للتطبيق فقط. ذاكرة التخزين المؤقت المضمنة للرموز agentic وأمثلة OBO في هذه الصفحة تستخدم المسار المفوض، والذي يتطلب الإذن المفوض Agent365.Observability.OtelWrite وموافقة المسؤول. a365 setup all الأمر لا يضبط هذا الإذن لوكلاء المخطط.

Tip

إذا كنت تنشئ عوامل باستخدام Microsoft 365 Agents SDK، فراجع إعداد مصادقة قابلية الملاحظة لـ Agent SDK للحصول على إرشادات خطوة بخطوة حول تكوين الحصول على الرموز المميزة OBO وS2S لكل من العوامل الوكيلة وغير الوكيلة.

محلل الرمز المميز اليدوي

استخدم مُعالجًا يدويًا عند الحصول على الرموز خارج خط أنابيب إطار عمل الوكلاء، أو عند بناء تطبيقات لا تستند إلى إطار عمل الوكلاء، أو عند استخدام مصادقة خدمة إلى خدمة (S2S). يجب أن يتطابق الرمز الذي يعيده المحلِّل مع المسار. بالنسبة للمسار المفوض، أعد رمزًا مفوضًا مع النطاق Agent365.Observability.OtelWrite. بالنسبة لمسار S2S، أعد الرمز النهائي المميز الخاص بالتطبيق فقط الذي تطلبه مع النطاق api://9b975845-388f-4429-889e-eab1ef63949c/.default. وكيل المخطط المسجل في S2S لا يحتاج إلى Agent365.Observability.OtelWrite الدور أو موافقة المسؤول.

ملحوظة

بالنسبة إلى المصادقة بين الخدمات (S2S)، يجب عليك استخدام نهج محلل الرموز المميزة اليدوي هذا. تدعم ذاكرة التخزين المؤقت للرمز المميز العامل فقط تدفقات المصادقة نيابة عن (OBO).

توضح الأمثلة التالية نمط محلّل رمز OBO (نيابة عن) المميّز — يكتسب الوكيل رمزًا مميّزًا للمستخدم عبر معالج المصادقة الخاص بالوكيل ويستبدله برمز مميّز مخصّص لقابلية الرصد. تتطلب هذه الأمثلة الإذن المفوض Agent365.Observability.OtelWrite وموافقة المسؤول. للاطلاع على أمثلة S2S (من خدمة إلى خدمة) ومقارنة بين مصادقة OBO وS2S، راجع إعداد مصادقة المراقبة لمجموعة أدوات SDK للوكيل.

يجب أن يكون محلل متزامنا. احصل على الرمز المميز في معالج النشاط غير المتزامن (أو عبر MSAL) واخزنه مؤقتا للمحلل.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

ذاكرة التخزين المؤقت للرمز المميز للوكيل مع تطبيقات إطار العمل الوكيل

بالنسبة إلى تطبيقات Agent Framework التي تستخدم مصادقة بالنيابة (OBO)، تسجّل التوزيعة IExporterTokenCache<AgenticTokenStruct> تلقائيًا عبر DI عندما لا تعيّن TokenResolver مخصصًا. يتصل وكيلك RegisterObservability() أثناء التشغيل لتوفير بيانات الاعتماد، وتتولى الذاكرة المؤقتة الحصول على الرموز المميزة المفوضة وتحديثها.

ملحوظة

يدعم هذا النهج فقط تدفقات المصادقة نيابة عن (OBO) على المسار المفوض، والذي يتطلب الإذن المفوض Agent365.Observability.OtelWrite وموافقة المسؤول. للمصادقة بين الخدمات (S2S)، بما في ذلك وكلاء المخطط المُعدّون باستخدام a365 setup all، استخدم محلل الرمز المميز اليدوي مع رمز مميز خاص بالتطبيق فقط بدلاً من ذلك. لخطوات الإعداد، انظر Agent 365-enabled باستخدام S2S.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

تخزين سمات التحقق من الصحة

للتحقق من صحة المتجر بنجاح، يجب على الوكيل تنفيذ InvokeAgentScopeو InferenceScopeو.ExecuteToolScope يتوافق كل نطاق مع عملية امتداد في المخطط المتعارف عليه:

نطاق SDK عملية الامتداد التعليمات البرمجية المرجعية العالمية
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

للحصول على القوائم الكاملة للسمات المطلوبة والاختيارية لكل نطاق - بما في ذلك دلالات كل سمة، وإرشادات اختيار القيم، والسمات القابلة للاستعلام من خلال البحث المتقدم في Microsoft Defender - راجع مرجع سمات قابلية الملاحظة لـ Agent 365. يحدد العمود ينطبق على النطاق الذي تنتمي إليه كل سمة، ويميز العمود مطلوب السمات الإلزامية (M) عن السمات الاختيارية (O).

اختبر وكيلك بقدرات المراقبة

بعد تنفيذ قابلية المراقبة، تحقق من التقاط بيانات القياس عن بُعد.

  1. انتقل إلى https://admin.cloud.microsoft/#/agents/all.
  2. حدد وكيلك، ثم حدد النشاط.
  3. تحقق من ظهور الجلسات التقنية واستدعاءات الأدوات.

نماذج التطبيقات والتكوين المتقدم

للحصول على نماذج العمل وخيارات التكوين المتقدمة، راجع مستودعات GitHub لكل لغة:

مرجع البرمجة

لمراجعة أنواع توزيعات Microsoft OpenTelemetry، راجع مقالات مرجعية برمجية التالية:

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

يصف هذا القسم المشاكل الشائعة عند تنفيذ واستخدام Microsoft OpenTelemetry Distro مع العامل 365.

المشكلة الوصف
لا تظهر بيانات إمكانية المراقبة لا يظهر أي قياس عن بُعد لأن تصدير Agent 365 غير مفعل، أو الإعداد غير مكتمل، أو فشل حل الرمز المميز.
معرف المستأجر المفقود أو معرف العامل - تم تخطي الامتدادات تتم تصفية النطاقات قبل التصدير عند غياب سمات هوية المستأجر أو الوكيل المطلوبة.
فشل حل الرمز المميز - تصدير تم تخطيه أو غير مصرح به يتم تخطي التصدير أو رفضه عندما لا يقوم محلل الرمز المميز بإرجاع أي رمز مميز أو أخطاء أثناء الحصول على الرمز المميز.
HTTP 401 غير مصرح به تصل الطلبات إلى الخدمة ولكن تفشل المصادقة لأن الرمز المميز غير صالح أو منتهي الصلاحية أو للجمهور الخطأ.
HTTP 403 ممنوع يفشل التفويض بسبب عدم وجود ترخيص للمستأجر، أو هوية S2S غير مسجلة، أو فقدان صلاحيات الكتابة الخاصة بإمكانية المراقبة حيثما تكون مطلوبة.
HTTP 403 ممنوع - عدم تطابق معرف العامل ترفض الخدمة التصدير عندما لا يتطابق معرف العامل في الطلب مع هوية العامل المعتمد من الرمز المميز.
أخطاء HTTP 429 أو 5xx - أخطاء عابرة التقييد المؤقت لمعدل الطلبات أو عدم استقرار النظام الخلفي يعطّل التصدير وقد يتطلب إعادة المحاولة أو ضبط الدفعات.
مهلة التصدير تتجاوز عمليات التصدير حدود المهلة بسبب تأخير الشبكة أو زمن استجابة نقطة النهاية.
ينجح التصدير ولكن بيانات تتبع الاستخدام لا تظهر في Defender أو Purview ينجح استيعاب البيانات ولكن يتم تأخير الرؤية أو حظرها بواسطة المتطلبات الأساسية للمصب ومتطلبات المخطط.

Tip

يحتوي دليل استكشاف أخطاء العميل 365 على توصيات عالية المستوى لحل المشاكل، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير الوكيل 365.

بيانات إمكانية الملاحظة لا تظهر

الأعراض:

  • العميل يهرب
  • لا يوجد تتبع في مركز الإدارة
  • لا يمكن رؤية نشاط العميل

السبب الجذري:

  • لم يتم تمكين التصدير لـ Agent 365
  • أخطاء التكوين
  • مشاكل حل الرموز

الحلول: جرب الخطوات التالية لحل المشكلة:

  • التحقق من تمكين تصدير الوكيل 365

    يجب تمكين مُصدّر Agent 365 بشكل واضح. عندما لا تقوم بتعيينه، قد تلجأ التوزيعة إلى مُصدر وحدة التحكم أو لا تصدر أي شيء. تمكينه في التعليمات البرمجية:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

    أو قم بتعيين متغير البيئة:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    ملحوظة

    ENABLE_A365_OBSERVABILITY_EXPORTER هو تبديل ثانوي لا يسري إلا عند enable_a365=True تعيينه في التعليمات البرمجية. يمكنك أيضا السيطرة عليه عن طريق الكوارج a365_enable_observability_exporter .

  • التحقق من تكوين محلل الرمز المميز

    يتطلب المصدر محلل رمز مميز صالح يقوم بإرجاع رمز حامل لكل طلب تصدير. إذا كان محلل الرمز المميز مفقودا أو يرجع null، يتم تخطي التصدير بصمت.

  • تمكين تصدير وحدة التحكم في النظام والتحقق من التتبع عن بعد محلياً

    إضافة مصدر تصدير وحدة التحكم للتحقق من إنشاء بيانات القياس عن بُعد قبل أن تصل إلى نقطة نهاية الوكيل 365.

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • تمكين التسجيل التفصيلي

    import logging

logging.basicConfig(level=logging.DEBUG)

  • التحقق من السجلات بحثا عن أخطاء التصدير

    استخدم الأمر للبحث في az webapp log tail السجلات عن الأخطاء المتعلقة بالمراقبة:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

معرف المستأجر أو معرف الوكيل مفقود — تم تخطي النطاقات

اعراض: يتجاهل النظام بصمت العمليات ولا يصدرها مطلقًا. تسجل بعض الأنظمة الأساسية عدد الامتدادات التي تم تخطيها أو رسالة مثل No spans with tenant/agent identity found. بينما يسقطها الآخرون دون تسجيل الدخول.

القرار:

  • قبل التصدير، تمتد أقسام التوزيعة حسب هوية المستأجر والوكيل. يتم إسقاط النطاقات التي تفتقر إلى معرف المستأجر أو معرف العامل ولا يتم إرسالها أبدا إلى الخدمة.
  • تأكد من إعداد BaggageBuilder مع معرف المستأجر ومعرف الوكيل قبل إنشاء المَتَتالَبات. تنتشر هذه القيم من خلال سياق OpenTelemetry وترتبط بجميع الامتدادات التي تم إنشاؤها ضمن نطاق الحمولة. للحصول على واجهة برمجة التطبيقات الخاصة بالنظام الأساسي، راجع سمات الأمتعة.
  • إذا كنت تستخدم برنامج وسيط الأمتعة أو مساعد تحويل السياق من حزمة تكامل الاستضافة، فتأكد من أن النشاط TurnContext لديه مستلم صالح مع هوية الوكيل.

فشل حل الرمز المميز — تصدير تم تخطيه أو غير مصرح به

الأعراض: يقوم محلل الرمز المميز بإرجاع null أو يسبب خطأً. اعتمادا على النظام الأساسي، يتم تخطي التصدير بالكامل أو فشله مع HTTP 401.

القرار:

  • محلل الرمز المميز مطلوب. إذا كان مفقودا، يطرح المصدر خطأ عند بدء التشغيل. تحقق من توفير محلل رمز مميز وإرجاع رمز حامل صالح.
  • تأكد من تمرير معرف المستأجر الصحيح ومعرف العامل إلى BaggageBuilder، لأنه تتم إعادة توجيه هذه القيم إلى محلل الرمز المميز.
  • بالنسبة إلى S2S، أعد رمز Observability النهائي الخاص بالتطبيق فقط لـ 9b975845-388f-4429-889e-eab1ef63949c أو api://9b975845-388f-4429-889e-eab1ef63949c. لا تعيد تأكيد المخطط الوسيط، أو رمز المخطط، أو رمز المستخدم أو رمز OBO.
  • بالنسبة للمسار المفوض، أعد رمزًا مفوضًا مع النطاق Agent365.Observability.OtelWrite.
  • بالنسبة للوكلاء المستضافين في Azure الذين يصدرون بهوية مدارة مباشرة، تحقق من أن الهوية المدارة لها Agent365.Observability.OtelWrite دور التطبيق. مثيلات وكلاء البلوبرينت المسجلين على S2S لا تحتاجه.
  • بالنسبة للتطبيقات .NET التي تستخدم حزمة استضافة إطار العامل، تتم معالجة تبادل الرمز المميز تلقائيا عبر DI. إذا كانت الرموز المميزة مفقودة، فتأكد من تثبيت Microsoft.Agents.A365.Observability.Hosting وتسجيلها.

HTTP 401 غير مصرح به

اعراض: فشل التصدير مع HTTP 401. لا يقوم المصدر بإعادة محاولة هذا الخطأ.

القرار:

  • تحقق من أن جمهور الرمز هو 9b975845-388f-4429-889e-eab1ef63949c أو api://9b975845-388f-4429-889e-eab1ef63949c، وأن نوع الرمز يطابق المسار: رمز مفوض للمسار المفوض، أو رمز مخصص للتطبيق فقط لمسار S2S.
  • بالنسبة إلى S2S، تحقق من أن resolver لا يعيد رمز مستخدم مفوض، أو تأكيد blueprint وسيط، أو رمز blueprint، أو رمزًا لجمهور غير صحيح، أو رمزًا منتهي الصلاحية.
  • بالنسبة للمسار المفوض، تحقق من أن مُطالَبة scp للرمز تحتوي على Agent365.Observability.OtelWrite وأن الرمز لم تنتهِ صلاحيته.

HTTP 403 ممنوع

اعراض: فشل التصدير مع HTTP 403. لا يقوم المصدر بإعادة محاولة هذا الخطأ.

السبب الجذري: يمكن أن يكون لخطأ HTTP 403 أسباب مختلفة. تحقق من الإعدادات التالية بالترتيب.

القرار:

  • الترخيص مفقود — تأكد من أن المستأجر لديه أحد التراخيص التالية المعينة في مركز إدارة Microsoft 365:

    • اختبار - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft وكيل فورنتير 365

  • الهوية غير المسجلة على S2S — يمكن لمثيل وكيل المخطط المسجل التصدير عبر مسار S2S باستخدام رمز مميز خاص بالتطبيق فقط لا Agent365.Observability.OtelWrite دور له. إذا لم تكن الهوية مسجلة لدى Agent 365، تعيد الخدمة HTTP 403 insufficient_scope. بالنسبة لوكلاء المخطط، a365 setup all يسجل مثيل الوكيل. لإعادة محاولة عملية تسجيل فاشلة، شغّل a365 setup all --agent-registration-only. إنشاء هوية Microsoft Entra وحده لا يسجل مثيل الوكيل.

  • إذن Agent365.Observability.OtelWrite مفقود حيثما كان مطلوبًا — امنح الإذن للمسار المفوض أو للهويات غير المسجلة، بما في ذلك تسجيلات التطبيقات القياسية. وكلاء المخططات المسجلين في S2S لا يحتاجون إلى هذا الإذن.

منح الإذن

امنح Agent365.Observability.OtelWrite فقط عندما تستخدم المسار المفوض أو الهوية غير المسجلة. وكلاء المخططات المسجلين الذين يستخدمون S2S لا يحتاجون إلى هذه الإذن أو موافقة المسؤول. امنح فقط نوع الإذن الذي يستخدمه مسارك:

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

استخدم أحد الخيارات التالية:

  • Agent 365 CLI (وكلاء blueprint على المسار المفوض)

    يضيف هذا الأمر الإذن المفوض إلى مخططك وأذوناتك القابلة للوراثة، ثم يمنح موافقة المسؤول. لا يضيف إذن التطبيق. يتطلب حساب المسؤول العام. شغل الأمر من دليل مشروع الوكيل الذي يحتوي على a365.config.json، أو أضف --agent-name "<agent-name>".

    a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite

  • مركز مسؤولي Microsoft Entra (أيّ من المسارين)

    لا حاجة لملفات الإعدادات؛ يتطلب صلاحيات المسؤول العام لتسجيل التطبيق. بالنسبة لمخطط على المسار المفوض، استخدم هذا الخيار فقط إذا كان المخطط يحتوي بالفعل على Observability API في صلاحياته القابلة للوراثة، مثل مخطط أعدته نسخة CLI سابقة. وإلا، استخدم CLI من Agent 365.

    1. انتقل إلى مركز إدارة Microsoft Entra، وحدد App registrations، ثم حدد تسجيل التطبيق الخاص بك من نوع blueprint أو standard.
    2. انتقل إلى أذونات واجهة برمجة التطبيقات>، ثم انقر على إضافة إذن>، واختر واجهات برمجة التطبيقات التي تستخدمها مؤسستي>، وابحث عن 9b975845-388f-4429-889e-eab1ef63949c.
    3. اختر الأذونات المفوضة للمسار المفوض، أو أذونات التطبيق لهوية غير مسجلة على مسار S2S.
    4. تحقق من Agent365.Observability.OtelWrite، ثم اختر إضافة الأذونات.
    5. اختر منح موافقة المسؤول وأكد.

    الإذن الذي أضفته يعرض الحالة Granted.

HTTP 403 ممنوع — عدم تطابق معرف الوكيل

الأعراض: يفشل التصدير مع HTTP 403 ورسالة خادم مشابهة لـ 403 Forbidden مع agent-ID-mismatch من حالات الفشل عند استدعاء نقاط نهاية التتبع الخاصة بـ Agent 365.

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

القرار:

  • تحقق مما إذا كان معرف المستأجر قد تمت إضافته إلى قائمة المستأجرين المسموح بها ل Agent 365.
  • تعيين تفاصيل العامل مع معرف عميل مثيل العامل (وليس معرف عميل المخطط).
  • تحقق من عنوان URL للتصدير الذي تم إنشاؤه - يتم تسجيله إذا قمت بتمكين المسجل. تأكد من أن معرف العامل في عنوان URL يطابق معرف عميل مثيل العامل.
  • لتمكين التسجيل التشخيصي لكل SDK، راجع التحقق المحلي.

أخطاء HTTP 429 أو 5xx - أخطاء عابرة

اعراض: فشل التصدير مع رمز حالة HTTP عابر مثل 429 أو 5xx.

القرار:

  • عادة ما تكون هذه الأخطاء عابرة وتحل من تلقاء نفسها. يعيد Python وJavaScript المحاولة تلقائيا على رموز الحالة HTTP 408 و429 و5xx. لا تتم إعادة محاولة توزيع .NET تلقائيا.
  • إذا استمرت الأخطاء، فتحقق من لوحة معلومات حماية الخدمة.
  • ضع في اعتبارك تقليل تكرار التصدير عن طريق زيادة التأخير المجدول بين الدفعات أو الحد الأقصى لحجم دفعة التصدير. بالنسبة إلى Python وJavaScript، استخدم المعلمات ذات الصلة exporterOptions أو a365_* الموثقة في مستودعات GitHub. بالنسبة إلى .NET، استخدم o.Agent365.Exporter.ScheduledDelayMillisecondso.Agent365.Exporter.MaxExportBatchSize.

مهلة التصدير

الأعراض: انتهت مدة محاولات التصدير.

القرار:

  • تحقق من اتصال الشبكة بنقطة نهاية إمكانية المراقبة.

  • مهلة طلب HTTP الافتراضية هي 30 ثانية عبر جميع الأنظمة الأساسية. إذا كانت المهلات تحدث بشكل متكرر، فقم بزيادة قيمة المهلة في خيارات المصدر:

    use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

    راجع مستودع Python للحصول على القائمة الكاملة لخيارات a365_*.

ينجح التصدير ولكن بيانات تتبع الاستخدام لا تظهر في Defender أو Purview

Symptoms: تعرض السجلات تصديرا ناجحا (HTTP 200) ولكن بيانات تتبع الاستخدام غير مرئية في Microsoft Defender أو Microsoft Purview.

القرار:

  • تحقق من تلبية المتطلبات الأساسية لعرض السجلات المصدرة:
  • يمكن أن يستغرق القياس عن بعد عدة دقائق للتعبئة بعد التصدير الناجح. انتظر قبل إجراء مزيد من التحقيق.
  • تحقق من أن المجالات تحتوي على سمات microsoft.tenant.id وgen_ai.agent.id صالحة. تتسبب سمات الهوية المفقودة في إسقاط الامتدادات من جانب الخادم حتى إذا كان تصدير HTTP يرجع 200.

المحتوى ذو الصلة

  • Last updated on