قابلية الرصد

تعد إمكانية المراقبة جانبا رئيسيا من جوانب بناء أنظمة موثوقة وقابلة للصيانة. يوفر إطار عمل العامل دعما مضمنا لقابلية المراقبة، ما يسمح لك بمراقبة سلوك وكلائك.

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

تكامل OpenTelemetry

يتكامل إطار عمل العامل مع OpenTelemetry، وبشكل أكثر تحديدا يرسل إطار عمل العامل التتبعات والسجلات والمقاييس وفقا للاصطلاحات الدلالية ل OpenTelemetry GenAI.

تمكين إمكانية المراقبة (C#)

لتمكين إمكانية المراقبة لعميل الدردشة، تحتاج إلى إنشاء عميل الدردشة كما يلي:

// Using the AIProjectClient as an example
var instrumentedChatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName) // Converts into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

لتمكين إمكانية المراقبة لوكيلك، تحتاج إلى إنشاء العامل على النحو التالي:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
)
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Important

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

تحذير

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

الإعداد

الآن بعد أن تم وضع علامة على عميل الدردشة والوكيل الخاص بك، يمكنك تكوين مصدري OpenTelemetry لإرسال بيانات تتبع الاستخدام إلى الخلفية المطلوبة.

Traces

لتصدير التتبعات إلى الخلفية المطلوبة، يمكنك تكوين OpenTelemetry SDK في التعليمات البرمجية لبدء تشغيل التطبيق الخاص بك. على سبيل المثال، لتصدير تتبعات إلى مورد Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using System;

// The source name under which all activities, metrics, and logs will be emitted.
const string SourceName = "MyApplication";
const string ServiceName = "AgentOpenTelemetry";

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Tip

AddSource يتم استخدام الأسلوب لتحديد اسم المصدر الذي سيستمع إليه الموفر. تأكد من أنه يطابق اسم المصدر الذي استخدمته في التعليمات البرمجية للأجهزة (على سبيل المثال، UseOpenTelemetry(sourceName: SourceName)). إذا لم يتم تحديد اسم مصدر في التعليمات البرمجية للأجهزة، فسيتم تعيينه افتراضيا إلى Experimental.Microsoft.Agents.AI، وفي هذه الحالة يجب عليك استخدام AddSource("Experimental.Microsoft.Agents.AI") في موفر التتبع وتكوين موفر العداد.

Tip

اعتمادا على الخلفية الخاصة بك، يمكنك استخدام مصدرين مختلفين. لمزيد من المعلومات، راجع وثائق openTelemetry .NET. للتطوير المحلي، ضع في اعتبارك استخدام لوحة معلومات Aspire.

المقاييس

وبالمثل، لتصدير المقاييس إلى الخلفية المطلوبة، يمكنك تكوين OpenTelemetry SDK في التعليمات البرمجية لبدء تشغيل التطبيق الخاص بك. على سبيل المثال، لتصدير المقاييس إلى مورد Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using System;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Logs

يتم التقاط السجلات عبر إطار عمل التسجيل الذي تستخدمه، على سبيل المثال Microsoft.Extensions.Logging. لتصدير السجلات إلى مورد Azure Monitor، يمكنك تكوين موفر التسجيل في التعليمات البرمجية لبدء تشغيل التطبيق:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Extensions.Logging;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter(options => options.ConnectionString = applicationInsightsConnectionString);
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    })
    .SetMinimumLevel(LogLevel.Debug);
});

// Create a logger instance for your application
var logger = loggerFactory.CreateLogger<Program>();

لوحة معلومات تطمح

ضع في اعتبارك استخدام لوحة معلومات Aspire كطريقة سريعة لتصور آثارك ومقاييسك أثناء التطوير. لمعرفة المزيد، راجع وثائق Aspire Dashboard. تتلقى لوحة معلومات Aspire البيانات عبر OpenTelemetry Collector، والتي يمكنك إضافتها إلى موفر التتبع الخاص بك على النحو التالي:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

الشروع في العمل

راجع مثالا كاملا لعامل مع تمكين OpenTelemetry في مستودع إطار عمل العامل.

Tip

راجع نماذج .NET للحصول على أمثلة كاملة قابلة للتشغيل.

التبعيات

الحزم المضمنة

