Observability

Observerbarhet är en viktig aspekt av att skapa tillförlitliga och underhållsbara system. Agent Framework tillhandahåller inbyggt stöd för observerbarhet, så att du kan övervaka agenternas beteende.

Den här guiden vägleder dig genom stegen för att aktivera observerbarhet med Agent Framework för att hjälpa dig att förstå hur dina agenter utför och diagnostisera eventuella problem som kan uppstå.

OpenTelemetry-integrering

Agent Framework integreras med OpenTelemetry, och mer specifikt genererar Agent Framework spårningar, loggar och mått enligt OpenTelemetry GenAI Semantic Conventions.

Aktivera observerbarhet (C#)

För att aktivera observerbarhet för chattklienten måste du skapa chattklienten på följande sätt:

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

Om du vill aktivera observerbarhet för din agent måste du skapa agenten på följande sätt:

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

Viktigt!

När du aktiverar observerbarhet för chattklienter och agenter kan du se duplicerad information, särskilt när känsliga data är aktiverade. Chattkontexten (inklusive frågor och svar) som samlas in av både chattklienten och agenten kommer att ingå i båda intervallen. Beroende på dina behov kan du välja att endast aktivera observerbarhet på chattklienten eller bara på agenten för att undvika duplicering. Mer information om de attribut som samlas in för LLM och agenter finns i GenAI-semantiska konventioner .

Anmärkning

Aktivera endast känsliga data i utvecklings- eller testmiljöer, eftersom de kan exponera användarinformation i produktionsloggar och spårningar. Känsliga data innehåller frågor, svar, argument för funktionsanrop och resultat.

Konfiguration

Nu när chattklienten och agenten är instrumenterade kan du konfigurera OpenTelemetry-exportörerna så att de skickar telemetridata till önskad serverdel.

Spårningar

Om du vill exportera spårningar till önskad serverdel kan du konfigurera OpenTelemetry SDK i programmets startkod. Om du till exempel vill exportera spårningar till en Azure Monitor-resurs:

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

Tips/Råd

Beroende på serverdelen kan du använda olika exportörer. Mer information finns i OpenTelemetry .NET-dokumentationen . För lokal utveckling bör du överväga att använda Aspire-instrumentpanelen.

Metrics

Om du vill exportera mått till önskad serverdel kan du konfigurera OpenTelemetry SDK i programmets startkod. Om du till exempel vill exportera mått till en Azure Monitor-resurs:

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

Loggfiler

Loggar registreras via det loggningsramverk som du använder, till exempel Microsoft.Extensions.Logging. Om du vill exportera loggar till en Azure Monitor-resurs kan du konfigurera loggningsprovidern i programmets startkod:

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 Kontrollpanel

Överväg att använda Aspire-instrumentpanelen som ett snabbt sätt att visualisera dina spårningar och mått under utvecklingen. Mer information finns i Dokumentation om Aspire-instrumentpanelen. Aspire-instrumentpanelen tar emot data via en OpenTelemetry Collector, som du kan lägga till i spårningsprovidern på följande sätt:

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

Komma igång

Se ett fullständigt exempel på en agent med OpenTelemetry aktiverat på Agent Framework-lagringsplatsen.

Beroenden

Inkluderade paket

För att aktivera observerbarhet i python-programmet installeras följande OpenTelemetry-paket som standard:

Exportörer

Vi installerar inte exportörer som standard för att förhindra onödiga beroenden och potentiella problem med automatisk instrumentering. Det finns en mängd olika exportörer tillgängliga för olika serverdelar, så du kan välja de som passar bäst för dina behov.

Några vanliga exportörer som du kanske vill installera baserat på dina behov:

För stöd för gRPC-protokoll: installera opentelemetry-exporter-otlp-proto-grpc
För HTTP-protokollstöd: installera opentelemetry-exporter-otlp-proto-http
För Azure Application Insights: installera azure-monitor-opentelemetry

Använd OpenTelemetry Registry för att hitta fler exportörer och instrumentationspaket.

Aktivera observerbarhet (Python)

Fem mönster för att konfigurera observerbarhet

Vi har identifierat flera sätt att konfigurera observerbarhet i ditt program, beroende på dina behov:

1. Standardvariabler för OpenTelemetry-miljö (rekommenderas)

Den enklaste metoden – konfigurera allt via miljövariabler:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Eller om du bara vill ha konsolexportörer:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Anpassade exportörer

Om du vill ha mer kontroll över exportörerna skapar du dem själv och skickar dem till 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. Installation från tredje part

Många OpenTelemetry-paket från tredje part har egna installationsmetoder. Du kan använda dessa metoder först och sedan anropa enable_instrumentation() för att aktivera Agent Framework-instrumentationskodsökvägar:

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. Manuell installation

För fullständig kontroll kan du konfigurera exportörer, leverantörer och instrumentation manuellt. Använd hjälpfunktionen create_resource() för att skapa en resurs med rätt tjänstnamn och version. Mer information om manuell instrumentering finns i Dokumentationen om OpenTelemetry Python .

5. Automatisk instrumentering (nollkod)

Använd CLI-verktyget OpenTelemetry för att automatiskt instrumentera ditt program utan kodändringar:

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

Mer information finns i OpenTelemetry Zero-code Python-dokumentationen .

Använda spårnings- och mätare

När observerbarheten har konfigurerats kan du skapa anpassade intervall eller mått:

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

Det här är omslutningar av OpenTelemetry-API:et som returnerar en spårning eller mätare från den globala providern, med agent_framework inställt som instrumentationsbibliotekets namn som standard.

Miljövariabler

Följande miljövariabler styr agentramverkets observerbarhet:

ENABLE_INSTRUMENTATION – Standardvärdet är false, inställt på för att true aktivera OpenTelemetry-instrumentation.
ENABLE_SENSITIVE_DATA – Standardvärdet är false, inställt på för att true aktivera loggning av känsliga data (prompter, svar, funktionsanropsargument och resultat). Var försiktig med den här inställningen eftersom den kan exponera känsliga data.
ENABLE_CONSOLE_EXPORTERS – Standardvärdet är false, inställt på för att true aktivera konsolutdata för telemetri.
VS_CODE_EXTENSION_PORT – Port för AI Toolkit- eller Azure AI Foundry VS Code-tilläggsintegrering.

Anmärkning

Känslig information omfattar frågor, svar med mera och bör endast aktiveras i utvecklings- eller testmiljöer. Vi rekommenderar inte att du aktiverar detta i produktion eftersom det kan exponera känsliga data.

Standardvariabler för OpenTelemetry-miljö

Funktionen configure_otel_providers() läser automatiskt standardvariabler för OpenTelemetry-miljön:

OTLP-konfiguration (för Aspire Dashboard, Jaeger osv.):

OTEL_EXPORTER_OTLP_ENDPOINT - Basslutpunkt för alla signaler (t.ex. http://localhost:4317)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT – Spårningsspecifik slutpunkt (åsidosätter bas)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT – Måttspecifik slutpunkt (åsidosätter bas)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT – Loggspecifik slutpunkt (åsidosätter bas)
OTEL_EXPORTER_OTLP_PROTOCOL - Protokoll att använda (grpc eller http, standard: grpc)
OTEL_EXPORTER_OTLP_HEADERS - Rubriker för alla signaler (t.ex. key1=value1,key2=value2)

Tjänstidentifiering:

OTEL_SERVICE_NAME – Tjänstnamn (standard: agent_framework)
OTEL_SERVICE_VERSION – Tjänstversion (standard: paketversion)
OTEL_RESOURCE_ATTRIBUTES – Ytterligare resursattribut

Mer information finns i OpenTelemetry-specifikationen .

Installation av Microsoft Foundry

Microsoft Foundry har inbyggt stöd för spårning med visualisering för dina spann.

Kontrollera att din Foundry har konfigurerats med en Azure Monitor-instans, se information

Installera `azure-monitor-opentelemetry`-paketet:

pip install azure-monitor-opentelemetry

Konfigurera observerbarhet direkt från `AzureAIClient`:

För Azure AI Foundry-projekt kan du konfigurera observerbarhet direkt från 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)

Tips/Råd

Argumenten för client.configure_azure_monitor() skickas vidare till den underliggande configure_azure_monitor() funktionen från azure-monitor-opentelemetry paketet, se dokumentationen för mer information, vi tar hand om att ange anslutningssträngen och resursen.

Konfigurera Azure Monitor och aktivera instrumentation som valfritt:

För ai-projekt som inte är Azure-projekt med Application Insights kontrollerar du att du konfigurerar en anpassad agent i Foundry. Mer information finns i .

Kör sedan din agent med samma OpenTelemetry-agent-ID som registrerat i Foundry och konfigurera Azure Monitor på följande sätt:

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 Kontrollpanel

För lokal utveckling utan Azure-konfiguration kan du använda Aspire-instrumentpanelen som körs lokalt via Docker och ger en utmärkt telemetrivisningsupplevelse.

Konfigurera Aspire Dashboard med 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

Då startas instrumentpanelen med:

Webbgränssnitt: Finns på http://localhost:18888
OTLP-slutpunkt: Tillgänglig för http://localhost:4317 dina program för att skicka telemetridata

Konfigurera ditt program

Ange följande miljövariabler:

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

Eller inkludera dem i .env filen och kör exemplet.

När exemplet är klart går du till http://localhost:18888 i en webbläsare för att se telemetridata. Följ utforskningsguiden för Aspire Dashboard för att autentisera till instrumentpanelen och börja utforska dina spårningar, loggar och mått.

Intervall och mått

När allt har konfigurerats kommer du att börja se intervall och mått som skapas automatiskt åt dig. Intervallen är:

invoke_agent <agent_name>: Det här är det översta intervallet för varje agentanrop, det kommer att innehålla alla andra intervall som underordnade.
chat <model_name>: Det här intervallet skapas när agenten anropar den underliggande chattmodellen, den innehåller prompten och svaret som attribut, om enable_sensitive_data är inställt på True.
execute_tool <function_name>: Det här intervallet skapas när agenten anropar ett funktionsverktyg, den innehåller funktionsargumenten och resultatet som attribut, om enable_sensitive_data är inställt på True.

De mått som skapas är:

För chattklienten och chat -åtgärderna:
- gen_ai.client.operation.duration (histogram): Det här måttet mäter varaktigheten för varje åtgärd i sekunder.
- gen_ai.client.token.usage (histogram): Det här måttet mäter tokenanvändningen i antal token.
För funktionsanrop under execute_tool åtgärderna:
- agent_framework.function.invocation.duration (histogram): Det här måttet mäter varaktigheten för varje funktionskörning i sekunder.

Exempel på spårningsutdata

När du kör en agent med observerbarhet aktiverat visas spårningsdata som liknar följande konsolutdata:

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

Den här spårningen visar:

Spårnings- och span-ID: För korrelering av relaterade åtgärder
Tidsinformation: När åtgärden startades och avslutades
Agentmetadata: Agent-ID, namn och instruktioner
Modellinformation: AI-systemet som används (OpenAI) och svars-ID
Tokenanvändning: Antal indata- och utdatatoken för kostnadsspårning

Samples

Vi har ett antal exempel på vår lagringsplats som demonstrerar dessa funktioner, se mappen observability samples (observerbarhetsexempel ) på Github. Det inkluderar exempel för att använda nollkodstelemetri också.

Feedback

Var den här sidan till hjälp?

Last updated on 2025-12-17

Dela via

Observability

OpenTelemetry-integrering

Aktivera observerbarhet (C#)

Konfiguration

Spårningar

Metrics

Loggfiler

Aspire Kontrollpanel

Komma igång

Beroenden

Inkluderade paket

Exportörer

Aktivera observerbarhet (Python)

Fem mönster för att konfigurera observerbarhet

1. Standardvariabler för OpenTelemetry-miljö (rekommenderas)

2. Anpassade exportörer

3. Installation från tredje part

4. Manuell installation

5. Automatisk instrumentering (nollkod)

Använda spårnings- och mätare

Miljövariabler

Standardvariabler för OpenTelemetry-miljö

Installation av Microsoft Foundry

Installera azure-monitor-opentelemetry-paketet:

Konfigurera observerbarhet direkt från AzureAIClient:

Konfigurera Azure Monitor och aktivera instrumentation som valfritt:

Aspire Kontrollpanel

Konfigurera Aspire Dashboard med Docker

Konfigurera ditt program

Intervall och mått

Exempel på spårningsutdata

Samples

Feedback

Ytterligare resurser

Installera `azure-monitor-opentelemetry`-paketet:

Konfigurera observerbarhet direkt från `AzureAIClient`: