Udostępnij przez

Observability

Obserwacja jest kluczowym aspektem tworzenia niezawodnych i konserwowalnych systemów. Struktura agentów zapewnia wbudowaną obsługę obserwacji, umożliwiając monitorowanie zachowania agentów.

Ten przewodnik przeprowadzi Cię przez kroki umożliwiające obserwowanie za pomocą platformy Agent Framework, aby ułatwić zrozumienie, jak agenci wykonują i diagnozują wszelkie problemy, które mogą wystąpić.

Integracja biblioteki OpenTelemetry

Struktura agenta integruje się z platformą OpenTelemetry, a dokładniej z platformą Agent Framework emituje ślady, dzienniki i metryki zgodnie z konwencjami semantycznymi GenAI OpenTelemetry GenAI.

Włącz możliwość obserwowania (C#)

Aby umożliwić obserwowanie klienta czatu, należy skompilować klienta czatu w następujący sposób:

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

Aby umożliwić obserwowanie agenta, należy skompilować agenta w następujący sposób:

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

Ważne

Jeśli włączysz możliwość obserwowania dla klientów czatów i agentów, mogą pojawić się zduplikowane informacje, szczególnie w przypadku włączenia poufnych danych. Kontekst czatu (w tym monity i odpowiedzi), który jest przechwytywany zarówno przez klienta czatu, jak i agenta zostanie uwzględniony w obu zakresach. W zależności od potrzeb możesz włączyć możliwość obserwowania tylko na kliencie czatu lub tylko na agencie, aby uniknąć duplikowania. Aby uzyskać więcej informacji na temat atrybutów przechwyconych dla usługi LLM i agentów, zobacz Konwencje semantyczne GenAI .

Uwaga / Notatka

Włączaj tylko poufne dane w środowiskach deweloperskich lub testowych, ponieważ mogą ujawniać informacje o użytkowniku w dziennikach produkcyjnych i śladach. Dane poufne obejmują monity, odpowiedzi, argumenty wywołania funkcji i wyniki.

Konfiguracja

Teraz, gdy klient czatu i agent są instrumentowani, możesz skonfigurować eksporterów OpenTelemetry, aby wysyłać dane telemetryczne do żądanego zaplecza.

Traces

Aby wyeksportować ślady do żądanego zaplecza, możesz skonfigurować zestaw OPENTelemetry SDK w kodzie uruchamiania aplikacji. Aby na przykład wyeksportować ślady do zasobu usługi 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();

Wskazówka

W zależności od zaplecza możesz użyć różnych eksporterów, zobacz dokumentację platformy .NET OpenTelemetry , aby uzyskać więcej informacji. W przypadku programowania lokalnego rozważ użycie pulpitu nawigacyjnego Aspirującego.

Metrics

Podobnie, aby wyeksportować metryki do żądanego zaplecza, możesz skonfigurować zestaw SDK OpenTelemetry w kodzie uruchamiania aplikacji. Aby na przykład wyeksportować metryki do zasobu usługi 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();

Dzienniki

Dzienniki są przechwytywane za pośrednictwem używanej platformy rejestrowania, na przykład Microsoft.Extensions.Logging. Aby wyeksportować dzienniki do zasobu usługi Azure Monitor, możesz skonfigurować dostawcę rejestrowania w kodzie uruchamiania aplikacji:

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 kokpit

Rozważ użycie pulpitu nawigacyjnego Aspirującego jako szybkiego sposobu wizualizacji śladów i metryk podczas opracowywania. Aby dowiedzieć się więcej, zobacz dokumentację pulpitu nawigacyjnego aspirującego. Pulpit nawigacyjny Aspiruje odbiera dane za pośrednictwem modułu zbierającego OpenTelemetry, który można dodać do dostawcy śledzenia w następujący sposób:

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

Wprowadzenie

Zobacz pełny przykład agenta z włączoną funkcją OpenTelemetry w repozytorium Agent Framework.

Zależności

Dołączone pakiety

Aby umożliwić obserwowanie w aplikacji języka Python, następujące pakiety OpenTelemetry są instalowane domyślnie:

Eksporterów

Domyślnie nie instalujemy eksporterów, aby zapobiec niepotrzebnym zależnościom i potencjalnym problemom z instrumentacją automatyczną. Istnieje wiele eksporterów dostępnych dla różnych zapleczy, dzięki czemu można wybrać te, które najlepiej pasują do Twoich potrzeb.

Niektórzy typowi eksporterzy, którzy mogą chcieć zainstalować na podstawie Twoich potrzeb:

  • W przypadku obsługi protokołu gRPC: zainstaluj opentelemetry-exporter-otlp-proto-grpc
  • W przypadku obsługi protokołu HTTP: instalowanie opentelemetry-exporter-otlp-proto-http
  • W przypadku usługi Azure Application Insights: instalowanie azure-monitor-opentelemetry

Użyj rejestru OpenTelemetry , aby znaleźć więcej eksporterów i pakietów instrumentacji.

Włącz możliwość obserwowania (Python)

Pięć wzorców konfigurowania obserwacji

Zidentyfikowaliśmy wiele sposobów konfigurowania wglądu w aplikację w zależności od potrzeb:

Najprostsze podejście — konfigurowanie wszystkich elementów za pomocą zmiennych środowiskowych:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Lub jeśli chcesz tylko eksporterów konsoli:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Eksporterzy niestandardowi

Aby uzyskać większą kontrolę nad eksporterami, utwórz je samodzielnie i przekaż je do :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. Konfiguracja innej firmy

Wiele pakietów OpenTelemetry innych firm ma własne metody konfiguracji. Możesz najpierw użyć tych metod, a następnie wywołać metodę enable_instrumentation() aktywowania ścieżek kodu instrumentacji struktury agenta:

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)