لتمكين إمكانية الملاحظة في تطبيق Python، يتم تثبيت حزم OpenTelemetry التالية بشكل افتراضي:

المصدرين

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

بعض المصدرين الشائعين الذين قد ترغب في تثبيتهم بناء على احتياجاتك:

لدعم بروتوكول gRPC: تثبيت opentelemetry-exporter-otlp-proto-grpc
لدعم بروتوكول HTTP: تثبيت opentelemetry-exporter-otlp-proto-http
للحصول على Azure Application Insights: تثبيتazure-monitor-opentelemetry

استخدم OpenTelemetry Registry للعثور على المزيد من المصدرين وحزم الأجهزة.

تمكين إمكانية المراقبة (Python)

نشر تتبع MCP

كلما كان هناك سياق OpenTelemetry span نشط، ينشر إطار عمل العامل تلقائيا سياق التتبع إلى خوادم MCP عبر params._meta حقل tools/call الطلبات. ويستخدم نشر (الشبكات) OpenTelemetry المكونة عالميا (سياق تتبع W3C افتراضيا، وينتج traceparent و tracestate)، لذلك يتم أيضا دعم النشرات المخصصة (B3 وJaeger وما إلى ذلك). وهذا يمكن التتبع الموزع عبر حدود الخادم من عامل إلى MCP، متوافق مع مواصفات MCP_meta.

النطاق: ينطبق الحقن التلقائي _meta فقط على جلسات عمل MCP التي تفتحها عملية العامل نفسها — MCPStreamableHTTPToolو MCPStdioToolو MCPWebsocketTool (أو أي فئة فرعية أخرى مفتوحة من قبل MCPTool العميل). لا ينطبق على تكوينات أداة MCP المستضافة/المدارة من قبل الموفر مثل FoundryChatClient.get_mcp_tool(...)أو AnthropicClient.get_mcp_tool(...)OpenAIChatClient.get_mcp_tool(...)GeminiChatClient.get_mcp_tool(...)مربعات أدوات عامل Foundry المستضاف، لأنه في هذه الحالات tools/call يتم إصدار الرسالة بواسطة وقت تشغيل خدمة الموفر بدلا من عملية العامل. ونتيجة لذلك، لا توجد فرصة لإطار العمل لإدخال سياق التتبع في تلك الطلبات، ويتحمل النشر traceparent/tracestate عبر حدود الخدمة المستضافة مسؤولية وقت تشغيل الخدمة، وليس إطار عمل العامل. إذا كان التتبع الموزع من طرف إلى طرف إلى خادم MCP المتلقي للمعلومات مطلوبا، فاستخدم نقل MCP مفتوح من قبل العميل بدلا من موصل مستضاف.

خمسة أنماط لتكوين إمكانية الملاحظة

لقد حددنا طرقا متعددة لتكوين إمكانية الملاحظة في التطبيق الخاص بك، اعتمادا على احتياجاتك:

1. متغيرات بيئة القياس المفتوح القياسية (مستحسن)

أبسط نهج - تكوين كل شيء عبر متغيرات البيئة:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

أو إذا كنت تريد مصدري وحدة التحكم فقط، فقم بتعيين ENABLE_CONSOLE_EXPORTERS متغير البيئة:

ENABLE_CONSOLE_EXPORTERS=true

from agent_framework.observability import configure_otel_providers

# Console exporters are enabled via the ENABLE_CONSOLE_EXPORTERS env var
configure_otel_providers()

يمكنك أيضا تجاوز إعدادات مصدر الخدمة العامة والموارد وOTLP في التعليمات البرمجية:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(
    service_name="customer-support-agent",
    resource_attributes={
        "deployment.environment.name": "production",
        "service.namespace": "customer-support",
    },
    otlp_endpoint="https://otel.example.com",
    otlp_protocol="http/protobuf",
)

otlp_protocol تقبل المعلمة grpcأو http/protobufأو http. يمكنك أيضا تعيين ، ، في ثوان، و، deflategzipأو otlp_compression ، أو none. otlp_timeoutotlp_headersservice_version يكون لاسم الخدمة الصريح وقيم الإصدار الأسبقية على متغيرات البيئة الخاصة بهم، أثناء resource_attributes الدمج عبر OTEL_RESOURCE_ATTRIBUTES. تتجاوز إعدادات OTLP البرمجية متغيرات البيئة الأساسية الخاصة بها. تظل متغيرات نقطة النهاية والرأس الخاصة بالإشارة أكثر تحديدا، وتستبدل otlp_headers الرؤوس الأساسية قبل دمج الرؤوس الخاصة بالإشارة. بالنسبة إلى HTTP، تتلقى /v1/tracesنقطة النهاية الأساسية تلقائيا المسار أو /v1/metricsأو ./v1/logs

