Observierbarkeit

Observability aktivieren (C#)

Um die Observability für Ihren Chatclient zu aktivieren, müssen Sie den Chatclient wie folgt erstellen:

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

Um die Observability für Ihren Agent zu aktivieren, müssen Sie den Agent wie folgt erstellen:

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

Konfiguration

Nachdem Der Chatclient und der Agent instrumentiert wurden, können Sie die OpenTelemetry-Exporter so konfigurieren, dass die Telemetriedaten an ihr gewünschtes Back-End gesendet werden.

Ablaufverfolgungen

Um Ablaufverfolgungen in das gewünschte Back-End zu exportieren, können Sie das OpenTelemetry SDK in Ihrem Anwendungsstartcode konfigurieren. So exportieren Sie beispielsweise Ablaufverfolgungen in eine Azure Monitor-Ressource:

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

Metriken

Ähnlich wie beim Exportieren von Metriken in das gewünschte Back-End können Sie das OpenTelemetry SDK in Ihrem Anwendungsstartcode konfigurieren. So exportieren Sie beispielsweise Metriken in eine Azure Monitor-Ressource:

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

Logs

Protokolle werden über das von Ihnen verwendete Protokollierungsframework erfasst, z. B Microsoft.Extensions.Logging. . Um Protokolle in eine Azure Monitor-Ressource zu exportieren, können Sie den Protokollierungsanbieter in Ihrem Anwendungsstartcode konfigurieren:

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 Dashboard

Erwägen Sie die Verwendung des Aspire-Dashboards als schnelle Möglichkeit, Ihre Ablaufverfolgungen und Metriken während der Entwicklung zu visualisieren. Weitere Informationen finden Sie in der Dokumentation zum Aspire Dashboard. Das Aspire Dashboard empfängt Daten über einen OpenTelemetry Collector, den Sie Ihrem Tracer-Anbieter wie folgt hinzufügen können:

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

Erste Schritte

Sehen Sie sich ein vollständiges Beispiel für einen Agent mit aktiviertem OpenTelemetry im Agent Framework-Repository an.

Abhängigkeiten

Enthaltene Pakete

Um die Observability in Ihrer Python-Anwendung zu aktivieren, werden standardmäßig die folgenden OpenTelemetry-Pakete installiert:

• opentelemetry-api
• opentelemetry-sdk
• opentelemetry-semantic-conventions-ai

Exporteure

Exporteure werden standardmäßig nicht installiert, um unnötige Abhängigkeiten und potenzielle Probleme mit der automatischen Instrumentierung zu verhindern. Es gibt eine vielzahl von Exportern für verschiedene Back-Ends, sodass Sie die für Ihre Anforderungen am besten geeigneten auswählen können.

Einige gängige Exporteure, die Sie basierend auf Ihren Anforderungen installieren möchten:

• Für gRPC-Protokollunterstützung: installieren opentelemetry-exporter-otlp-proto-grpc
• Für HTTP-Protokollunterstützung: installieren opentelemetry-exporter-otlp-proto-http
• Für Azure Application Insights: Installieren azure-monitor-opentelemetry

Verwenden Sie die OpenTelemetry-Registrierung , um weitere Exporter und Instrumentierungspakete zu finden.

Observability aktivieren (Python)

Fünf Muster für die Konfiguration der Observierbarkeit

Je nach Ihren Anforderungen haben wir mehrere Möglichkeiten zum Konfigurieren der Observierbarkeit in Ihrer Anwendung identifiziert:

1. Standard-OpenTelemetry-Umgebungsvariablen (empfohlen)

Der einfachste Ansatz – Alles über Umgebungsvariablen konfigurieren:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Oder wenn Sie nur Konsolenexporteure benötigen:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Benutzerdefinierte Exporteure

Um mehr Kontrolle über die Exporteure zu haben, erstellen Sie sie selbst, und übergeben Sie sie an 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. Einrichtung von Drittanbietern

Viele OpenTelemetry-Pakete von Drittanbietern verfügen über eigene Setupmethoden. Sie können diese Methoden zuerst verwenden und dann aufrufen enable_instrumentation() , um Codepfade der Agent Framework-Instrumentierung zu aktivieren:

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)

Für 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. Manuelle Einrichtung

Zur vollständigen Kontrolle können Sie Exporter, Anbieter und Instrumentierung manuell einrichten. Verwenden Sie die Hilfsfunktion create_resource() , um eine Ressource mit dem entsprechenden Dienstnamen und der entsprechenden Version zu erstellen. Ausführliche Anleitungen zur manuellen Instrumentierung finden Sie in der Dokumentation zu OpenTelemetry Python .

5. Automatische Instrumentierung (Nullcode)

Verwenden Sie das OpenTelemetry CLI-Tool , um Ihre Anwendung automatisch ohne Codeänderungen zu instrumentieren:

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

Weitere Informationen finden Sie in der Python-Dokumentation zu OpenTelemetry Zero-Code .

Verwenden von Tracern und Metern

Sobald die Observability konfiguriert ist, können Sie benutzerdefinierte Spannen oder Metriken erstellen:

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

Hierbei handelt es sich um Wrapper der OpenTelemetry-API, die einen Ablaufverfolgungs- oder Meterwert vom globalen Anbieter zurückgeben, wobei agent_framework standardmäßig der Name der Instrumentationsbibliothek festgelegt ist.

Umgebungsvariablen

Die folgenden Umgebungsvariablen steuern die Observability des Agent Frameworks:

• ENABLE_INSTRUMENTATION - Der Standardwert ist falseauf die Aktivierung der OpenTelemetry-Instrumentierung festgelegt true .
• ENABLE_SENSITIVE_DATA- Der Standardwert ist so festgelegt, dass die true Protokollierung vertraulicher Daten (Eingabeaufforderungen, Antworten, Funktionsaufrufargumente und Ergebnisse) aktiviert wirdfalse. Achten Sie bei dieser Einstellung darauf, da vertrauliche Daten verfügbar gemacht werden können.
• ENABLE_CONSOLE_EXPORTERS - Der Standardwert ist falseauf die Aktivierung der true Konsolenausgabe für Telemetrie festgelegt.
• VS_CODE_EXTENSION_PORT – Port für AI Toolkit oder Azure AI Foundry VS Code Extension Integration.

Standard-OpenTelemetry-Umgebungsvariablen

Die configure_otel_providers() Funktion liest automatisch standardmäßige OpenTelemetry-Umgebungsvariablen:

OTLP-Konfiguration (für Aspire Dashboard, Jaeger usw.):

• OTEL_EXPORTER_OTLP_ENDPOINT - Basisendpunkt für alle Signale (z. B. http://localhost:4317)
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Ablaufverfolgungsspezifischer Endpunkt (Überschreibungsbasis)
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Metrikspezifischer Endpunkt (Überschreibungsbasis)
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Protokollspezifischer Endpunkt (Überschreibungsbasis)
• OTEL_EXPORTER_OTLP_PROTOCOL - Zu verwendende Protokoll (grpc oder http, Standard: grpc)
• OTEL_EXPORTER_OTLP_HEADERS - Kopfzeilen für alle Signale (z. B. key1=value1,key2=value2)

Dienstidentifikation:

• OTEL_SERVICE_NAME - Dienstname (Standard: agent_framework)
• OTEL_SERVICE_VERSION - Dienstversion (Standard: Paketversion)
• OTEL_RESOURCE_ATTRIBUTES - Zusätzliche Ressourcenattribute

Weitere Details finden Sie in der OpenTelemetry-Spezifikation .

Microsoft Foundry-Setup

Microsoft Foundry bietet integrierte Unterstützung für die Ablaufverfolgung mit Visualisierung für Ihre Spanne.

Stellen Sie sicher, dass Ihre Foundry mit einer Azure Monitor-Instanz konfiguriert ist, siehe Details

Installieren Sie das Paket azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Konfigurieren Sie die Observierbarkeit direkt aus dem AzureAIClient:

Für Azure AI Foundry-Projekte können Sie die Observierbarkeit direkt aus den 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)