Dla 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. Ręczna konfiguracja

Aby uzyskać pełną kontrolę, możesz ręcznie skonfigurować eksporterów, dostawców i instrumentację. Użyj funkcji create_resource() pomocnika, aby utworzyć zasób z odpowiednią nazwą usługi i wersją. Szczegółowe wskazówki dotyczące instrumentacji ręcznej można znaleźć w dokumentacji języka Python openTelemetry .

5. Automatyczna instrumentacja (kod zerowy)

Użyj narzędzia interfejsu wiersza polecenia OpenTelemetry , aby automatycznie instrumentować aplikację bez zmian kodu:

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

Aby uzyskać więcej informacji, zobacz dokumentację języka Python zero-code openTelemetry .

Używanie śladów i mierników

Po skonfigurowaniu możliwości obserwacji można utworzyć niestandardowe zakresy lub metryki:

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

Są to otoki interfejsu API OpenTelemetry, który domyślnie zwraca element tracer lub miernik od dostawcy globalnego z agent_framework ustawioną nazwą biblioteki instrumentacji.

Zmienne środowiskowe

Następujące zmienne środowiskowe kontrolują możliwość obserwowania struktury agentów:

  • ENABLE_INSTRUMENTATION — wartość domyślna to false, aby true włączyć instrumentację OpenTelemetry.
  • ENABLE_SENSITIVE_DATA — wartość domyślna to false, aby true włączyć rejestrowanie poufnych danych (monity, odpowiedzi, argumenty wywołania funkcji i wyniki). Należy zachować ostrożność przy użyciu tego ustawienia, ponieważ może uwidaczniać poufne dane.
  • ENABLE_CONSOLE_EXPORTERS — Wartość domyślna to false, aby true włączyć dane wyjściowe konsoli dla danych telemetrycznych.
  • VS_CODE_EXTENSION_PORT — Port dla zestawu narzędzi AI Toolkit lub integracji rozszerzenia programu VS Code z usługą Azure AI Foundry.

Uwaga / Notatka

Informacje poufne obejmują monity, odpowiedzi i nie tylko i powinny być włączone tylko w środowiskach deweloperskich lub testowych. Nie zaleca się włączania tej funkcji w środowisku produkcyjnym, ponieważ może to spowodować ujawnienie poufnych danych.

Standardowe zmienne środowiskowe OpenTelemetry

Funkcja configure_otel_providers() automatycznie odczytuje standardowe zmienne środowiskowe OpenTelemetry:

Konfiguracja OTLP (dla pulpitu nawigacyjnego Aspirującego, Jaegera itp.):

  • OTEL_EXPORTER_OTLP_ENDPOINT - Podstawowy punkt końcowy dla wszystkich sygnałów (np. http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Punkt końcowy specyficzny dla śledzenia (zastępuje bazę)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT — Punkt końcowy specyficzny dla metryk (podstawy przesłonięć)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT — Punkt końcowy specyficzny dla dzienników (zastępuje bazę)
  • OTEL_EXPORTER_OTLP_PROTOCOL - Protokół do użycia (grpc lub http, wartość domyślna: grpc)
  • OTEL_EXPORTER_OTLP_HEADERS - Nagłówki dla wszystkich sygnałów (np. key1=value1,key2=value2)

Identyfikacja usługi:

  • OTEL_SERVICE_NAME - Nazwa usługi (wartość domyślna: agent_framework)
  • OTEL_SERVICE_VERSION — Wersja usługi (domyślna: wersja pakietu)
  • OTEL_RESOURCE_ATTRIBUTES - Dodatkowe atrybuty zasobów

Aby uzyskać więcej informacji , zobacz specyfikację OpenTelemetry .

Konfiguracja rozwiązania Microsoft Foundry

Platforma Microsoft Foundry ma wbudowaną obsługę śledzenia za pomocą wizualizacji dla Twoich zakresów.

Upewnij się, że masz skonfigurowaną usługę Foundry z wystąpieniem usługi Azure Monitor, zobacz szczegóły

azure-monitor-opentelemetry Zainstaluj pakiet:

pip install azure-monitor-opentelemetry

Skonfiguruj możliwość obserwowania bezpośrednio z poziomu elementu AzureAIClient:

W przypadku projektów usługi Azure AI Foundry można skonfigurować możliwość obserwacji bezpośrednio z poziomu elementu 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)

