Megosztás:

Observability

A megfigyelhetőség kulcsfontosságú eleme a megbízható és karbantartható rendszerek kiépítésének. Az Agent Framework beépített támogatást nyújt a megfigyelhetőséghez, lehetővé téve az ügynökök viselkedésének monitorozását.

Ez az útmutató végigvezeti az Agent Framework megfigyelhetőségének engedélyezésének lépésein, hogy megértse, hogyan végzik az ügynökök az ügynököket, és diagnosztizálja az esetlegesen felmerülő problémákat.

OpenTelemetry-integráció

Az Agent Framework integrálható az OpenTelemetria szolgáltatással, és pontosabban az Agent Framework az OpenTelemetria GenAI szemantikai konvenciók szerint bocsát ki nyomkövetéseket, naplókat és metrikákat.

Megfigyelhetőség engedélyezése (C#)

A csevegőügyfél megfigyelhetőségének engedélyezéséhez a következő módon kell létrehoznia a csevegőügyfélt:

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

Az ügynök megfigyelhetőségének engedélyezéséhez az alábbiak szerint kell létrehoznia az ügynököt:

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

Fontos

Ha engedélyezi a megfigyelhetőséget a csevegési ügyfelek és ügynökök számára, ismétlődő információkat láthat, különösen akkor, ha a bizalmas adatok engedélyezve van. A csevegőügyfél és az ügynök által rögzített csevegési környezet (beleértve a parancssorokat és a válaszokat is) mindkét tartomány része lesz. Az igényeitől függően dönthet úgy, hogy csak a csevegési ügyfélen vagy csak az ügynökön engedélyezi a megfigyelhetőséget a duplikációk elkerülése érdekében. Az LLM-hez és az ügynökökhöz rögzített attribútumokról további információt a GenAI szemantikai konvencióiban talál.

Megjegyzés:

Csak a fejlesztési vagy tesztelési környezetekben engedélyezze a bizalmas adatokat, mivel felhasználói adatokat tehet közzé az éles naplókban és nyomkövetésekben. A bizalmas adatok közé tartoznak a parancssorok, válaszok, függvényhívási argumentumok és eredmények.

Konfiguráció

Most, hogy a csevegőügyfél és az ügynök rendszerezett, konfigurálhatja az OpenTelemetry-exportőröket, hogy a telemetriaadatokat a kívánt háttérrendszerbe küldjék.

Nyomok

Ha nyomkövetéseket szeretne exportálni a kívánt háttérrendszerbe, konfigurálhatja az OpenTelemetry SDK-t az alkalmazás indítási kódjában. Nyomkövetések exportálása például egy Azure Monitor-erőforrásba:

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

Jótanács

A háttérrendszertől függően különböző exportőröket használhat. További információkért tekintse meg az OpenTelemetry .NET dokumentációját. A helyi fejlesztéshez fontolja meg az Aspire irányítópult használatát.

Mértékek

Hasonlóképpen, ha metrikákat szeretne exportálni a kívánt háttérrendszerbe, konfigurálhatja az OpenTelemetry SDK-t az alkalmazás indítási kódjában. Például metrikák exportálása egy Azure Monitor-erőforrásba:

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

Naplók

A naplók rögzítése a használt naplózási keretrendszeren keresztül történik, például Microsoft.Extensions.Logging. Ha naplókat szeretne exportálni egy Azure Monitor-erőforrásba, konfigurálhatja a naplózási szolgáltatót az alkalmazás indítási kódjában:

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 irányítópult

Fontolja meg az Aspire-irányítópult használatát a nyomkövetések és metrikák gyors megjelenítéséhez a fejlesztés során. További információkért tekintse meg az Aspire irányítópult dokumentációját. Az Aspire irányítópult egy OpenTelemetry Collectoren keresztül fogadja az adatokat, amelyeket az alábbiak szerint adhat hozzá a nyomkövetési szolgáltatóhoz:

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

Kezdő lépések

Tekintse meg az Ügynök keretrendszer adattárában engedélyezett OpenTelemetry-t tartalmazó ügynök teljes példáját.

Függőségek

Belefoglalt csomagok

A Python-alkalmazásban a megfigyelhetőség engedélyezéséhez alapértelmezés szerint a következő OpenTelemetry-csomagok vannak telepítve:

Exportőrök

Alapértelmezés szerint nem telepítünk exportőröket a szükségtelen függőségek és az automatikus rendszerállapot esetleges problémáinak elkerülése érdekében. Számos különböző exportőr áll rendelkezésre a különböző háttérrendszerekhez, így kiválaszthatja az igényeinek leginkább megfelelőket.

Néhány gyakori exportőr, amelyeket igény szerint érdemes telepíteni:

  • A gRPC protokoll támogatásához: telepítés opentelemetry-exporter-otlp-proto-grpc
  • HTTP protokoll támogatása esetén: telepítés opentelemetry-exporter-otlp-proto-http
  • Azure Application Insights esetén: telepítés azure-monitor-opentelemetry

Az OpenTelemetry Registry használatával további exportőröket és rendszerállapot-csomagokat kereshet.

Megfigyelhetőség engedélyezése (Python)

Öt minta a megfigyelhetőség konfigurálásához

Több módszert is azonosítottunk a megfigyelhetőség konfigurálására az alkalmazásban az igényeitől függően:

A legegyszerűbb megközelítés – mindent konfiguráljon környezeti változókon keresztül:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Vagy ha csak konzolexportálókra van szüksége:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Egyéni exportőrök

Az exportőrök feletti nagyobb ellenőrzés érdekében hozza létre őket saját maga, és adja át őket a következőnek 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. Harmadik fél beállítása

Számos külső OpenTelemetry-csomag saját beállítási módszerekkel rendelkezik. Először ezeket a metódusokat használhatja, majd meghívhatja enable_instrumentation() az Agent Framework rendszerállapotkód-elérési útjait:

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)

Langfuse esetén:

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. Manuális beállítás

A teljes ellenőrzéshez manuálisan állíthatja be az exportőröket, a szolgáltatókat és a rendszerezést. A segédfüggvény create_resource() használatával hozzon létre egy erőforrást a megfelelő szolgáltatásnévvel és verzióval. A manuális kialakítással kapcsolatos részletes útmutatásért tekintse meg az OpenTelemetry Python dokumentációját .

5. Automatikus rendszerezés (nulla kód)

Az OpenTelemetry CLI eszközzel kódmódosítások nélkül automatikusan eszközzé alakíthatja az alkalmazást:

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

További információt az OpenTelemetry Zero-code Python dokumentációjában talál.

Jelölők és mérők használata

A megfigyelhetőség konfigurálása után egyéni tartományok vagy metrikák hozhatók létre:

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

Ezek az OpenTelemetry API burkolói, amelyek egy jelölőt vagy mérőt adnak vissza a globális szolgáltatótól, agent_framework és alapértelmezés szerint a rendszerállapot-kódtár neveként vannak beállítva.

Környezeti változók

A következő környezeti változók szabályozzák az Ügynök-keretrendszer megfigyelhetőségét:

  • ENABLE_INSTRUMENTATION - Az alapértelmezett beállítás falseaz OpenTelemetry-rendszerállapot engedélyezésére true van beállítva.
  • ENABLE_SENSITIVE_DATA - Az alapértelmezett beállítás falsea bizalmas adatok (parancssorok, válaszok, függvényhívási argumentumok és eredmények) naplózásának engedélyezésére van beállítva true . Legyen óvatos ezzel a beállítással, mert bizalmas adatokat tehet közzé.
  • ENABLE_CONSOLE_EXPORTERS - Az alapértelmezett beállítás falsea konzol kimenetének engedélyezésére van beállítva true a telemetriai adatokhoz.
  • VS_CODE_EXTENSION_PORT - Port for AI Toolkit vagy Azure AI Foundry VS Code extension integration.

Megjegyzés:

A bizalmas információk közé tartoznak a kérések, válaszok és egyebek, és csak fejlesztési vagy tesztelési környezetekben engedélyezettek. Ezt nem ajánlott éles környezetben engedélyezni, mert bizalmas adatokat tehet közzé.

Standard OpenTelemetry környezeti változók

A configure_otel_providers() függvény automatikusan felolvassa a standard OpenTelemetry környezeti változókat:

OTLP-konfiguráció (Aspire-irányítópulthoz, Jaegerhez stb.):

  • OTEL_EXPORTER_OTLP_ENDPOINT - Alapvégpont az összes jelhez (pl. http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Nyomkövetés-specifikus végpont (felülbírálások alapja)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Metrikaspecifikus végpont (felülbírálások alapja)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Naplóspecifikus végpont (felülbírálások alapja)
  • OTEL_EXPORTER_OTLP_PROTOCOL - Használandó protokoll (grpc vagy httpalapértelmezett: grpc)
  • OTEL_EXPORTER_OTLP_HEADERS - Az összes jel fejléce (pl. key1=value1,key2=value2)

Szolgáltatásazonosítás:

  • OTEL_SERVICE_NAME - Szolgáltatásnév (alapértelmezett: agent_framework)
  • OTEL_SERVICE_VERSION - Szolgáltatás verziója (alapértelmezett: csomagverzió)
  • OTEL_RESOURCE_ATTRIBUTES – További erőforrásattribútumok

További részletekért tekintse meg az OpenTelemetry specifikációt .

A Microsoft Foundry beállítása

A Microsoft Foundry beépített támogatással rendelkezik a vizualizációval való nyomkövetéshez az Ön számára.

Győződjön meg arról, hogy a Foundry konfigurálva van egy Azure Monitor-példánysal, lásd a részleteket

Telepítse a azure-monitor-opentelemetry csomagot:

pip install azure-monitor-opentelemetry

Konfigurálja a megfigyelhetőséget közvetlenül a AzureAIClientkövetkezőből:

Azure AI Foundry-projektek esetén a megfigyelhetőséget közvetlenül a AzureAIClientkövetkezőből konfigurálhatja:

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)