2. المصدرون المخصصون

لمزيد من التحكم في المصدرين، قم بإنشائها بنفسك وتمريرها إلى configure_otel_providers():

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from agent_framework.observability import configure_otel_providers

# Create custom exporters with specific configuration
exporters = [
    OTLPSpanExporter(endpoint="http://localhost:4317", compression=Compression.Gzip),
    OTLPLogExporter(endpoint="http://localhost:4317"),
    OTLPMetricExporter(endpoint="http://localhost:4317"),
]

# These will be added alongside any exporters from environment variables
configure_otel_providers(exporters=exporters, enable_sensitive_data=True)

3. إعداد جهة خارجية

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

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

# Configure Azure Monitor first
configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),  # Uses OTEL_SERVICE_NAME, etc.
    enable_live_metrics=True,
)

# Then activate Agent Framework's telemetry code paths
# This is optional if ENABLE_INSTRUMENTATION and/or ENABLE_SENSITIVE_DATA are set in env vars
enable_instrumentation(enable_sensitive_data=False)

بالنسبة إلى Langfuse:

from agent_framework.observability import enable_instrumentation
from langfuse import get_client

langfuse = get_client()

# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")

# Then activate Agent Framework's telemetry code paths
enable_instrumentation(enable_sensitive_data=False)

4. الإعداد اليدوي

للتحكم الكامل، يمكنك إعداد المصدرين والموفرين والأجهزة يدويا. استخدم وظيفة create_resource() المساعد لإنشاء مورد باسم الخدمة والإصدار المناسبين. راجع وثائق openTelemetry Python للحصول على إرشادات مفصلة حول الأجهزة اليدوية.

5. تقرير عن حالة النظام التلقائي (رمز صفري)

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

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python agent_framework_app.py

راجع وثائق التعليمات البرمجية الصفرية ل OpenTelemetry Python للحصول على مزيد من المعلومات.

استخدام أدوات التتبع والعدادات

بمجرد تكوين إمكانية الملاحظة، يمكنك إنشاء نطاقات أو مقاييس مخصصة:

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

هذه هي برامج تضمين OpenTelemetry API التي ترجع تتبعا أو عدادا من الموفر العمومي، مع agent_framework تعيين كاسم مكتبة الأجهزة بشكل افتراضي.

متغيرات البيئة

تتحكم متغيرات البيئة التالية في إمكانية مراقبة إطار عمل العامل:

ENABLE_INSTRUMENTATION - الافتراضي هو true؛ تعيين إلى false لتعطيل تقرير حالة النظام OpenTelemetry.
ENABLE_SENSITIVE_DATA - الافتراضي هو false، تعيين إلى true لتمكين تسجيل البيانات الحساسة (المطالبات والاستجابات ووسيطات استدعاء الدالة والنتائج). كن حذرا مع هذا الإعداد لأنه قد يعرض البيانات الحساسة.
ENABLE_MESSAGE_EVENTS - الافتراضي هو true؛ قيم true، 1، yes، أو on تمكين أحداث سجل الرسائل والاختيارات v1.36، بشكل غير حساس لحالة الأحرف. أي قيمة مجموعة أخرى تعطلها. يتم إصدار هذه الأحداث فقط عند تمكين الأجهزة والبيانات الحساسة أيضا.
ENABLE_CONSOLE_EXPORTERS - الافتراضي هو false، تعيين إلى true لتمكين إخراج وحدة التحكم لبيانات تتبع الاستخدام.
VS_CODE_EXTENSION_PORT- منفذ مجموعة أدوات الذكاء الاصطناعي أو تكامل ملحق Microsoft Foundry VS Code.
OTEL_SEMCONV_STABILITY_OPT_IN - عند إلغاء الإعداد، يستخدم إطار عمل العامل أحدث اصطلاحات GenAI التجريبية. إذا تم تعيينه، فقم بتضمين الرمز المميز الحساس gen_ai_latest_experimental لحالة الأحرف في القيمة المفصولة بفواصل لاستخدام أحدث الاصطلاحات. تحدد قيمة المجموعة التي تحذف هذا الرمز المميز، بما في ذلك قيمة فارغة، اصطلاحات v1.36.

