Observability

Pozorovatelnost je klíčovým aspektem vytváření spolehlivých a udržovatelných systémů. Agent Framework poskytuje integrovanou podporu pozorovatelnosti, která umožňuje monitorovat chování vašich agentů.

Tato příručka vás provede postupem, jak povolit pozorovatelnost pomocí rozhraní Agent Framework, abyste pochopili, jak vaši agenti fungují, a diagnostikovat případné problémy, které by mohly nastat.

Integrace OpenTelemetry

Agent Framework se integruje s OpenTelemetry a konkrétněji Agent Framework generuje trasování, protokoly a metriky podle sémantických konvencí OpenTelemetry GenAI.

Povolení pozorovatelnosti (C#)

Pokud chcete chatovacímu klientovi povolit pozorovatelnost, je potřeba vytvořit chatovacího klienta následujícím způsobem:

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

Pokud chcete pro svého agenta povolit pozorovatelnost, musíte agenta sestavit následujícím způsobem:

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

Důležité

Když povolíte pozorovatelnost pro chatovací klienty a agenty, může se zobrazit duplicitní informace, zejména pokud jsou povolena citlivá data. Kontext chatu (včetně výzev a odpovědí), který zachytí jak chatovací klient, tak agent, bude zahrnut do obou rozsahů. V závislosti na vašich potřebách se můžete rozhodnout povolit pozorovatelnost pouze v chatovacím klientovi nebo jenom v agentu, abyste se vyhnuli duplikaci. Další podrobnosti o atributech zachycených pro LLM a agenty najdete v sémantických konvencích GenAI .

Poznámka:

V vývojových nebo testovacích prostředích povolte jenom citlivá data, protože můžou vystavit informace o uživatelích v produkčních protokolech a trasování. Citlivá data zahrnují výzvy, odpovědi, argumenty volání funkce a výsledky.

Konfigurace

Teď, když je váš chatovací klient a agent instrumentovaný, můžete nakonfigurovat exportéry OpenTelemetry tak, aby odesílaly telemetrická data do požadovaného back-endu.

Trasování

Pokud chcete exportovat trasování do požadovaného back-endu, můžete v spouštěcím kódu aplikace nakonfigurovat sadu OpenTelemetry SDK. Pokud chcete například exportovat trasování do prostředku služby 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();

Návod

V závislosti na vašem back-endu můžete použít různé vývozce. Další informace najdete v dokumentaci k rozhraní .NET OpenTelemetry. Pro místní vývoj zvažte použití řídicího panelu Aspire.

Metrics

Podobně můžete k exportu metrik do požadovaného back-endu nakonfigurovat sadu OpenTelemetry SDK ve spouštěcím kódu aplikace. Pokud chcete například exportovat metriky do prostředku služby 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();

Záznamy

Protokoly se zaznamenávají prostřednictvím rozhraní protokolování, které používáte, například Microsoft.Extensions.Logging. Pokud chcete exportovat protokoly do prostředku služby Azure Monitor, můžete nakonfigurovat zprostředkovatele protokolování ve spouštěcím kódu aplikace:

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

Zvažte použití řídicího panelu Aspire jako rychlého způsobu vizualizace trasování a metrik během vývoje. Další informace najdete v dokumentaci k řídicímu panelu Aspire. Řídicí panel Aspire přijímá data prostřednictvím kolekce OpenTelemetry, kterou můžete přidat k poskytovateli traceru následujícím způsobem:

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

Začínáme

Podívejte se na úplný příklad agenta s povoleným OpenTelemetry v úložišti Agent Framework.

Závislosti

Zahrnuté balíčky

Pokud chcete ve své aplikaci Pythonu povolit pozorovatelnost, nainstalují se ve výchozím nastavení následující balíčky OpenTelemetry:

Vývozci

Ve výchozím nastavení neinstalujeme exportéry, abychom zabránili zbytečným závislostem a potenciálním problémům s automatickým instrumentací. Pro různé back-endy je k dispozici celá řada vývozců, takže si můžete vybrat ty, které nejlépe vyhovují vašim potřebám.

Některé běžné vývozce, které můžete chtít nainstalovat na základě vašich potřeb:

Podpora protokolu gRPC: instalace opentelemetry-exporter-otlp-proto-grpc
Podpora protokolu HTTP: instalace opentelemetry-exporter-otlp-proto-http
Pro Azure Application Insights: instalace azure-monitor-opentelemetry

Pomocí registru OpenTelemetry můžete najít další vývozce a balíčky instrumentace.

Povolení pozorovatelnosti (Python)

Pět vzorů pro konfiguraci pozorovatelnosti

Zjistili jsme několik způsobů konfigurace pozorovatelnosti ve vaší aplikaci v závislosti na vašich potřebách:

1. Standardní proměnné prostředí OpenTelemetry (doporučeno)

Nejjednodušší přístup – konfigurace všeho prostřednictvím proměnných prostředí:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Nebo pokud chcete jenom vývozce konzoly:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Vlastní vývozci

Pro větší kontrolu nad vývozci je vytvořte sami a předejte jim 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. Nastavení třetí strany

Mnoho balíčků OpenTelemetry třetích stran má vlastní metody nastavení. Tyto metody můžete použít nejprve a pak volat enable_instrumentation() aktivaci cest kódu instrumentace agenta Framework:

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)