Konfigurieren sie azure monitor, und aktivieren Sie optional die Instrumentierung:

Stellen Sie sicher, dass Sie einen benutzerdefinierten Agent in Foundry einrichten, um Nicht-Azure AI-Projekte mit Application Insights zu erhalten.

Führen Sie dann Ihren Agent mit derselben OpenTelemetry-Agent-ID wie in Foundry registriert aus, und konfigurieren Sie azure monitor wie folgt:

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 Dashboard

Für die lokale Entwicklung ohne Azure-Setup können Sie das Aspire-Dashboard verwenden, das lokal über Docker ausgeführt wird und eine hervorragende Telemetrieanzeige bietet.

Einrichten des Aspire-Dashboards mit 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

Dadurch wird das Dashboard mit folgenden Aktionen gestartet:

• Web-UI: Verfügbar unter http://localhost:18888
• OTLP-Endpunkt: Verfügbar für http://localhost:4317 Ihre Anwendungen zum Senden von Telemetriedaten

Konfigurieren Der Anwendung

Legen Sie die folgenden Umgebungsvariablen fest:

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

Oder fügen Sie sie in Ihre .env Datei ein, und führen Sie Ihr Beispiel aus.

Nachdem die Ausführung des Beispiels abgeschlossen ist, navigieren Sie http://localhost:18888 zu einem Webbrowser, um die Telemetriedaten anzuzeigen. Folgen Sie dem Explorationshandbuch des Aspire-Dashboards , um sich beim Dashboard zu authentifizieren und ihre Ablaufverfolgungen, Protokolle und Metriken zu untersuchen.

Spannweiten und Metriken

Sobald alles eingerichtet ist, werden Sie mit der Automatischen Erstellung von Spannen und Metriken beginnen, die für Sie erstellt werden, die Spanne sind:

• invoke_agent <agent_name>: Dies ist der Bereich der obersten Ebene für jeden Agentaufruf, er enthält alle anderen Spans als untergeordnete Elemente.
• chat <model_name>: Diese Spanne wird erstellt, wenn der Agent das zugrunde liegende Chatmodell aufruft, es enthält die Eingabeaufforderung und Antwort als Attribute, falls enable_sensitive_data festgelegt True.
• execute_tool <function_name>: Diese Spanne wird erstellt, wenn der Agent ein Funktionstool aufruft, es enthält die Funktionsargumente und das Ergebnis als Attribute, falls enable_sensitive_data festgelegt True.

Die erstellten Metriken sind:

• Für den Chatclient und chat die Vorgänge:

  • gen_ai.client.operation.duration (Histogramm): Diese Metrik misst die Dauer jedes Vorgangs in Sekunden.
  • gen_ai.client.token.usage (Histogramm): Diese Metrik misst die Tokenverwendung in der Anzahl der Token.

• Für Funktionsaufrufe während der execute_tool Vorgänge:

  • agent_framework.function.invocation.duration (Histogramm): Diese Metrik misst die Dauer jeder Funktionsausführung in Sekunden.

Beispiel für die Ablaufverfolgungsausgabe

Wenn Sie einen Agent mit aktivierter Observability ausführen, werden Ablaufverfolgungsdaten ähnlich der folgenden Konsolenausgabe angezeigt:

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

Diese Ablaufverfolgung zeigt:

• Ablaufverfolgungs- und Span-IDs: Zum Korrelieren verwandter Vorgänge
• Anzeigedauerinformationen: Wann der Vorgang gestartet und beendet wurde
• Agentmetadaten: Agent-ID, Name und Anweisungen
• Modellinformationen: Das verwendete KI-System (OpenAI) und die Antwort-ID
• Tokennutzung: Eingabe- und Ausgabetokenanzahl für die Kostennachverfolgung

Beispiele

Wir haben eine Reihe von Beispielen in unserem Repository, die diese Funktionen veranschaulichen, siehe den Ordner "Observability samples" auf Github. Dazu gehören Beispiele für die Verwendung von Zero-Code-Telemetrie.