سمات امتداد الوضع الأخير تنبعث منها ؛ تنبعث gen_ai.provider.namegen_ai.systemمنها سمات نطاق v1.36 وأحداث الرسائل . اختيار حدث الرسالة مستقل عن تحديد الاصطلاح الدلالي. يؤدي تحديد v1.36 إلى منع أحدث سمات نطاق الرسالة ولكنه لا يعطل أحداث الرسائل v1.36. مع تمكين البيانات الحساسة، يصدر أحدث وضع افتراضي كلا التمثيلين.

يضيف إطار عمل العامل أيضا حزمته وإصداره إلى User-Agent طلبات العميل المدعومة. يمكن أن تتضمن مسارات طلب Microsoft المعتمدة Azure OpenAI رمزا مميزا لاستخدام الميزات على مستوى العملية يقوم بترميز فئات ميزات إطار العمل، وليس محتوى المطالبة أو الاستجابة. تعيين هذه المتغيرات قبل بدء العملية:

AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true - يعطل الرمز المميز لاستخدام الميزة فقط ويحتفظ بالحزمة/الإصدار User-Agent.
AGENT_FRAMEWORK_USER_AGENT_DISABLED=true - يعطل مساهمة إطار عمل العامل بأكملها User-Agent، بما في ذلك الرمز المميز للميزة.

تحذير

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

متغيرات بيئة القياس المفتوح القياسية

configure_otel_providers() تقرأ الدالة تلقائيا متغيرات بيئة OpenTelemetry القياسية:

تكوين OTLP (للوحة معلومات Aspire وJaeger وما إلى ذلك):

OTEL_EXPORTER_OTLP_ENDPOINT - نقطة النهاية الأساسية لجميع الإشارات (على سبيل المثال، http://localhost:4317)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - نقطة نهاية خاصة بالتتتبعات (تجاوز القاعدة)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - نقطة نهاية خاصة بالمقاييس (تجاوز القاعدة)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - نقطة نهاية خاصة بالسجلات (تجاوز القاعدة)
OTEL_EXPORTER_OTLP_PROTOCOL - البروتوكول المراد استخدامه (grpc أو ، الافتراضي http: grpc)
OTEL_EXPORTER_OTLP_HEADERS - رؤوس لجميع الإشارات (على سبيل المثال، key1=value1,key2=value2)

تعريف الخدمة:

OTEL_SERVICE_NAME - اسم الخدمة (الافتراضي: agent_framework)
OTEL_SERVICE_VERSION - إصدار الخدمة (الافتراضي: إصدار الحزمة)
OTEL_RESOURCE_ATTRIBUTES - سمات الموارد الإضافية

راجع مواصفات OpenTelemetry لمزيد من التفاصيل.

إعداد Microsoft Foundry

يحتوي Microsoft Foundry على دعم مضمن للتتبع باستخدام المرئيات للامتدادات الخاصة بك.

تأكد من تكوين Foundry باستخدام مثيل Azure Monitor، راجع التفاصيل

ثبّت حزمة `azure-monitor-opentelemetry`.

pip install azure-monitor-opentelemetry

تكوين إمكانية المراقبة مباشرة من `FoundryChatClient`

بالنسبة لمشاريع Foundry، يمكنك تكوين إمكانية المراقبة مباشرة من FoundryChatClient:

import os

from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        )

        # Automatically configures Azure Monitor with the connection string from the Foundry project
        await client.configure_azure_monitor(enable_live_metrics=True)

Tip

يتم تمرير الوسيطات الخاصة client.configure_azure_monitor() بالدالة configure_azure_monitor() الأساسية من الحزمةazure-monitor-opentelemetry، راجع الوثائق للحصول على التفاصيل، ونهتم بتعيين سلسلة الاتصال والمورد.

تكوين azure monitor وتمكين الأجهزة اختياريا

بالنسبة للمشاريع غير التابعة ل Foundry باستخدام Application Insights، تأكد من إعداد وكيل مخصص في Foundry، راجع التفاصيل.