Pro 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. Ruční nastavení

Pro úplnou kontrolu můžete ručně nastavit vývozce, poskytovatele a instrumentaci. Pomocí pomocné funkce create_resource() vytvořte prostředek s odpovídajícím názvem a verzí služby. Podrobné pokyny k ruční instrumentaci najdete v dokumentaci k OpenTelemetry Pythonu .

5. Automatická instrumentace (bez kódu)

Pomocí nástroje Rozhraní příkazového řádku OpenTelemetry můžete automaticky instrumentovat aplikaci bez změn kódu:

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

Další informace najdete v dokumentaci Pythonu pro OpenTelemetry Zero-code .

Použití trasovacích a měřičů

Po nakonfigurování pozorovatelnosti můžete vytvořit vlastní rozsahy nebo metriky:

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

Jedná se o obálky rozhraní API OpenTelemetry, které vrací trasovací modul nebo měřič od globálního poskytovatele, a agent_framework ve výchozím nastavení je nastavený jako název knihovny instrumentace.

Proměnné prostředí

Následující proměnné prostředí řídí pozorovatelnost agenta Framework:

ENABLE_INSTRUMENTATION – Výchozí hodnota je false, nastavená na true povolení instrumentace OpenTelemetry.
ENABLE_SENSITIVE_DATA – Výchozí hodnota je false, nastavená na true povolení protokolování citlivých dat (výzvy, odpovědi, argumenty volání funkce a výsledky). Při tomto nastavení buďte opatrní, protože může vystavit citlivá data.
ENABLE_CONSOLE_EXPORTERS – Výchozí hodnota je false, nastavená na true povolení výstupu konzoly pro telemetrii.
VS_CODE_EXTENSION_PORT – Port pro integraci rozšíření AI Toolkit nebo Azure AI Foundry VS Code.

Poznámka:

Citlivé informace zahrnují výzvy, odpovědi a další informace a měly by být povoleny pouze ve vývojových nebo testovacích prostředích. Nedoporučujeme to povolit v produkčním prostředí, protože může vystavit citlivá data.

Standardní proměnné prostředí OpenTelemetry

Funkce configure_otel_providers() automaticky čte standardní proměnné prostředí OpenTelemetry:

Konfigurace OTLP (pro řídicí panel Aspire, Jaeger atd.):

OTEL_EXPORTER_OTLP_ENDPOINT - Základní koncový bod pro všechny signály (např. http://localhost:4317)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT – Koncový bod specifický pro trasování (základ přepsání)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT – Koncový bod specifický pro metriky (přepsání základu)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT – Koncový bod specifický pro protokoly (přepsání základu)
OTEL_EXPORTER_OTLP_PROTOCOL - Protokol k použití (grpc nebo http, výchozí: grpc)
OTEL_EXPORTER_OTLP_HEADERS - Hlavičky pro všechny signály (např key1=value1,key2=value2. )

Identifikace služby:

OTEL_SERVICE_NAME – Název služby (výchozí: agent_framework)
OTEL_SERVICE_VERSION – Verze služby (výchozí: verze balíčku)
OTEL_RESOURCE_ATTRIBUTES – Další atributy prostředků

Další podrobnosti najdete v specifikaci OpenTelemetry .

Nastavení Microsoft Foundry

Microsoft Foundry má integrovanou podporu trasování s vizualizací pro vaše rozsahy.

Ujistěte se, že máte ve službě Foundry nakonfigurovanou instanci služby Azure Monitor, prohlédněte si podrobnosti.

Nainstalujte balíček `azure-monitor-opentelemetry`:

pip install azure-monitor-opentelemetry

Konfigurovat pozorovatelnost přímo z `AzureAIClient`:

U projektů Azure AI Foundry můžete konfigurovat pozorovatelnost přímo z AzureAIClientnásledujících možností:

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)

Návod

Argumenty pro client.configure_azure_monitor() předání podkladové configure_azure_monitor() funkci z azure-monitor-opentelemetry balíčku najdete v dokumentaci , kde se postaráme o nastavení připojovacího řetězce a prostředku.