Jótanács

Az argumentumokat a csomagból továbbítjuk az alapul szolgáló client.configure_azure_monitor() függvénynekconfigure_azure_monitor(), a részletekért lásd a azure-monitor-opentelemetrydokumentációt, és gondoskodunk a kapcsolati sztring és az erőforrás beállításáról.

Konfigurálja az Azure Monitort, és opcionálisan engedélyezze a rendszerállapot-beállítást:

Az Application Insights szolgáltatással nem Azure-beli AI-projektek esetén győződjön meg arról, hogy egyéni ügynököt állít be a Foundryben, lásd a részleteket.

Ezután futtassa az ügynököt ugyanazzal az OpenTelemetry-ügynökazonosítóval , mint a Foundryben, és konfigurálja az Azure Monitort az alábbiak szerint:

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 irányítópult

Az Azure beállítása nélküli helyi fejlesztéshez használhatja az Aspire irányítópultot, amely helyileg fut a Dockeren keresztül, és kiváló telemetriamegtekintési élményt nyújt.

Az Aspire-irányítópult beállítása a Dockerrel

# 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

Ez a parancs a következő paranccsal indítja el az irányítópultot:

  • Webes felhasználói felület: itt érhető el: http://localhost:18888
  • OTLP-végpont: Elérhető az http://localhost:4317 alkalmazások számára telemetriai adatok küldéséhez

Az alkalmazás konfigurálása

Állítsa be a következő környezeti változókat:

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

Vagy vegye fel őket a .env fájlba, és futtassa a mintát.

Ha a minta futása befejeződött, lépjen http://localhost:18888 egy webböngészőbe a telemetriai adatok megtekintéséhez. Kövesse az Aspire irányítópult feltárási útmutatóját az irányítópulton való hitelesítéshez, és kezdje el felderíteni a nyomkövetéseket, naplókat és metrikákat.

Spans and metrics

Ha minden be van állítva, látni fogja, hogy automatikusan létrejönnek a spanok és a metrikák, a spanok a következők:

  • invoke_agent <agent_name>: Ez az ügynökhívások legfelső szintű tartománya, amely gyermekként tartalmazza az összes többi spant.
  • chat <model_name>: Ez a span akkor jön létre, amikor az ügynök meghívja a mögöttes csevegőmodellt, attribútumként fogja tartalmazni a parancssort és a választ, ha enable_sensitive_data a beállítás értéke True.
  • execute_tool <function_name>: Ez a span akkor jön létre, amikor az ügynök függvényeszközt hív meg, a függvényargumentumokat és az eredményt attribútumként fogja tartalmazni, ha enable_sensitive_data a beállítás értéke True.

A létrehozott metrikák a következők:

  • A csevegőügyfél és chat a műveletek esetében:

    • gen_ai.client.operation.duration (hisztogram): Ez a metrika az egyes műveletek időtartamát méri másodpercben.
    • gen_ai.client.token.usage (hisztogram): Ez a metrika a jogkivonatok használatát méri a tokenek számában.

  • Függvényhívás esetén a execute_tool műveletek során:

    • agent_framework.function.invocation.duration (hisztogram): Ez a metrika az egyes függvények végrehajtásának időtartamát méri másodpercben.

Példa nyomkövetési kimenetre

Ha olyan ügynököt futtat, amelynél engedélyezve van a megfigyelhetőség, a következő konzolkimenethez hasonló nyomkövetési adatokat fog látni:

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

Ez a nyomkövetés a következőt mutatja:

  • Nyomkövetési és átnyúlási azonosítók: Kapcsolódó műveletek korrelációja esetén
  • Időzítési információk: Amikor a művelet elindult és befejeződött
  • Ügynök metaadatai: Ügynök azonosítója, neve és utasításai
  • Modellinformációk: A használt AI-rendszer (OpenAI) és válaszazonosító
  • Tokenhasználat: Bemeneti és kimeneti jogkivonatok száma a költségkövetéshez

Samples

Az adattárban számos minta mutatja be ezeket a microsoft/agent-framework képességeket. További információt a megfigyelhetőségi minták mappájában talál. Ez a mappa a nulla kódú telemetriai adatok használatára szolgáló mintákat is tartalmaz.

  • Last updated on