ثم قم بتشغيل عاملك بنفس معرف عامل OpenTelemetry كما هو مسجل في Foundry، وقم بتكوين azure monitor كما يلي:

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),
    enable_live_metrics=True,
)
# optional if you do not have ENABLE_INSTRUMENTATION in env vars
enable_instrumentation()

# Create your agent with the same OpenTelemetry agent ID as registered in Foundry
agent = Agent(
    client=...,
    name="My Agent",
    instructions="You are a helpful assistant.",
    id="<OpenTelemetry agent ID>"
)
# use the agent as normal

لوحة معلومات تطمح

للتطوير المحلي دون إعداد Azure، يمكنك استخدام لوحة معلومات Aspire، التي تعمل محليا عبر Docker وتوفر تجربة عرض ممتازة لبيانات تتبع الاستخدام.

إعداد لوحة معلومات Aspire باستخدام Docker

# Pull and run the Aspire Dashboard container
docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

سيبدأ هذا الأمر لوحة المعلومات ب:

واجهة مستخدم الويب: متوفرة في http://localhost:18888
نقطة نهاية OTLP: متوفرة في http://localhost:4317 لتطبيقاتك لإرسال بيانات تتبع الاستخدام

تكوين التطبيق الخاص بك

عيّن متغيرات البيئة التالية:

ENABLE_INSTRUMENTATION=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

أو قم بتضمينها في الملف الخاص بك .env وتأكد من الاتصال load_dotenv() في بداية التطبيق الخاص بك (إطار عمل العامل لا يقوم .env بتحميل الملفات تلقائيا).

بمجرد انتهاء تشغيل العينة، انتقل إلى http://localhost:18888 في مستعرض ويب لمشاهدة بيانات تتبع الاستخدام. اتبع دليل استكشاف لوحة معلومات Aspire للمصادقة على لوحة المعلومات والبدء في استكشاف التتبعات والسجلات والمقاييس.

الامتدادات والمقاييس

بمجرد إعداد كل شيء، ستبدأ في رؤية الامتدادات والمقاييس التي يتم إنشاؤها تلقائيا من أجلك، فإن النطاقات هي:

invoke_agent <agent_name>: هذا هو نطاق المستوى الأعلى لكل استدعاء عامل، وسوف يحتوي على جميع الامتدادات الأخرى كأطفال.
chat <model_name>: يتم إنشاء هذا النطاق عندما يستدعي العامل نموذج الدردشة الأساسي، فإنه سيحتوي على المطالبة والاستجابة كسمات، إذا enable_sensitive_data تم تعيين إلى True.
execute_tool <function_name>: يتم إنشاء هذا النطاق عندما يستدعي العامل أداة دالة، فإنه سيحتوي على وسيطات الدالة والنتيجة كسمات، إذا enable_sensitive_data تم تعيين إلى True.

المقاييس التي تم إنشاؤها هي:

لعميل الدردشة والعمليات chat :
- gen_ai.client.operation.duration (المدرج التكراري): يقيس هذا المقياس مدة كل عملية، بالثوان.
- gen_ai.client.token.usage (المدرج التكراري): يقيس هذا المقياس استخدام الرمز المميز، في عدد الرموز المميزة.
لادعاء الدالة execute_tool أثناء العمليات:
- agent_framework.function.invocation.duration (المدرج التكراري): يقيس هذا المقياس مدة تنفيذ كل دالة، بالثوان.

مثال على إخراج التتبع

عند تشغيل عامل مع تمكين إمكانية المراقبة، سترى بيانات تتبع مشابهة لإخراج وحدة التحكم التالية:

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-09-25T11:00:48.663688Z",
    "end_time": "2025-09-25T11:00:57.271389Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.provider.name": "openai",
        "gen_ai.agent.id": "Joker",
        "gen_ai.agent.name": "Joker",
        "gen_ai.request.instructions": "You are good at telling jokes.",
        "gen_ai.response.id": "chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

يظهر هذا التتبع:

تتبع معرفات الامتداد: لربط العمليات ذات الصلة
معلومات التوقيت: عند بدء العملية وانتهائها
بيانات تعريف العامل: معرف العامل والاسم والإرشادات
معلومات النموذج: موفر الذكاء الاصطناعي المستخدم (OpenAI) ومعرف الاستجابة
استخدام الرمز المميز: عدد رموز الإدخال والإخراج لتعقب التكلفة

