Bagikan melalui

Observability

Pengamatan adalah aspek utama dalam membangun sistem yang andal dan dapat dipertahankan. Agent Framework menyediakan dukungan bawaan untuk pengamatan, memungkinkan Anda memantau perilaku agen Anda.

Panduan ini akan memandu Anda melalui langkah-langkah untuk memungkinkan pengamatan dengan Agent Framework untuk membantu Anda memahami performa agen Anda dan mendiagnosis masalah apa pun yang mungkin muncul.

Integrasi OpenTelemetry

Agent Framework terintegrasi dengan OpenTelemetry, dan lebih khusus lagi Agent Framework memancarkan jejak, log, dan metrik sesuai dengan Konvensi Semantik OpenTelemetry GenAI.

Aktifkan Observabilitas (C#)

Untuk mengaktifkan pengamatan untuk klien obrolan Anda, Anda perlu membangun klien obrolan sebagai berikut:

// Using the Azure OpenAI client as an example
var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: "MyApplication", configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Untuk mengaktifkan pengamatan untuk agen Anda, Anda perlu membangun agen sebagai berikut:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
).WithOpenTelemetry(sourceName: "MyApplication", enableSensitiveData: true);    // Enable OpenTelemetry instrumentation with sensitive data

Penting

Saat mengaktifkan pengamatan untuk klien dan agen obrolan, Anda mungkin melihat informasi duplikat, terutama saat data sensitif diaktifkan. Konteks obrolan (termasuk perintah dan respons) yang diambil oleh klien obrolan dan agen akan disertakan dalam kedua rentang. Bergantung pada kebutuhan Anda, Anda dapat memilih untuk mengaktifkan pengamatan hanya pada klien obrolan atau hanya pada agen untuk menghindari duplikasi. Lihat Konvensi Semantik GenAI untuk detail selengkapnya tentang atribut yang diambil untuk LLM dan Agen.

Nota

Hanya aktifkan data sensitif dalam lingkungan pengembangan atau pengujian, karena mungkin mengekspos informasi pengguna dalam log dan jejak produksi. Data sensitif mencakup perintah, respons, argumen panggilan fungsi, dan hasil.

Konfigurasi

Sekarang setelah klien dan agen obrolan Anda diinstrumentasikan, Anda dapat mengonfigurasi pengekspor OpenTelemetry untuk mengirim data telemetri ke backend yang Anda inginkan.

Tanda-tanda

Untuk mengekspor jejak ke backend yang diinginkan, Anda dapat mengonfigurasi OpenTelemetry SDK dalam kode startup aplikasi Anda. Misalnya, untuk mengekspor jejak ke sumber daya Azure Monitor:

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

var SourceName = "MyApplication";

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)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Petunjuk / Saran

Bergantung pada backend, Anda dapat menggunakan eksportir yang berbeda. Untuk informasi selengkapnya, lihat dokumentasi OpenTelemetry .NET. Untuk pengembangan lokal, pertimbangkan untuk menggunakan Dasbor Aspire.

Metrics

Demikian pula, untuk mengekspor metrik ke backend yang diinginkan, Anda dapat mengonfigurasi OpenTelemetry SDK dalam kode startup aplikasi Anda. Misalnya, untuk mengekspor metrik ke sumber daya 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)
    .AddMeter("*Microsoft.Agents.AI") // Agent Framework metrics
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Catatan

Log diambil melalui kerangka kerja pengelogan yang Anda gunakan, misalnya Microsoft.Extensions.Logging. Untuk mengekspor log ke sumber daya Azure Monitor, Anda dapat mengonfigurasi penyedia pengelogan dalam kode startup aplikasi Anda:

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>();

Dasbor Aspire

Pertimbangkan untuk menggunakan Dasbor Aspire sebagai cara cepat untuk memvisualisasikan jejak dan metrik Anda selama pengembangan. Untuk Mempelajari selengkapnya, lihat Dokumentasi Dasbor Aspire. Dasbor Aspire menerima data melalui OpenTelemetry Collector, yang dapat Anda tambahkan ke penyedia pelacak Anda sebagai berikut:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Memulai Langkah Pertama

Lihat contoh lengkap agen dengan OpenTelemetry yang diaktifkan di repositori Kerangka Kerja Agen.

Dependensi

Paket yang disertakan

Untuk mengaktifkan pengamatan di aplikasi Python Anda, paket OpenTelemetry berikut diinstal secara default:

Eksportir

Kami tidak menginstal pengekspor secara default untuk mencegah dependensi yang tidak perlu dan potensi masalah dengan instrumentasi otomatis. Ada banyak eksportir yang tersedia untuk backend yang berbeda, sehingga Anda dapat memilih yang paling sesuai dengan kebutuhan Anda.

