Delen via

Observability

Waarneembaarheid is een belangrijk aspect van het bouwen van betrouwbare en onderhoudbare systemen. Agent Framework biedt ingebouwde ondersteuning voor waarneembaarheid, zodat u het gedrag van uw agents kunt bewaken.

In deze handleiding wordt u begeleid bij de stappen voor het inschakelen van waarneembaarheid met Agent Framework, zodat u begrijpt hoe uw agents presteren en eventuele problemen diagnosticeren.

Integratie van OpenTelemetry

Agent Framework kan worden geïntegreerd met OpenTelemetry en met name Agent Framework verzendt traceringen, logboeken en metrische gegevens volgens de Semantische Conventies van OpenTelemetry GenAI.

Waarneembaarheid inschakelen (C#)

Als u waarneembaarheid voor uw chatclient wilt inschakelen, moet u de chatclient als volgt bouwen:

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

Als u waarneembaarheid voor uw agent wilt inschakelen, moet u de agent als volgt bouwen:

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

Belangrijk

Wanneer u waarneembaarheid inschakelt voor uw chatclients en agents, ziet u mogelijk dubbele informatie, met name wanneer gevoelige gegevens zijn ingeschakeld. De chatcontext (inclusief prompts en antwoorden) die door zowel de chatclient als de agent wordt vastgelegd, wordt opgenomen in beide bereiken. Afhankelijk van uw behoeften kunt u ervoor kiezen om alleen waarneembaarheid in te schakelen op de chatclient of alleen op de agent om duplicatie te voorkomen. Zie de Semantische Conventies van GenAI voor meer informatie over de kenmerken die zijn vastgelegd voor LLM en agents.

Opmerking

Schakel gevoelige gegevens alleen in in ontwikkel- of testomgevingen, omdat gebruikersgegevens mogelijk worden weergegeven in productielogboeken en traceringen. Gevoelige gegevens omvatten prompts, antwoorden, argumenten voor functieoproep en resultaten.

Configuratie

Nu uw chatclient en -agent zijn geïnstrueerd, kunt u de OpenTelemetry-exporteurs configureren om de telemetriegegevens naar de gewenste back-end te verzenden.

Sporen

Als u traceringen naar de gewenste back-end wilt exporteren, kunt u de OpenTelemetry SDK configureren in de opstartcode van uw toepassing. Als u bijvoorbeeld traceringen wilt exporteren naar een Azure Monitor-resource:

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

Aanbeveling

Afhankelijk van uw back-end kunt u verschillende exporteurs gebruiken. Zie de OpenTelemetry .NET-documentatie voor meer informatie. Voor lokale ontwikkeling kunt u overwegen om het Aspire Dashboard te gebruiken.

Metrics

Als u metrische gegevens naar de gewenste back-end wilt exporteren, kunt u de OpenTelemetry SDK configureren in de opstartcode van uw toepassing. Als u bijvoorbeeld metrische gegevens wilt exporteren naar een Azure Monitor-resource:

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

Logboeken worden vastgelegd via het logboekregistratieframework dat u gebruikt, bijvoorbeeld Microsoft.Extensions.Logging. Als u logboeken wilt exporteren naar een Azure Monitor-resource, kunt u de logboekprovider configureren in de opstartcode van uw toepassing:

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

Ambidashboard

Overweeg om het Aspire Dashboard te gebruiken als een snelle manier om uw traceringen en metrische gegevens tijdens de ontwikkeling te visualiseren. Zie de documentatie van Het Dashboard van Aspire voor meer informatie. Het Aspire Dashboard ontvangt gegevens via een OpenTelemetry Collector, die u als volgt kunt toevoegen aan uw tracerprovider:

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

Aan de slag

Bekijk een volledig voorbeeld van een agent waarvoor OpenTelemetry is ingeschakeld in de agentframeworkopslagplaats.

Afhankelijkheden

Meegeleverde pakketten

Als u waarneembaarheid in uw Python-toepassing wilt inschakelen, worden de volgende OpenTelemetry-pakketten standaard geïnstalleerd:

Exporteurs

We installeren geen exporteurs standaard om onnodige afhankelijkheden en potentiële problemen met automatische instrumentatie te voorkomen. Er is een grote verscheidenheid aan exporteurs beschikbaar voor verschillende back-ends, zodat u de exporteurs kunt kiezen die het beste bij uw behoeften passen.

Sommige algemene exporteurs die u mogelijk wilt installeren op basis van uw behoeften:

  • Voor gRPC-protocolondersteuning: installeren opentelemetry-exporter-otlp-proto-grpc
  • Voor http-protocolondersteuning: installeren opentelemetry-exporter-otlp-proto-http
  • Voor Azure Application Insights: installeren azure-monitor-opentelemetry

Gebruik het OpenTelemetry Registry om meer exporteurs en instrumentatiepakketten te vinden.

Waarneembaarheid inschakelen (Python)

Vijf patronen voor het configureren van waarneembaarheid

We hebben verschillende manieren geïdentificeerd om waarneembaarheid in uw toepassing te configureren, afhankelijk van uw behoeften:

De eenvoudigste aanpak: configureer alles via omgevingsvariabelen:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Of als u alleen consoleexporteurs wilt:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Aangepaste exporteurs

Voor meer controle over de exporteurs, maak ze zelf en geef ze door aan 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. Installatie van derden

Veel OpenTelemetry-pakketten van derden hebben hun eigen installatiemethoden. U kunt deze methoden eerst gebruiken en vervolgens aanroepen enable_instrumentation() om agent framework-instrumentatiecodepaden te activeren:

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)