Samples

هناك عدد من العينات في microsoft/agent-framework المستودع توضح هذه القدرات. لمزيد من المعلومات، راجع مجلد نماذج المراقبة. يتضمن هذا المجلد نماذج لاستخدام بيانات تتبع الاستخدام بدون تعليمات برمجية أيضا.

مثال كامل

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.observability import configure_otel_providers, get_tracer
from agent_framework.openai import OpenAIChatClient
from opentelemetry.trace import SpanKind
from opentelemetry.trace.span import format_trace_id
from pydantic import Field

"""
This sample shows how you can observe an agent in Agent Framework by using the
same observability setup function.
"""


# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
async def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    await asyncio.sleep(randint(0, 10) / 10.0)  # Simulate a network call
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


async def main():
    # calling `configure_otel_providers` will *enable* tracing and create the necessary tracing, logging
    # and metrics providers based on environment variables.
    # See the .env.example file for the available configuration options.
    configure_otel_providers()

    questions = ["What's the weather in Amsterdam?", "and in Paris, and which is better?", "Why is the sky blue?"]

    with get_tracer().start_as_current_span("Scenario: Agent Chat", kind=SpanKind.CLIENT) as current_span:
        print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")

        agent = Agent(
            client=OpenAIChatClient(),
            tools=get_weather,
            name="WeatherAgent",
            instructions="You are a weather assistant.",
            id="weather-agent",
        )
        thread = agent.create_session()
        for question in questions:
            print(f"\nUser: {question}")
            print(f"{agent.name}: ", end="")
            async for update in agent.run(
                question,
                session=thread,
                stream=True,
            ):
                if update.text:
                    print(update.text, end="")


if __name__ == "__main__":
    asyncio.run(main())

إمكانية المراقبة باستخدام OpenTelemetry

يتضمن Go Agent Framework برنامج وسيط OpenTelemetry الذي يتتبع استدعاءات العامل تلقائيا.

الإعداد

import (
    "github.com/microsoft/agent-framework-go/provider/otelprovider"

    "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    otellib "go.opentelemetry.io/otel"
)

// Create a tracer provider with a console exporter
exporter, _ := stdouttrace.New(stdouttrace.WithPrettyPrint())
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
defer tp.Shutdown(context.Background())
otellib.SetTracerProvider(tp)

إضافة البرنامج الوسيط إلى وكيلك

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Middlewares: []agent.Middleware{
            otelprovider.NewMiddleware(otelprovider.MiddlewareConfig{}), // OpenTelemetry tracing
        },
    },
})

يمتد البرنامج الوسيط مع سمات بما في ذلك:

gen_ai.provider.name — اسم الموفر (على سبيل المثال، "openai")
gen_ai.agent.id — المعرف الفريد للعامل
gen_ai.agent.name — اسم عرض العامل
gen_ai.agent.description — وصف العامل

Tip

راجع النموذج الكامل للحصول على مثال كامل قابل للتشغيل.

استخدام إمكانية المراقبة مع Harness Agent

بالنسبة إلى عامل عادي، أضف OpenTelemetry إلى مسار عميل الدردشة أو العامل باستخدام UseOpenTelemetry أو WithOpenTelemetry، كما هو موضح سابقا. HarnessAgent يضيف كلا من أدوات عميل الدردشة والعامل OpenTelemetry بشكل افتراضي:

using Microsoft.Agents.AI;
using OpenTelemetry;
using OpenTelemetry.Trace;

const string SourceName = "MyApplication.Harness";

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(SourceName)
    .AddOtlpExporter()
    .Build();

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    OpenTelemetrySourceName = SourceName,
});

OpenTelemetrySourceName يقيم افتراضيا إلى Experimental.Microsoft.Agents.AI. يجب أن يتطابق الاسم الذي تم تمريره إلى AddSource . قم بتعيين DisableOpenTelemetry = true لحذف كل من طبقات الأجهزة المضافة من Harness.