Beberapa pengekspor umum yang mungkin ingin Anda instal berdasarkan kebutuhan Anda:

  • Untuk dukungan protokol gRPC: instal opentelemetry-exporter-otlp-proto-grpc
  • Untuk dukungan protokol HTTP: instal opentelemetry-exporter-otlp-proto-http
  • Untuk Azure Application Insights: instal azure-monitor-opentelemetry

Gunakan OpenTelemetry Registry untuk menemukan lebih banyak pengekspor dan paket instrumentasi.

Aktifkan Observability (Python)

Lima pola untuk mengonfigurasi pengamatan

Kami telah mengidentifikasi beberapa cara untuk mengonfigurasi pengamatan dalam aplikasi Anda, tergantung pada kebutuhan Anda:

Pendekatan paling sederhana - konfigurasikan semuanya melalui variabel lingkungan:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Atau jika Anda hanya ingin pengekspor konsol:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Pengekspor Kustom

Untuk kontrol lebih atas eksportir, buat sendiri dan berikan ke 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. Penyiapan pihak ketiga

Banyak paket OpenTelemetry pihak ketiga memiliki metode penyiapannya sendiri. Anda dapat menggunakan metode tersebut terlebih dahulu, lalu memanggil enable_instrumentation() untuk mengaktifkan jalur kode instrumentasi Kerangka Kerja Agen:

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)

Untuk 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. Penyiapan manual

Untuk kontrol penuh, Anda dapat menyiapkan pengekspor, penyedia, dan instrumentasi secara manual. Gunakan fungsi create_resource() pembantu untuk membuat sumber daya dengan nama dan versi layanan yang sesuai. Lihat dokumentasi OpenTelemetry Python untuk panduan terperinci tentang instrumentasi manual.

5. Instrumentasi otomatis (kode nol)

Gunakan alat OpenTelemetry CLI untuk melengkapi aplikasi Anda secara otomatis tanpa perubahan kode:

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

Lihat dokumentasi Python OpenTelemetry Zero-code untuk informasi selengkapnya.

Menggunakan pelacak dan meter

Setelah pengamatan dikonfigurasi, Anda dapat membuat rentang atau metrik kustom:

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"})

Ini adalah pembungkus API OpenTelemetry yang mengembalikan pelacak atau meter dari penyedia global, dengan agent_framework ditetapkan sebagai nama pustaka instrumentasi secara default.

Variabel lingkungan

Variabel lingkungan berikut mengontrol pengamatan Agent Framework:

  • ENABLE_INSTRUMENTATION - Defaultnya adalah false, diatur ke true untuk mengaktifkan instrumentasi OpenTelemetry.
  • ENABLE_SENSITIVE_DATA - Defaultnya adalah false, atur ke true untuk mengaktifkan pengelogan data sensitif (perintah, respons, argumen panggilan fungsi, dan hasil). Berhati-hatilah dengan pengaturan ini karena mungkin mengekspos data sensitif.
  • ENABLE_CONSOLE_EXPORTERS - Defaultnya adalah false, diatur ke true untuk mengaktifkan output konsol untuk telemetri.
  • VS_CODE_EXTENSION_PORT - Port untuk integrasi ekstensi AI Toolkit atau Azure AI Foundry VS Code.

Nota

Informasi sensitif mencakup perintah, respons, dan banyak lagi, dan hanya boleh diaktifkan dalam lingkungan pengembangan atau pengujian. Tidak disarankan untuk mengaktifkan ini dalam produksi karena dapat mengekspos data sensitif.

Variabel lingkungan OpenTelemetry Standar

Fungsi ini configure_otel_providers() secara otomatis membaca variabel lingkungan OpenTelemetry standar:

Konfigurasi OTLP (untuk Dasbor Aspire, Jaeger, dll.):

  • OTEL_EXPORTER_OTLP_ENDPOINT - Titik akhir dasar untuk semua sinyal (misalnya, http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Titik akhir khusus jejak (menimpa basis)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Titik akhir khusus metrik (basis penimpaan)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Titik akhir khusus log (menggantikan basis)
  • OTEL_EXPORTER_OTLP_PROTOCOL - Protokol untuk digunakan (grpc atau http, default: grpc)
  • OTEL_EXPORTER_OTLP_HEADERS - Header untuk semua sinyal (misalnya, key1=value1,key2=value2)

Identifikasi Layanan:

  • OTEL_SERVICE_NAME - Nama layanan (default: agent_framework)
  • OTEL_SERVICE_VERSION - Versi layanan (default: versi paket)
  • OTEL_RESOURCE_ATTRIBUTES - Atribut sumber daya tambahan

Lihat spesifikasi OpenTelemetry untuk detail selengkapnya.

Penyiapan Microsoft Foundry

Microsoft Foundry memiliki dukungan bawaan untuk melacak dengan visualisasi untuk rentang Anda.

Pastikan Anda memiliki Foundry yang dikonfigurasi dengan instans Azure Monitor, lihat detailnya

Instal paket azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Konfigurasikan observabilitas langsung dari AzureAIClient:

Untuk proyek Azure AI Foundry, Anda dapat mengonfigurasi observabilitas langsung dari AzureAIClient:

from agent_framework.azure import AzureAIClient
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with (
        AzureCliCredential() as credential,
        AIProjectClient(endpoint="https://<your-project>.foundry.azure.com", credential=credential) as project_client,
        AzureAIClient(project_client=project_client) as client,
    ):
        # Automatically configures Azure Monitor with connection string from project
        await client.configure_azure_monitor(enable_live_metrics=True)

Petunjuk / Saran

Argumen untuk client.configure_azure_monitor() diteruskan ke fungsi yang mendasar configure_azure_monitor() dari azure-monitor-opentelemetry paket, lihat dokumentasi untuk detailnya, kami mengurus pengaturan string koneksi dan sumber daya.

Konfigurasikan azure monitor dan aktifkan instrumentasi secara opsional:

Untuk proyek AI non-Azure dengan Application Insights, pastikan Anda menyiapkan agen kustom di Foundry, lihat detailnya.

Kemudian jalankan agen Anda dengan ID agen OpenTelemetry yang sama seperti yang terdaftar di Foundry, dan konfigurasikan azure monitor sebagai berikut:

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 = ChatAgent(
    chat_client=...,
    name="My Agent",
    instructions="You are a helpful assistant.",
    id="<OpenTelemetry agent ID>"
)
# use the agent as normal

Dasbor Aspire

Untuk pengembangan lokal tanpa penyiapan Azure, Anda dapat menggunakan Dasbor Aspire, yang berjalan secara lokal melalui Docker dan memberikan pengalaman tampilan telemetri yang sangat baik.

Menyiapkan Dasbor Aspire dengan 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

Perintah ini akan memulai dasbor dengan:

  • UI Web: Tersedia di http://localhost:18888
  • Titik akhir OTLP: Tersedia untuk http://localhost:4317 aplikasi Anda untuk mengirim data telemetri

Mengonfigurasi aplikasi Anda

Atur variabel lingkungan berikut:

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

Atau sertakan dalam file Anda .env dan jalankan sampel Anda.

Setelah sampel Anda selesai berjalan, navigasikan ke http://localhost:18888 di browser web untuk melihat data telemetri. Ikuti panduan eksplorasi Dasbor Aspire untuk mengautentikasi ke dasbor dan mulai menjelajahi jejak, log, dan metrik Anda.

Rentang dan metrik

Setelah semuanya diatur, Anda akan mulai melihat rentang dan metrik yang dibuat secara otomatis untuk Anda, rentangnya adalah:

  • invoke_agent <agent_name>: Ini adalah rentang tingkat atas untuk setiap pemanggilan agen, itu akan berisi semua rentang lain sebagai anak-anak.
  • chat <model_name>: Rentang ini dibuat ketika agen memanggil model obrolan yang mendasar, itu akan berisi perintah dan respons sebagai atribut, jika enable_sensitive_data diatur ke True.
  • execute_tool <function_name>: Rentang ini dibuat ketika agen memanggil alat fungsi, itu akan berisi argumen fungsi dan hasilnya sebagai atribut, jika enable_sensitive_data diatur ke True.

Metrik yang dibuat adalah:

  • Untuk klien obrolan dan chat operasi:

    • gen_ai.client.operation.duration (histogram): Metrik ini mengukur durasi setiap operasi, dalam hitungan detik.
    • gen_ai.client.token.usage (histogram): Metrik ini mengukur penggunaan token, dalam jumlah token.

  • Untuk pemanggilan fungsi selama execute_tool operasi:

    • agent_framework.function.invocation.duration (histogram): Metrik ini mengukur durasi setiap eksekusi fungsi, dalam hitungan detik.

Contoh output pelacakan

Saat menjalankan agen dengan pengamatan diaktifkan, Anda akan melihat data pelacakan yang mirip dengan output konsol berikut:

{
    "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.system": "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
    }
}

Jejak ini menunjukkan:

  • Pengidentifikasi pelacakan dan rentang: Untuk menghubungkan operasi terkait
  • Informasi waktu: Saat operasi dimulai dan berakhir
  • Metadata agen: ID Agen, nama, dan instruksi
  • Informasi model: Sistem AI yang digunakan (OpenAI) dan ID respons
  • Penggunaan token: Jumlah token input dan output untuk pelacakan biaya

Samples

Ada sejumlah sampel di repositori microsoft/agent-framework yang menunjukkan kemampuan ini. Untuk informasi selengkapnya, lihat folder sampel pengamatan. Folder itu mencakup sampel untuk menggunakan telemetri nol kode juga.

  • Last updated on