Voor 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. Handmatige installatie

Voor volledige controle kunt u handmatig exporteurs, providers en instrumentatie instellen. Gebruik de helperfunctie create_resource() om een resource te maken met de juiste servicenaam en -versie. Zie de Documentatie voor OpenTelemetry Python voor gedetailleerde richtlijnen over handmatige instrumentatie.

5. Automatische instrumentatie (nulcode)

Gebruik het hulpprogramma OpenTelemetry CLI om uw toepassing automatisch te instrumenteren zonder codewijzigingen:

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

Zie de Python-documentatie van OpenTelemetry Zero-code voor meer informatie.

Tracers en meters gebruiken

Zodra waarneembaarheid is geconfigureerd, kunt u aangepaste spans of metrische gegevens maken:

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

Dit zijn wrappers van de OpenTelemetry-API die een tracer of meter retourneren van de globale provider, waarbij agent_framework deze standaard is ingesteld als de naam van de instrumentatiebibliotheek.

Omgevingsvariabelen

De volgende omgevingsvariabelen bepalen de waarneembaarheid van Agent Framework:

  • ENABLE_INSTRUMENTATION - De standaardwaarde is falseingesteld om true OpenTelemetry-instrumentatie in te schakelen.
  • ENABLE_SENSITIVE_DATA - De standaardwaarde is falseingesteld om logboekregistratie van gevoelige gegevens in te true schakelen (prompts, antwoorden, argumenten voor functieoproep en resultaten). Wees voorzichtig met deze instelling, omdat gevoelige gegevens mogelijk worden weergegeven.
  • ENABLE_CONSOLE_EXPORTERS - De standaardwaarde is falseingesteld om console-uitvoer voor telemetrie in te true schakelen.
  • VS_CODE_EXTENSION_PORT - Poort voor AI Toolkit of Integratie van Azure AI Foundry VS Code-extensie.

Opmerking

Gevoelige informatie omvat prompts, antwoorden en meer, en mag alleen worden ingeschakeld in ontwikkel- of testomgevingen. Het wordt niet aanbevolen om dit in productie in te schakelen, omdat gevoelige gegevens mogelijk worden weergegeven.

Omgevingsvariabelen van Standard OpenTelemetry

De configure_otel_providers() functie leest automatisch standaard omgevingsvariabelen van OpenTelemetry:

OTLP-configuratie (voor Aspire Dashboard, Jaeger, enzovoort):

  • OTEL_EXPORTER_OTLP_ENDPOINT - Basiseindpunt voor alle signalen (bijvoorbeeld http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Traceringen-specifiek eindpunt (overschrijft basis)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Metrische gegevensspecifiek eindpunt (overschrijft basis)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Logboekspecifiek eindpunt (overschrijft basis)
  • OTEL_EXPORTER_OTLP_PROTOCOL - Protocol dat moet worden gebruikt (grpc of http, standaard): grpc)
  • OTEL_EXPORTER_OTLP_HEADERS - Kopteksten voor alle signalen (bijvoorbeeld key1=value1,key2=value2)

Serviceidentificatie:

  • OTEL_SERVICE_NAME - Servicenaam (standaard: agent_framework)
  • OTEL_SERVICE_VERSION - Serviceversie (standaard: pakketversie)
  • OTEL_RESOURCE_ATTRIBUTES - Aanvullende resourcekenmerken

Zie de OpenTelemetry-specificatie voor meer informatie.

Installatie van Microsoft Foundry

Microsoft Foundry biedt ingebouwde ondersteuning voor tracering met visualisatie voor uw spans.