Wskazówka

Argumenty dla client.configure_azure_monitor() elementu są przekazywane do funkcji bazowej configure_azure_monitor()azure-monitor-opentelemetry z pakietu, zobacz dokumentację , aby uzyskać szczegółowe informacje, zajmujemy się ustawianiem parametrów połączenia i zasobu.

Skonfiguruj usługę Azure Monitor i opcjonalnie włącz instrumentację:

W przypadku projektów spoza platformy Azure AI w usłudze Application Insights upewnij się, że skonfigurowaliśmy agenta niestandardowego w narzędziu Foundry, zobacz szczegóły.

Następnie uruchom agenta z tym samym identyfikatorem agenta OpenTelemetry co zarejestrowany w rozwiązaniu Foundry i skonfiguruj usługę Azure Monitor w następujący sposób:

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

Aspire kokpit

W przypadku programowania lokalnego bez konfiguracji platformy Azure możesz użyć pulpitu nawigacyjnego Aspirującego , który działa lokalnie za pośrednictwem platformy Docker i zapewnia doskonałe środowisko wyświetlania danych telemetrycznych.

Konfigurowanie pulpitu nawigacyjnego Aspirującego przy użyciu platformy 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

Spowoduje to uruchomienie pulpitu nawigacyjnego z następującymi elementami:

  • Internetowy interfejs użytkownika: dostępny pod adresem http://localhost:18888
  • Punkt końcowy OTLP: dostępny dla http://localhost:4317 aplikacji do wysyłania danych telemetrycznych

Konfigurowanie aplikacji

Ustaw następujące zmienne środowiskowe:

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

Możesz też dołączyć je do .env pliku i uruchomić przykład.

Po zakończeniu działania przykładu przejdź do http://localhost:18888 witryny w przeglądarce internetowej, aby wyświetlić dane telemetryczne. Postępuj zgodnie z przewodnikiem eksploracji pulpitu nawigacyjnego Aspiruj , aby uwierzytelnić się na pulpicie nawigacyjnym i rozpocząć eksplorowanie śladów, dzienników i metryk.

Zakresy i metryki

Po skonfigurowaniu wszystkiego zaczniesz widzieć zakresy i metryki tworzone automatycznie, zakresy są następujące:

  • invoke_agent <agent_name>: Jest to zakres najwyższego poziomu dla każdego wywołania agenta, który będzie zawierać wszystkie pozostałe zakresy jako elementy podrzędne.
  • chat <model_name>: Ten zakres jest tworzony, gdy agent wywołuje bazowy model czatu, będzie zawierać monit i odpowiedź jako atrybuty, jeśli enable_sensitive_data ustawiono wartość True.
  • execute_tool <function_name>: Ten zakres jest tworzony, gdy agent wywołuje narzędzie funkcji, będzie zawierać argumenty funkcji i wynik jako atrybuty, jeśli enable_sensitive_data jest ustawiona na True.

Tworzone metryki to:

  • W przypadku klienta czatu i chat operacji:

    • gen_ai.client.operation.duration (histogram): Ta metryka mierzy czas trwania każdej operacji w sekundach.
    • gen_ai.client.token.usage (histogram): Ta metryka mierzy użycie tokenu w liczbie tokenów.

  • W przypadku wywołania funkcji podczas execute_tool operacji:

    • agent_framework.function.invocation.duration (histogram): Ta metryka mierzy czas trwania każdego wykonania funkcji w sekundach.

Przykładowe dane wyjściowe śledzenia

Po uruchomieniu agenta z włączoną możliwością obserwowania zobaczysz dane śledzenia podobne do następujących danych wyjściowych konsoli:

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

Ten ślad pokazuje:

  • Identyfikatory śledzenia i zakresu: w celu korelowania powiązanych operacji
  • Informacje o chronometrażu: kiedy operacja została uruchomiona i zakończona
  • Metadane agenta: identyfikator agenta, nazwa i instrukcje
  • Informacje o modelu: używany system sztucznej inteligencji (OpenAI) i identyfikator odpowiedzi
  • Użycie tokenu: liczba tokenów wejściowych i wyjściowych na potrzeby śledzenia kosztów

Samples

Mamy kilka przykładów w naszym repozytorium, które demonstrują te możliwości, zobacz folder przykłady możliwości obserwowania w witrynie GitHub. Obejmuje to również przykłady dotyczące używania telemetrii zero-code.

  • Last updated on