Nakonfigurujte Azure Monitor a volitelně povolte instrumentaci:

V případě projektů mimo Azure AI s Application Insights se ujistěte, že jste v Foundry nastavili vlastního agenta, podívejte se na podrobnosti.

Potom spusťte agenta se stejným ID agenta OpenTelemetry , jaké jste zaregistrovali v Foundry, a nakonfigurujte azure Monitor následujícím způsobem:

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

Pro místní vývoj bez nastavení Azure můžete použít řídicí panel Aspire, který běží místně prostřednictvím Dockeru a poskytuje vynikající prostředí pro zobrazení telemetrie.

Nastavení řídicího panelu Aspire pomocí Dockeru

# 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

Tento příkaz spustí řídicí panel takto:

Webové uživatelské rozhraní: K dispozici na adrese http://localhost:18888
Koncový bod OTLP: Dostupný pro http://localhost:4317 vaše aplikace pro odesílání telemetrických dat

Konfigurace aplikace

Nastavte následující proměnné prostředí:

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

Nebo je vložte .env do souboru a spusťte ukázku.

Po dokončení ukázky přejděte ve http://localhost:18888 webovém prohlížeči, abyste viděli telemetrická data. Postupujte podle průvodce zkoumáním řídicího panelu Aspire a ověřte řídicí panel a začněte zkoumat trasování, protokoly a metriky.

Rozsahy a metriky

Jakmile je všechno nastavené, začnete automaticky zobrazovat rozsahy a metriky, které se pro vás vytvářejí, rozsahy jsou:

invoke_agent <agent_name>: Toto je rozsah nejvyšší úrovně pro každé vyvolání agenta, bude obsahovat všechny ostatní rozsahy jako podřízené položky.
chat <model_name>: Toto rozpětí se vytvoří, když agent volá základní model chatu, bude obsahovat výzvu a odpověď jako atributy, pokud enable_sensitive_data je nastavena na True.
execute_tool <function_name>: Toto rozpětí se vytvoří, když agent volá nástroj funkce, bude obsahovat argumenty funkce a výsledek jako atributy, pokud enable_sensitive_data je nastavena na True.

Vytvořené metriky:

Pro chatovacího klienta a chat operace:
- gen_ai.client.operation.duration (histogram): Tato metrika měří dobu trvání každé operace v sekundách.
- gen_ai.client.token.usage (histogram): Tato metrika měří využití tokenu v počtu tokenů.
Volání funkce během execute_tool operací:
- agent_framework.function.invocation.duration (histogram): Tato metrika měří dobu trvání každého spuštění funkce v sekundách.

Příklad výstupu trasování

Když spustíte agenta s povolenou pozorovatelností, zobrazí se data trasování podobná následujícímu výstupu konzoly:

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

Toto trasování ukazuje:

Trasování a identifikátory rozsahu: Pro korelaci souvisejících operací
Informace o časování: Kdy byla operace spuštěna a ukončena
Metadata agenta: ID, název a pokyny agenta
Informace o modelu: Použitý systém AI (OpenAI) a ID odpovědi
Využití tokenů: Počty vstupních a výstupních tokenů pro sledování nákladů

Samples

V úložišti je celá řada ukázek microsoft/agent-framework , které tyto funkce demonstrují. Další informace najdete ve složce ukázek pozorovatelnosti. Tato složka obsahuje ukázky pro použití telemetrie s nulovým kódem.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-12-17

Sdílet prostřednictvím

Observability

Integrace OpenTelemetry

Povolení pozorovatelnosti (C#)

Konfigurace

Trasování

Metrics

Záznamy

Aspire Dashboard

Začínáme

Závislosti

Zahrnuté balíčky

Vývozci

Povolení pozorovatelnosti (Python)

Pět vzorů pro konfiguraci pozorovatelnosti

1. Standardní proměnné prostředí OpenTelemetry (doporučeno)

2. Vlastní vývozci

3. Nastavení třetí strany

4. Ruční nastavení

5. Automatická instrumentace (bez kódu)

Použití trasovacích a měřičů

Proměnné prostředí

Standardní proměnné prostředí OpenTelemetry

Nastavení Microsoft Foundry

Nainstalujte balíček azure-monitor-opentelemetry:

Konfigurovat pozorovatelnost přímo z AzureAIClient:

Nakonfigurujte Azure Monitor a volitelně povolte instrumentaci:

Aspire Dashboard

Nastavení řídicího panelu Aspire pomocí Dockeru

Konfigurace aplikace

Rozsahy a metriky

Příklad výstupu trasování

Samples

Váš názor

Další materiály

Nainstalujte balíček `azure-monitor-opentelemetry`:

Konfigurovat pozorovatelnost přímo z `AzureAIClient`: