توزيعة Microsoft OpenTelemetry

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

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

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

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

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

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

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

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

المتطلبات الأساسية: Python 3.10 أو أحدث.

pip install microsoft-opentelemetry

التكوين

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

اتصل 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().

المعلمة‬ الوصف افتراضي
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

نشر السياق

للحفاظ على قابلية الملاحظة عبر عمليات Agent 365 الموزعة، قم بتمرير السياق. عندما تمرر السياق عبر عواملَك وخدماتك، تضمن أن التتبع والسجلات والمقاييس مرتبطة بشكل صحيح خلال دورة حياة الطلب بالكامل. هذا الارتباط ضروري لتجربة مراقبة Microsoft Agent 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. يمكن لـ Distro جمع بيانات تتبع الاستخدام للتطبيقات، وبيانات تتبع الاستخدام للبنية التحتية، وبيانات تتبع الاستخدام للوكلاءن أو الذكاء الاصطناعي التوليدي اعتمادًا على اللغة والتكوين.

الفئة ما الذي يغطيه هذا
مسارات الإشارات التتبعات والمقاييس والسجلات.
اكتشاف الموارد حيث كانت الخدمة والمضيف والسحابة وسياق وقت التشغيل 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 Agents SDK، وAgent Framework، وLangChain، وبيانات Microsoft Agent 365، ونطاقات Microsoft Agent 365.
Node.js HTTP، وAzure SDK، ودالات Azure، وMongoDB، وMySQL، وPostgreSQL، وRedis، وBunyan، وWinston. OpenAI Agents SDK، وLangChain، بيانات Microsoft Agent 365، وMicrosoft Agent 365 scopes.
.NET ASP.NET Core، وHttpClient، وSQL Client، وAzure SDK، واكتشاف الموارد، والمقاييس، والسجلات. نواة دلالية وOpenAI وAzure OpenAI وAgent Framework وحمولة Microsoft Agent 365 ونطاقات Microsoft Agent 365.

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

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

مهم

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

مكتبات أجهزة مدمجة

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

Framework Python Node.js .NET
نواة دلالية مدعوم غير مدعوم مدعوم
OpenAI وOpenAI Agents SDK مدعوم مدعوم مدعوم
Agent Framework مدعوم غير مدعوم مدعوم
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},
    },
)

Agent Framework

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

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 محلية

وقم بتكوين Distro لإرسال بيانات تتبع الاستخدام إلى جامع محلي أو نقطة نهاية أخرى متوافقة مع بروتوكول 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، يجب عليك توفير آلية لتوفير الرمز المميز للمصادقة. يعمل محلّل التوكنات لكل دفعة تصدير باستخدام معرف العامل ومعرف المستأجر من سياق الأمتعة النشطة. تدعم distro نهجين.

تلميح

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

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