يقوم Harness بتكوين الأجهزة، ولكنك لا تزال تمتلك TracerProvider، والمصدرين، وبيانات الاعتماد، والمسح، وإيقاف التشغيل. لا تقم مسبقا باستخدام نفس عميل الدردشة ثم اترك Harness instrumentation ممكنا ما لم تكن تريد عن قصد فترات مكررة.

يحتوي القياس عن بعد على بيانات تعريف بشكل افتراضي. يؤدي تعيين OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true أيضا إلى تسجيل المطالبات والاستجابات ووسيطات الأدوات ونتائج الأدوات؛ فقط تمكينها عندما يكون نهج المصدر والاستبقاء مناسبا لتلك البيانات.

HarnessAgent متوفر من الحزمة Microsoft.Agents.AI.Harness .

تتضمن المثيلات العادية Agent بالفعل طبقة القياس عن بعد؛ تكوين موفري بيانات تتبع الاستخدام المفتوحة والمصدرين باستخدام configure_otel_providers() أو إعداد OpenTelemetry SDK الخاص بك. create_harness_agent يستخدم نفس التكوين العمومي ويعين اسم موفر خاص ب Harness:

from agent_framework import create_harness_agent
from agent_framework.observability import configure_otel_providers

configure_otel_providers()

agent = create_harness_agent(
    client=client,
    otel_provider_name="my.application.harness",
)

otel_provider_name يتحكم في اسم الموفر المسجل على بيانات تتبع الاستخدام Harness. يتم تعيينه افتراضيا إلى microsoft.agent_framework.harness؛ لا يقوم بتكوين وجهة مصدر أو بيانات تتبع الاستخدام. يتم تمكين تقرير عن حالة النظام بشكل افتراضي، ويتم تعطيل التقاط البيانات الحساسة بشكل افتراضي، ولا يتم تثبيت أي مصدر أو تكوينه تلقائيا.

موفرو OpenTelemetry هم موارد على مستوى العملية. قم بتكوينها مرة واحدة، وتأمين بيانات اعتماد المصدر ونقاط النهاية، ومسحها أو إيقاف تشغيلها وفقا ل OpenTelemetry SDK والمصدر الذي حددته. تعيين ENABLE_INSTRUMENTATION=false أو استدعاء disable_instrumentation() عند تعطيل بيانات تتبع الاستخدام. يؤدي التمكين ENABLE_SENSITIVE_DATA إلى إضافة الرسائل البسيطة ووسيطات الأدوات ونتائج الأدوات.

create_harness_agent تم إصداره في agent-framework-core.

لا تتوفر حاليا حزمة Go Harness. قم بتكوين البرنامج الوسيط OpenTelemetry مباشرة على عامل Go عادي كما هو موضح سابقا.

الخطوات التالية

مهارات العامل

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-08-31

قابلية الرصد

تكامل OpenTelemetry

تمكين إمكانية المراقبة (C#)

الإعداد

Traces

المقاييس

Logs

لوحة معلومات تطمح

الشروع في العمل

التبعيات

الحزم المضمنة

المصدرين

تمكين إمكانية المراقبة (Python)

نشر تتبع MCP

خمسة أنماط لتكوين إمكانية الملاحظة

1. متغيرات بيئة القياس المفتوح القياسية (مستحسن)

2. المصدرون المخصصون

3. إعداد جهة خارجية

4. الإعداد اليدوي

5. تقرير عن حالة النظام التلقائي (رمز صفري)

استخدام أدوات التتبع والعدادات

متغيرات البيئة

متغيرات بيئة القياس المفتوح القياسية

إعداد Microsoft Foundry

ثبّت حزمة azure-monitor-opentelemetry.

تكوين إمكانية المراقبة مباشرة من FoundryChatClient

تكوين azure monitor وتمكين الأجهزة اختياريا

لوحة معلومات تطمح

إعداد لوحة معلومات Aspire باستخدام Docker

تكوين التطبيق الخاص بك

الامتدادات والمقاييس

مثال على إخراج التتبع

Samples

مثال كامل

إمكانية المراقبة باستخدام OpenTelemetry

الإعداد

إضافة البرنامج الوسيط إلى وكيلك

استخدام إمكانية المراقبة مع Harness Agent

الخطوات التالية

الملاحظات

الموارد الإضافية

ثبّت حزمة `azure-monitor-opentelemetry`.

تكوين إمكانية المراقبة مباشرة من `FoundryChatClient`