Zorg ervoor dat uw Foundry is geconfigureerd met een Azure Monitor-exemplaar. Zie de details

Installeer het azure-monitor-opentelemetry-pakket:

pip install azure-monitor-opentelemetry

Configureer de waarneembaarheid rechtstreeks vanuit het AzureAIClientvolgende:

Voor Azure AI Foundry-projecten kunt u waarneembaarheid rechtstreeks vanuit het AzureAIClientvolgende configureren:

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)

Aanbeveling

De argumenten voor client.configure_azure_monitor() worden doorgegeven aan de onderliggende configure_azure_monitor() functie uit het azure-monitor-opentelemetry pakket, raadpleeg de documentatie voor meer informatie, we zorgen voor het instellen van de verbindingsreeks en resource.

Configureer Azure Monitor en schakel eventueel instrumentatie in:

Voor niet-Azure AI-projecten met Application Insights moet u een aangepaste agent instellen in Foundry, zie de details.

Voer vervolgens uw agent uit met dezelfde OpenTelemetry-agent-id als geregistreerd in Foundry en configureer Azure Monitor als volgt:

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

Ambidashboard

Voor lokale ontwikkeling zonder Azure-installatie kunt u het Aspire Dashboard gebruiken, dat lokaal wordt uitgevoerd via Docker en een uitstekende telemetrieweergave biedt.

Aspire Dashboard instellen met 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

Met deze opdracht wordt het dashboard gestart met:

  • Webgebruikersinterface: beschikbaar op http://localhost:18888
  • OTLP-eindpunt: beschikbaar voor http://localhost:4317 uw toepassingen voor het verzenden van telemetriegegevens

Uw toepassing configureren

Stel de volgende omgevingsvariabelen in:

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

U kunt ze ook opnemen in uw .env bestand en het voorbeeld uitvoeren.

Zodra het voorbeeld is uitgevoerd, gaat u naar http://localhost:18888 een webbrowser om de telemetriegegevens te bekijken. Volg de verkenningshandleiding van Het Aspire Dashboard om u te verifiëren bij het dashboard en uw traceringen, logboeken en metrische gegevens te verkennen.

Spans en metrische gegevens

Zodra alles is ingesteld, ziet u dat spans en metrische gegevens automatisch voor u worden gemaakt, de spans zijn:

  • invoke_agent <agent_name>: Dit is het hoogste niveau voor elke aanroep van de agent, deze bevat alle andere spanten als onderliggende items.
  • chat <model_name>: Deze periode wordt gemaakt wanneer de agent het onderliggende chatmodel aanroept, bevat deze de prompt en het antwoord als kenmerken, indien enable_sensitive_data ingesteld op True.
  • execute_tool <function_name>: Deze periode wordt gemaakt wanneer de agent een functiehulpprogramma aanroept, bevat deze de functieargumenten en het resultaat als kenmerken, als enable_sensitive_data deze is ingesteld op True.

De metrische gegevens die worden gemaakt, zijn:

  • Voor de chatclient en chat -bewerkingen:

    • gen_ai.client.operation.duration (histogram): Met deze metrische waarde wordt de duur van elke bewerking in seconden meten.
    • gen_ai.client.token.usage (histogram): Met deze metrische waarde wordt het tokengebruik meten in het aantal tokens berekend.

  • Voor functie-aanroep tijdens de execute_tool bewerkingen:

    • agent_framework.function.invocation.duration (histogram): Met deze metrische waarde wordt de duur van elke uitvoering van de functie in seconden meten.

Voorbeeld van traceringsuitvoer

Wanneer u een agent uitvoert waarvoor waarneembaarheid is ingeschakeld, ziet u traceringsgegevens die vergelijkbaar zijn met de volgende console-uitvoer:

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

Deze tracering toont:

  • Tracerings- en span-id's: voor het correleren van gerelateerde bewerkingen
  • Tijdsinstellingen: Wanneer de bewerking is gestart en beëindigd
  • Metagegevens van agent: agent-id, naam en instructies
  • Modelinformatie: Het AI-systeem dat wordt gebruikt (OpenAI) en de antwoord-id
  • Tokengebruik: het aantal invoer- en uitvoertoken voor het bijhouden van kosten

Samples

Er zijn een aantal voorbeelden in de microsoft/agent-framework opslagplaats die deze mogelijkheden demonstreren. Zie de map waarneembaarheidsvoorbeelden voor meer informatie. Deze map bevat ook voorbeelden voor het gebruik van telemetrie met nulcode.

  • Last updated on