Observability

L’observabilité est un aspect clé de la création de systèmes fiables et maintenables. Agent Framework fournit une prise en charge intégrée de l’observabilité, ce qui vous permet de surveiller le comportement de vos agents.

Ce guide vous guide tout au long des étapes permettant d’activer l’observabilité avec Agent Framework pour vous aider à comprendre comment vos agents effectuent et diagnostiquent les problèmes qui peuvent survenir.

Intégration d’OpenTelemetry

Agent Framework s’intègre à OpenTelemetry, et plus spécifiquement Agent Framework émet des traces, des journaux et des métriques en fonction des conventions sémantiques OpenTelemetry GenAI.

Activer l’observabilité (C#)

Pour activer l’observabilité pour votre client de conversation, vous devez créer le client de conversation comme suit :

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

Pour activer l’observabilité pour votre agent, vous devez générer l’agent comme suit :

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

Important

Lorsque vous activez l’observabilité pour vos clients et agents de conversation, vous pouvez voir des informations dupliquées, en particulier lorsque des données sensibles sont activées. Le contexte de conversation (y compris les invites et les réponses) capturé par le client de conversation et l’agent seront inclus dans les deux étendues. Selon vos besoins, vous pouvez choisir d’activer l’observabilité uniquement sur le client de conversation ou uniquement sur l’agent pour éviter la duplication. Pour plus d’informations sur les attributs capturés pour LLM et Agents, consultez les conventions sémantiques GenAI .

Note

Activez uniquement les données sensibles dans les environnements de développement ou de test, car elles peuvent exposer des informations utilisateur dans les journaux de production et les traces. Les données sensibles incluent des invites, des réponses, des arguments d’appel de fonction et des résultats.

Paramétrage

Maintenant que votre client de conversation et votre agent sont instrumentés, vous pouvez configurer les exportateurs OpenTelemetry pour envoyer les données de télémétrie à votre back-end souhaité.

Traces

Pour exporter des traces vers le back-end souhaité, vous pouvez configurer le Kit de développement logiciel (SDK) OpenTelemetry dans le code de démarrage de votre application. Par exemple, pour exporter des traces vers une ressource 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();

Conseil / Astuce

Selon votre back-end, vous pouvez utiliser différents exportateurs, consultez la documentation OpenTelemetry .NET pour plus d’informations. Pour le développement local, envisagez d’utiliser le tableau de bord Aspire.

Metrics

De même, pour exporter des métriques vers le back-end souhaité, vous pouvez configurer le Kit de développement logiciel (SDK) OpenTelemetry dans le code de démarrage de votre application. Par exemple, pour exporter des métriques vers une ressource 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();

Journaux

Les journaux sont capturés via l’infrastructure de journalisation que vous utilisez, par exemple Microsoft.Extensions.Logging. Pour exporter des journaux vers une ressource Azure Monitor, vous pouvez configurer le fournisseur de journalisation dans le code de démarrage de votre application :

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

Tableau de bord Aspire

Envisagez d’utiliser le tableau de bord Aspire comme moyen rapide de visualiser vos traces et métriques pendant le développement. Pour en savoir plus, consultez la documentation du tableau de bord Aspire. Le tableau de bord Aspire reçoit des données via un collecteur OpenTelemetry, que vous pouvez ajouter à votre fournisseur de suivi comme suit :

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

Mise en route

Consultez un exemple complet d’un agent avec OpenTelemetry activé dans le référentiel Agent Framework.

Dépendances

Packages inclus

Pour activer l’observabilité dans votre application Python, les packages OpenTelemetry suivants sont installés par défaut :

Exportateurs

Nous n’installons pas les exportateurs par défaut pour empêcher les dépendances inutiles et les problèmes potentiels liés à l’instrumentation automatique. Il existe un grand nombre d’exportateurs disponibles pour différents back-ends. Vous pouvez donc choisir ceux qui conviennent le mieux à vos besoins.

Certains exportateurs courants que vous souhaiterez peut-être installer en fonction de vos besoins :

Pour la prise en charge du protocole gRPC : installation opentelemetry-exporter-otlp-proto-grpc
Pour la prise en charge du protocole HTTP : installation opentelemetry-exporter-otlp-proto-http
Pour Azure Application Insights : installation azure-monitor-opentelemetry

Utilisez le Registre OpenTelemetry pour trouver d’autres exportateurs et packages d’instrumentation.

Activer l’observabilité (Python)

Cinq modèles pour la configuration de l’observabilité

Nous avons identifié plusieurs façons de configurer l’observabilité dans votre application, en fonction de vos besoins :

1. Variables d’environnement OpenTelemetry standard (recommandé)

L’approche la plus simple : configurez tout via des variables d’environnement :

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Ou si vous souhaitez simplement exporter des consoles :

from agent_framework.observability import configure_otel_providers

configure_otel_providers(enable_console_exporters=True)

2. Exportateurs personnalisés

Pour plus de contrôle sur les exportateurs, créez-les vous-même et passez-les à 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. Configuration tierce

De nombreux packages OpenTelemetry tiers ont leurs propres méthodes d’installation. Vous pouvez d’abord utiliser ces méthodes, puis appeler enable_instrumentation() pour activer les chemins de code d’instrumentation agent 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)

Pour 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. Configuration manuelle

Pour un contrôle complet, vous pouvez configurer manuellement des exportateurs, des fournisseurs et de l’instrumentation. Utilisez la fonction create_resource() d’assistance pour créer une ressource avec le nom et la version de service appropriés. Consultez la documentation Python OpenTelemetry pour obtenir des instructions détaillées sur l’instrumentation manuelle.

5. Instrumentation automatique (code zéro)

Utilisez l’outil CLI OpenTelemetry pour instrumenter automatiquement votre application sans modification du code :

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

Pour plus d’informations, consultez la documentation Python De code Zéro OpenTelemetry .

Utilisation de traceurs et de compteurs

Une fois l’observabilité configurée, vous pouvez créer des étendues ou des métriques personnalisées :

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

Il s’agit de wrappers de l’API OpenTelemetry qui retournent un traceur ou un compteur à partir du fournisseur global, avec agent_framework le nom de la bibliothèque d’instrumentation par défaut.

Variables d'environnement

Les variables d’environnement suivantes contrôlent l’observabilité de l’infrastructure agent :

ENABLE_INSTRUMENTATION - La valeur par défaut est falsedéfinie pour true activer l’instrumentation OpenTelemetry.
ENABLE_SENSITIVE_DATA - La valeur par défaut est falsedéfinie pour true activer la journalisation des données sensibles (invites, réponses, arguments d’appel de fonction et résultats). Soyez prudent avec ce paramètre, car il peut exposer des données sensibles.
ENABLE_CONSOLE_EXPORTERS - La valeur par défaut est falsedéfinie pour true activer la sortie de la console pour la télémétrie.
VS_CODE_EXTENSION_PORT - Port pour AI Toolkit ou intégration de l’extension VS Code Azure AI Foundry.

Note

Les informations sensibles incluent des invites, des réponses, etc. Elles ne doivent être activées que dans les environnements de développement ou de test. Il n’est pas recommandé d’activer cette fonctionnalité en production, car elle peut exposer des données sensibles.

Variables d’environnement OpenTelemetry standard

La configure_otel_providers() fonction lit automatiquement les variables d’environnement OpenTelemetry standard :

Configuration OTLP (pour le tableau de bord Aspire, Jaeger, etc.) :

OTEL_EXPORTER_OTLP_ENDPOINT - Point de terminaison de base pour tous les signaux (par exemple, http://localhost:4317)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - Point de terminaison spécifique aux traces (remplace la base)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - Point de terminaison spécifique aux métriques (remplace la base)
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - Point de terminaison spécifique aux journaux (remplace la base)
OTEL_EXPORTER_OTLP_PROTOCOL - Protocole à utiliser (grpc ou http, par défaut : grpc)
OTEL_EXPORTER_OTLP_HEADERS - En-têtes pour tous les signaux (par exemple, key1=value1,key2=value2)

Identification du service :

OTEL_SERVICE_NAME - Nom du service (par défaut : agent_framework)
OTEL_SERVICE_VERSION - Version du service (par défaut : version du package)
OTEL_RESOURCE_ATTRIBUTES - Attributs de ressources supplémentaires

Pour plus d’informations, consultez la spécification OpenTelemetry .

Configuration de Microsoft Foundry

Microsoft Foundry prend en charge le suivi avec visualisation pour vos étendues.

Vérifiez que votre Foundry est configuré avec une instance Azure Monitor, consultez les détails

Installez le package `azure-monitor-opentelemetry` :

pip install azure-monitor-opentelemetry

Configurez l’observabilité directement à partir des `AzureAIClient`éléments suivants :

Pour les projets Azure AI Foundry, vous pouvez configurer l’observabilité directement à partir des AzureAIClientéléments suivants :

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)

Conseil / Astuce

Les arguments à client.configure_azure_monitor() utiliser sont transmis à la fonction sous-jacente configure_azure_monitor() à partir du azure-monitor-opentelemetry package, consultez la documentation pour plus d’informations, nous nous occupons de définir la chaîne de connexion et la ressource.

Configurez Azure Monitor et activez éventuellement l’instrumentation :

Pour les projets non-Azure AI avec Application Insights, veillez à configurer un agent personnalisé dans Foundry, consultez les détails.

Exécutez ensuite votre agent avec le même ID d’agent OpenTelemetry que celui inscrit dans Foundry et configurez Azure Monitor comme suit :

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

Tableau de bord Aspire

Pour le développement local sans configuration d’Azure, vous pouvez utiliser le tableau de bord Aspire qui s’exécute localement via Docker et offre une excellente expérience d’affichage des données de télémétrie.

Configuration du tableau de bord Aspire avec 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

Cela démarre le tableau de bord avec :

Interface utilisateur web : disponible à l’adresse http://localhost:18888
Point de terminaison OTLP : disponible à http://localhost:4317 vos applications pour envoyer des données de télémétrie

Configuration de votre application

Définissez les variables d’environnement suivantes :

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

Vous pouvez également les inclure dans votre .env fichier et exécuter votre exemple.

Une fois votre exemple en cours d’exécution, accédez à http://localhost:18888 un navigateur web pour afficher les données de télémétrie. Suivez le guide d’exploration du tableau de bord Aspire pour vous authentifier auprès du tableau de bord et commencer à explorer vos traces, journaux et métriques.

Étendues et métriques

Une fois que tout est configuré, vous allez commencer à voir les étendues et les métriques créées automatiquement pour vous, les étendues sont les suivantes :

invoke_agent <agent_name>: il s’agit de l’étendue de niveau supérieur pour chaque appel d’agent, elle contiendra toutes les autres étendues en tant qu’enfants.
chat <model_name>: cette étendue est créée lorsque l’agent appelle le modèle de conversation sous-jacent, il contient l’invite et la réponse sous forme d’attributs, si enable_sensitive_data elle est définie Truesur .
execute_tool <function_name>: cette étendue est créée lorsque l’agent appelle un outil de fonction, il contient les arguments de fonction et le résultat en tant qu’attributs, s’il enable_sensitive_data est défini sur True.

Les métriques créées sont les suivantes :

Pour le client de conversation et chat les opérations :
- gen_ai.client.operation.duration (histogramme) : cette métrique mesure la durée de chaque opération, en secondes.
- gen_ai.client.token.usage (histogramme) : cette métrique mesure l’utilisation des jetons, en nombre de jetons.
Pour l’appel de fonction pendant les execute_tool opérations :
- agent_framework.function.invocation.duration (histogramme) : cette métrique mesure la durée de chaque exécution de fonction, en secondes.

Exemple de sortie de trace

Lorsque vous exécutez un agent avec l’observabilité activée, vous verrez des données de trace similaires à la sortie de la console suivante :

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

Cette trace montre :

Identificateurs de trace et d’étendue : pour la corrélation des opérations associées
Informations de minutage : au démarrage et à la fin de l’opération
Métadonnées de l’agent : ID de l’agent, nom et instructions
Informations sur le modèle : le système IA utilisé (OpenAI) et l’ID de réponse
Utilisation des jetons : nombre de jetons d’entrée et de sortie pour le suivi des coûts

Samples

Nous avons un certain nombre d’exemples dans notre référentiel qui illustrent ces fonctionnalités, consultez le dossier d’exemples d’observabilité sur Github. Cela inclut également des exemples d’utilisation de données de télémétrie sans code.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-12-17

Partager via

Observability

Intégration d’OpenTelemetry

Activer l’observabilité (C#)

Paramétrage

Traces

Metrics

Journaux

Tableau de bord Aspire

Mise en route

Dépendances

Packages inclus

Exportateurs

Activer l’observabilité (Python)

Cinq modèles pour la configuration de l’observabilité

1. Variables d’environnement OpenTelemetry standard (recommandé)

2. Exportateurs personnalisés

3. Configuration tierce

4. Configuration manuelle

5. Instrumentation automatique (code zéro)

Utilisation de traceurs et de compteurs

Variables d'environnement

Variables d’environnement OpenTelemetry standard

Configuration de Microsoft Foundry

Installez le package azure-monitor-opentelemetry :

Configurez l’observabilité directement à partir des AzureAIClientéléments suivants :

Configurez Azure Monitor et activez éventuellement l’instrumentation :

Tableau de bord Aspire

Configuration du tableau de bord Aspire avec Docker

Configuration de votre application

Étendues et métriques

Exemple de sortie de trace

Samples

Commentaires

Ressources supplémentaires

Installez le package `azure-monitor-opentelemetry` :

Configurez l’observabilité directement à partir des `AzureAIClient`éléments suivants :