استخدم محلل يدوي عند الحصول على الرموز المميزة خارج مسار Agent Framework، أو عند إنشاء تطبيقات غير تابعة لـ Agent Framework، أو عند استخدام مصادقة الخدمة إلى الخدمة (S2S) (تدفق بيانات اعتماد العميل). يمكن للوكلاءن إنشاء رمز مميز بأنفسهم، على سبيل المثال باستخدام مكتبة مصادقة Microsoft ‏(MSAL) أو أي طريقة أخرى للحصول على الرموز المميزة، ولكن عليهم التأكد من أن الرمز المميز لديه نطاق المراقبة الصحيح (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

إشعار

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

توضح الأمثلة التالية نمط محلّل رمز OBO (نيابة عن) المميّز — يكتسب العامل رمزًا مميّزًا للمستخدم عبر معالج المصادقة الخاص بالعامل ويستبدله برمز مميّز مخصّص لإمكانية المراقبة. للحصول على أمثلة S2S (خدمة إلى خدمة) ومقارنة بين مصادقة OBO ومصادقة S2S، راجع إعداد مصادقة المراقبة لـ Agent 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

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

إشعار

يدعم هذا النهج فقط تدفقات مصادقة نيابة عن (OBO). للمصادقة من خدمة إلى خدمة (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 مع Agent 365.

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

تلميح

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

بيانات قابلية المراقبة لا تظهر

العلامات:

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

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

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

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

  • تأكد من تمكين تصدير Agent 365

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

    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، يتم تخطي التصدير بصمت.

  • مكّن تصدير وحدة التحكم وتحقق من قياس تتبع الاستخدام محليًا

    وأضف مُصدِّر وحدة التحكم للتحقق من توليد بيانات تتبع الاستخدام قبل وصولها إلى نقطة نهاية Agent 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. يسقطها الآخرون دون تسجيل.

الحل:

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

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

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

الحل:

  • مطلوب محلل الرموز المميزة. إذا كان مفقودًا، فإن المصدر يُظهر خطأً عند بدء التشغيل. تحقق من توفير محلل رمز مميز وإرجاع رمز مميز صالْح للحامل.
  • تأكد من تمرير معرف المستأجر الصحيح ومعرف عامل الصحيح إلى BaggageBuilder، لأن هذه القيم يتم توجيهها إلى محل الرمز.
  • بالنسبة للوكلاءن المستضافين على Azure، تحقق من أن الهوية المُدارة لديها إذن API المطلوب لنطاق المراقبة.
  • وبالنسبة لتطبيقات .NET التي تستخدم حزمة استضافة Agent Framework، تتم معالجة تبادل الرموز المميزة تلقائيًا عبر DI. إذا كانت الرموز المميزة مفقودة، فتأكد من تثبيت Microsoft.Agents.A365.Observability.Hosting وتسجيله.

HTTP 401 غير مخوّل

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

الحل:

  • تحقق من أن جمهور الرمز يتوافق مع نطاق نقطة النهاية للرصد.
  • تحقق من أن محلل الرموز لا يعيد رمز مستخدم مفوّض، أو رمزًا لجمهور غير صحيح، أو رمزًا منتهي الصلاحية.

HTTP 403 محظور

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

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

الحل:

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

    • اختبار - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • إذن Agent365.Observability.OtelWrite مفقود — منح الإذن إلى هويتك (الهوية المُدارة أو تسجيل التطبيق). بدون ذلك، يفشل تصدير بيانات القياس عن بعد، ويظهر خطأ HTTP 403.

منح الإذن

استخدم أيًا من هذين الخيارين:

  • Agent 365 CLI

    يتطلب حساب مسؤول عام؛ شغّله من دليل مشروع العامل الذي يحتوي على a365.config.json، أو استخدم --agent-name.

    a365 setup permissions bot

    أو، بدون ملف التكوين:

    a365 setup permissions bot --agent-name "<agent-name>"

  • مدخل Entra

    لا حاجة لملفات الإعدادات؛ تحتاج إلى وصول مسؤول عام إلى تسجيل تطبيق المخطط.

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

    كل من Agent365.Observability.OtelWrite (مفوضة) وAgent365.Observability.OtelWrite (التطبيق) يظهران حالة Granted.

HTTP 403 محظور - عدم تطابق هوية العامل

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

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

الحل:

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

أخطاء HTTP 429 أو 5xx - أخطاء مؤقتة

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

الحل:

  • عادةً ما تكون هذه الأخطاء مؤقتة وتحل من تلقاء نفسها. تقوم توزيعات Python وJavaScript بإعادة المحاولة تلقائيًا عند ظهور رموز الحالة HTTP 408 و429 و5xx. لا يقوم توزيع .NET بإعادة المحاولة تلقائيًا.
  • إذا استمرت الأخطاء، تحقق من لوحة تحكم صحة الخدمة.
  • فكر في تقليل تكرار التصدير عن طريق زيادة التأخير المجدول بين الدفعات أو الحد الأقصى لحجم دفعة التصدير. بالنسبة للغة Python وJavaScript، استخدم معلمات exporterOptions أو a365_* ذات الصلة والموثقة في مستودعات GitHub. بالنسبة إلى .NET، استخدم o.Agent365.Exporter.ScheduledDelayMilliseconds وo.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

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

الحل:

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

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

  • Last updated on