Distribution OpenTelemetry de Microsoft

Microsoft Distribution OpenTelemetry est une distribution d’observabilité unifiée qui offre une expérience d’intégration unique pour collecter des traces, des métriques et des journaux d’activité à partir d’applications agentiques et non-agentiques. Il prend en charge l’observabilité pour Microsoft Agent 365, Microsoft Foundry, Azure Monitor et tout back-end compatible avec OpenTelemetry Protocol (OTLP). La distribution prend en charge .NET, Node.js, et Python, et remplace la configuration fragmentée sur plusieurs systèmes d’observabilité par un appel d'importation et un appel de configuration.

Principaux avantages

La distribution OpenTelemetry Microsoft offre les avantages suivants :

Un package, une API : remplacez plusieurs packages d’exportation et d’instrumentation par une seule dépendance.
Prise en charge de plusieurs backends : envoyez des données de télémétrie à Azure Monitor, à tout point de terminaison compatible avec le protocole OTLP (OpenTelemetry Protocol), tel que Datadog, Grafana ou New Relic, ainsi qu'à Microsoft Agent 365 en même temps.
Instrumentations intégrées : utilisez l’instrumentation automatique pour HTTP, bases de données, Kit de développement logiciel (SDK) Azure, Azure Functions, etc. sans configuration supplémentaire.
Basé sur des normes : Reposez sur OpenTelemetry, le framework d’observabilité standard du secteur.
Configuration minimale : ajoutez un import et un appel de fonction au point d’entrée de votre application.

Installation et configuration

Ce guide explique comment ajouter l’observabilité à votre application avec Microsoft OpenTelemetry Distro. La distribution collecte automatiquement les traces, les métriques et les journaux avec des instrumentations intégrées et exporte les données de télémétrie vers Azure Monitor, tout point de terminaison OTLP (OpenTelemetry Protocol) ou Microsoft Agent 365.

Installer la bibliothèque

Pour commencer à utiliser la distribution OpenTelemetry Microsoft, installez la bibliothèque appropriée pour votre plateforme de développement à l'aide du gestionnaire de package de votre langage.

Prerequisites : Python 3.10 ou version ultérieure.

pip install microsoft-opentelemetry

Conditions préalables : Node.js 18 ou version ultérieure. Les applications ESM nécessitent Node.js 20.6.0 ou version ultérieure.

npm install @microsoft/opentelemetry

Important

Appelez useMicrosoftOpenTelemetry() le plus tôt possible dans votre point d’entrée d’application afin que les instrumentations puissent corriger les bibliothèques avant leur chargement.

Pour les applications ESM, enregistrez des points d'instrumentation avant d'importer des modules instrumentés. Utilisez l’indicateur --import au démarrage :

node --import @microsoft/opentelemetry/loader ./dist/index.js

Installez le package NuGet Microsoft.OpenTelemetry. Ce package unique inclut le runtime d’observabilité Agent 365, l’intégration d’hébergement, l’instrumentation automatique pour les infrastructures IA prises en charge et les bibliothèques OpenTelemetry standard.

<PackageReference Include="Microsoft.OpenTelemetry" />

Vous pouvez également utiliser l’interface CLI .NET :

dotnet add package Microsoft.OpenTelemetry

Note

Si le package n’est pas disponible sur le flux NuGet public, ajoutez un nuget.config fichier à la racine de votre projet. Consultez le référentiel readME .NET pour la configuration du flux.

Paramétrage

L'exportateur Agent 365 n'utilise pas de chaîne de connexion. Il découvre automatiquement son point de terminaison en fonction du locataire. Pour activer l’exportation vers l’agent 365, définissez la cible de l’exportateur et fournissez un programme de résolution de jeton qui retourne un jeton d’accès pour un ID d’agent et un ID de locataire donnés.

Appel use_microsoft_opentelemetry() pour activer l’observabilité.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

Pour la résolution de jetons personnalisée (au lieu du programme de résolution de jeton par défaut), consultez programme de résolution de jeton manuel.

Utilisez ObservabilityManager avec AgenticTokenCacheInstance pour gérer automatiquement la mise en cache des jetons :

import { useMicrosoftOpenTelemetry, AgenticTokenCacheInstance } from '@microsoft/opentelemetry';
import { resourceFromAttributes } from '@opentelemetry/resources';

useMicrosoftOpenTelemetry({
  resource: resourceFromAttributes({
    'service.name': 'Default Token Cache Sample',
    'service.version': '1.0.0',
  }),
  azureMonitor: {
    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
  },
  instrumentationOptions: {
    http: { enabled: false },
  },
  a365: {
    enabled: process.env.ENABLE_A365_OBSERVABILITY_EXPORTER !== 'false',
    tokenResolver: (agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId) ?? '',
  },
});

Pour la résolution de jetons personnalisée (au lieu du programme de résolution de jeton par défaut), consultez programme de résolution de jeton manuel.

Pour obtenir des options de configuration complètes et des variables d’environnement, consultez le fichier README du référentiel JavaScript.

Dans Program.cs, appel UseMicrosoftOpenTelemetry() pour activer l’observabilité. Les indicateurs d'énumération ExportTarget contrôlent l’emplacement où les données de télémétrie sont envoyées - combinez des cibles avec | (par exemple, ExportTarget.Console | ExportTarget.Agent365).

Cache de jetons automatique (DI) ( recommandé pour les applications Agent Framework) :

Lorsque vous ne définissez TokenResolverpas, la distribution s’inscrit IExporterTokenCache<AgenticTokenStruct> automatiquement par le biais d’une di. Votre agent appelle RegisterObservability() au moment de l’exécution pour fournir des informations d’identification, et le cache gère l’acquisition et l’actualisation des jetons.

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // TokenResolver is auto-registered via the agentic token cache in DI, with required imports in the next code snippet.
});

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

// In your agent class
public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

Pour la résolution de jetons personnalisée (au lieu du programme de résolution de jeton par défaut), consultez programme de résolution de jeton manuel.

Note

ENABLE_A365_OBSERVABILITY_EXPORTER est un concept Python et JavaScript. Dans .NET, l’exportateur Agent 365 est entièrement contrôlé dans le code via ExportTarget.Agent365.

Propager le contexte

Pour maintenir l'observabilité dans les opérations distribuées de l'Agent 365, vous devez propager le contexte. Lorsque vous propagez le contexte par le biais de vos agents et services, vous vous assurez que les traces, les journaux et les métriques sont correctement corrélés dans l’ensemble du cycle de vie d'une requête. Cette corrélation est requise pour une expérience de surveillance complète et efficace Microsoft Agent 365.

Attributs des bagages

Utilisez BaggageBuilder pour définir des informations contextuelles qui transitent par toutes les portées d’une requête. Le SDK implémente un SpanProcessor qui copie toutes les entrées de bagages non vides dans les spans nouvellement lancés sans écraser les attributs existants.

from microsoft.opentelemetry.a365.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

Pour remplir automatiquement le BaggageBuilder à partir du TurnContext, utilisez l’outil populate dans le package microsoft-opentelemetry. Cette assistance extrait automatiquement l’appelant, l’agent, le client, le canal et les détails de conversation de l’activité.

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

import { BaggageBuilder, InvokeAgentScope, ExecuteToolScope } from '@microsoft/opentelemetry';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

Pour remplir automatiquement le BaggageBuilder à partir du TurnContext, utilisez l’outil fromTurnContext dans le package @microsoft/opentelemetry. Cette assistance extrait automatiquement l’appelant, l’agent, le client, le canal et les détails de conversation de l’activité.

import { BaggageBuilder, BaggageBuilderUtils } from '@microsoft/opentelemetry';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

baggageScope.run(() => {
  // Baggage is auto-populated from the TurnContext activity
});

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

Pour remplir automatiquement le BaggageBuilder à partir du ITurnContext, utilisez la méthode d’extension FromTurnContext dans le package Microsoft.Agents.A365.Observability.Hosting. Cette méthode extrait automatiquement l’appelant, l’agent, le locataire, le canal et les détails de conversation de l’activité.

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

Intergiciels de bagages

Si votre agent utilise le package d’intégration d’hébergement, inscrivez l’intergiciel des bagages pour remplir automatiquement les bagages pour chaque demande entrante. Cette étape supprime la nécessité d’appeler BaggageBuilder manuellement dans chaque gestionnaire d’activités.

Dans Python, inscrivez l’intergiciel des bagages via ObservabilityHostingManager.configure() plutôt que directement sur l’adaptateur.

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

L’intergiciel ignore la configuration des bagages pour les réponses asynchrones (ContinueConversation événements) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

Enregistrez BaggageMiddleware sur l’adaptateur. Il extrait automatiquement l’appelant, l’agent, le locataire, le canal et les détails de conversation de chaque entrant TurnContext et encapsule la demande dans une étendue de bagages.

import { BaggageMiddleware } from '@microsoft/opentelemetry';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

Vous pouvez également utiliser ObservabilityHostingManager pour configurer le middleware de gestion des bagages avec d'autres fonctionnalités d'hébergement.

import { ObservabilityHostingManager } from '@microsoft/opentelemetry';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

Enregistrez BaggageTurnMiddleware sur l’adaptateur. Il extrait automatiquement l’appelant, l’agent, le locataire, le canal et les détails de conversation de chaque entrant ITurnContext et encapsule la demande dans une étendue de bagages.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

Si vous avez besoin d'un bagage au niveau HTTP (par exemple, pour définir des ID de locataire et d’agent avant l’exécution du pipeline Bot Framework), enregistrez ObservabilityBaggageMiddleware dans le pipeline ASP.NET Core à l’aide de la méthode d’extension UseObservabilityRequestContext. Vous devez fournir une fonction de programme de résolution qui extrait l’ID de locataire et l’ID de l’agent à partir du contexte HTTP.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

Valider que les données circulent dans le produit

Pour afficher les données de télémétrie de l’agent dans Microsoft Purview ou Microsoft Defender, vérifiez que les conditions suivantes sont remplies :

Microsoft Purview : l’audit doit être activé pour votre organisation. Pour obtenir des instructions, consultez Activer ou désactiver l’audit.
Microsoft Defender : la recherche avancée doit être configurée pour permettre l'accès à la table CloudAppEvents. Pour plus d’informations, consultez la table CloudAppEvents dans le schéma de repérage avancé.

Instrumentation automatique

La distribution OpenTelemetry Microsoft combine les pipelines OpenTelemetry standard avec l'instrumentation sélectionnée par Microsoft. La distribution peut collecter la télémétrie d'application, la télémétrie de l'infrastructure et la télémétrie de l'agent ou d'IA générative en fonction du langage et de la configuration.

Catégorie	Ce qu’il couvre
Pipelines de signal	Traces, métriques et journaux de bord.
Détection des ressources	Service, hôte, cloud et contexte d'exécution Azure pris en charge.
Instrumentation de l’infrastructure	HTTP, ASP.NET Core, Kit de développement logiciel (SDK) Azure, clients de base de données et frameworks de journalisation pris en charge.
Instrumentation de l’IA générative	OpenAI, Azure OpenAI, Noyau sémantique, LangChain, Kit de développement logiciel des agents OpenAI (SDK) et Agent Framework, là où c'est pris en charge.
Étendues de l’agent manuel	Appel de l’agent, exécution d’outils, inférence et données de télémétrie de sortie prises en charge.
Exportateurs et transformateurs	Azure Monitor, Microsoft Agent 365, OTLP, sortie de console, processeurs d’étendue, processeurs de journaux et lecteurs de métriques.

Couverture de l’instrumentation

Language	Instrumentation des applications courantes	Instrumentation courante des agents et de l'IA générative
Python	Ressources OpenTelemetry, processeurs, lecteurs, journalisation, métriques et traces.	Noyau sémantique, Kit de développement logiciel (SDK) des agents OpenAI, Agent Framework, LangChain, bagages Microsoft Agent 365 et étendues Microsoft Agent 365.
Node.js	HTTP, Kit de développement logiciel (SDK) Azure, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan et Winston.	Kit SDK d’agents OpenAI, LangChain, données Microsoft Agent 365 et périmètres Microsoft Agent 365.
.NET	ASP.NET Core, HttpClient, SQL Client, Kit de développement logiciel (SDK) Azure, détection des ressources, métriques et journaux.	Noyau sémantique, OpenAI et Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage et périmètres Microsoft Agent 365.

L’instrumentation automatique écoute les signaux de télémétrie émis par les bibliothèques et infrastructures prises en charge. L’instrumentation manuelle est utilisée lorsqu’une application doit décrire des opérations spécifiques à l’agent, telles que l’appel, l’exécution d’outils, l’inférence ou la sortie asynchrone.

Ajoutez des sources, des compteurs, des processeurs ou des lecteurs OpenTelemetry personnalisés lorsque votre application émet des données de télémétrie qui ne sont pas couvertes par les instrumentations intégrées.

Bibliothèques d’instrumentation intégrées

L’instrumentation automatique écoute les données de télémétrie émises par les frameworks pris en charge et les transfère via le pipeline OpenTelemetry de la distribution. Pour les scénarios d’agent, définissez les bagages tels que l’ID de locataire et l’ID d’agent avant que l’infrastructure instrumentée crée des étendues.

Cadre	Python	Node.js	.NET
Noyau sémantique	Soutenu	Non pris en charge	Soutenu
OpenAI et SDK d'agents OpenAI	Soutenu	Soutenu	Soutenu
Infrastructure de l’agent	Soutenu	Non pris en charge	Soutenu
LangChain	Soutenu	Soutenu	Non répertorié

Noyau sémantique

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

Noyau sémantique instrumentation est activée par défaut. Pour le désactiver, définissez l’option d’instrumentation explicitement.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableSemanticKernelInstrumentation = false;
});

OpenAI

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    openaiAgents: { enabled: true },
  },
});

OpenAI et Azure l’instrumentation OpenAI est activée par défaut. Pour le désactiver, définissez l’option d’instrumentation explicitement.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableOpenAIInstrumentation = false;
});

Infrastructure de l’agent

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

L'instrumentation du framework d'agent est activée par défaut. Pour le désactiver, définissez l’option d’instrumentation explicitement.

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableAgentFrameworkInstrumentation = false;
});

LangChain

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    langchain: { enabled: true },
  },
});

Instrumentation manuelle

Utilisez l’instrumentation manuelle lorsque l’instrumentation automatique ne décrit pas l’opération de l’agent avec suffisamment de détails. Les étendues manuelles permettent à une application de décrire les activités d’agent courantes de manière cohérente entre les langages.

Étendue	Utiliser pour
`InvokeAgentScope`	Le début et l’achèvement d’un appel d’agent.
`ExecuteToolScope`	Un appel de fonctionnalité effectué par un agent.
`InferenceScope`	Opération d’inférence de modèle IA.
`OutputScope`	Sortie qui doit être enregistrée après que l’étendue d’origine a déjà été terminée.

Réutilisez les mêmes valeurs d’identité de requête et d’agent entre les étendues d’une requête afin que les données de télémétrie associées puissent être corrélées.

Invocation de l’agent

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

import { InvokeAgentScope } from "@microsoft/opentelemetry";
import type {
  AgentDetails,
  A365Request,
  InvokeAgentScopeDetails,
} from "@microsoft/opentelemetry";

const agentDetails: AgentDetails = {
  agentId: "agent-456",
  agentName: "Email Assistant",
  agentDescription: "An AI agent powered by Azure OpenAI",
  agentAUID: "auid-123",
  agentEmail: "agent@contoso.com",
  agentBlueprintId: "blueprint-789",
  tenantId: "tenant-123",
};

const request: A365Request = {
  content: "Please help me organize my emails",
  sessionId: "session-42",
  conversationId: "conv-xyz",
  channel: { name: "msteams" },
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: "myagent.contoso.com", port: 443 },
};

const invokeScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    invokeScope.recordInputMessages(["Please help me organize my emails"]);

    // Run the agent invocation.

    invokeScope.recordOutputMessages(["I found 15 urgent emails."]);
  });
} catch (error) {
  invokeScope.recordError(error as Error);
  throw error;
} finally {
  invokeScope.dispose();
}

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

var agentDetails = new AgentDetails(
    agentId: "agent-456",
    agentName: "Email Assistant",
    agentDescription: "An AI agent powered by Azure OpenAI",
    agenticUserId: "auid-123",
    agenticUserEmail: "agent@contoso.com",
    agentBlueprintId: "blueprint-789",
    tenantId: "tenant-123");

var request = new Request(
    content: "Please help me organize my emails",
    sessionId: "session-42",
    conversationId: "conv-xyz",
    channel: new Channel(name: "msteams"));

var scopeDetails = new InvokeAgentScopeDetails(
    endpoint: new Uri("https://myagent.contoso.com"));

using var invokeScope = InvokeAgentScope.Start(
    request: request,
    scopeDetails: scopeDetails,
    agentDetails: agentDetails);

invokeScope.RecordInputMessages(new[] { "Please help me organize my emails" });

// Run the agent invocation.

invokeScope.RecordOutputMessages(new[] { "I found 15 urgent emails." });

Exécution de l’outil

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

with ExecuteToolScope.start(
    request=request,
    details=tool_details,
    agent_details=agent_details,
) as scope:
    result = search_emails(tool_details.arguments)
    scope.record_response(result)

import { ExecuteToolScope } from "@microsoft/opentelemetry";
import type { ToolCallDetails } from "@microsoft/opentelemetry";

const toolDetails: ToolCallDetails = {
  toolName: "email-search",
  arguments: JSON.stringify({ query: "from:manager@contoso.com" }),
  toolCallId: "tool-call-456",
  description: "Search emails by criteria",
  toolType: "function",
  endpoint: {
    host: "tools.contoso.com",
    port: 8080,
    protocol: "https",
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var toolDetails = new ToolCallDetails(
    toolName: "email-search",
    arguments: "{\"query\": \"from:manager@contoso.com\"}",
    toolCallId: "tool-call-456",
    description: "Search emails by criteria",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080"));

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolDetails,
    agentDetails: agentDetails);

// Execute the tool.

scope.RecordResponse("{\"count\": 15}");

Inférence

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

import { InferenceOperationType, InferenceScope } from "@microsoft/opentelemetry";
import type { InferenceDetails } from "@microsoft/opentelemetry";

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: "gpt-4o-mini",
  providerName: "azure-openai",
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    scope.recordInputMessages(["Summarize the following emails for me."]);
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
    scope.recordFinishReasons(["stop"]);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI");

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails);

scope.RecordInputMessages(new[] { "Summarize the following emails for me." });

// Call the model.

scope.RecordOutputMessages(new[] { "Here is your email summary." });
scope.RecordInputTokens(145);
scope.RecordOutputTokens(82);
scope.RecordFinishReasons(new[] { "stop" });

Sortie

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

import { OutputScope } from "@microsoft/opentelemetry";
import type { A365SpanDetails, OutputResponse } from "@microsoft/opentelemetry";

// Capture this before disposing the originating InvokeAgentScope.
const parentContext = invokeScope.getSpanContext();
const response: OutputResponse = {
  messages: ["Here is your organized inbox."],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined,
  { parentContext } as A365SpanDetails
);

scope.dispose();

// Capture this before disposing the originating InvokeAgentScope.
var parentContext = invokeScope.GetActivityContext();
var response = new Response(new[] { "Here is your organized inbox." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext));

La documentation produit doit définir les exigences de validation spécifiques au produit pour ces étendues.

Validation locale

La validation locale confirme que l’application produit des données de télémétrie avant qu’une destination spécifique au produit soit validée. Utilisez la sortie de la console ou un point de terminaison OTLP local pour vérifier que les traces, les métriques et la journalisation sont créées.

Valider avec un point de terminaison OTLP local

Configurez la distribution pour envoyer des données de télémétrie à un collecteur local ou à un autre point de terminaison compatible OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

useMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Otlp;
    o.OtlpEndpoint = new Uri("http://localhost:4317");
});

Valider avec la sortie locale

Utilisez la sortie locale lorsque vous souhaitez confirmer l’instrumentation avant d’envoyer des données de télémétrie à une destination distante.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

import {
  useMicrosoftOpenTelemetry,
  shutdownMicrosoftOpenTelemetry,
} from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "local-validation-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
});

// Run instrumented application code.

await shutdownMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Console;
});

Passez en revue la sortie locale pour examiner des étendues provenant de sources attendues, telles que les requêtes HTTP, les appels OpenAI ou Azure OpenAI, les portées d'appel d'agents, d'exécution d'outils ou d'inférence. La validation spécifique à la destination doit être incluse dans la documentation du produit pour cette destination.

Configurer manuellement l’authentification

Lorsque vous utilisez l’exportateur Agent 365, vous devez fournir un mécanisme pour fournir un jeton d’authentification. Le résolveur de jetons fonctionne par lot d’exportation en utilisant l'ID d'agent et l'ID de locataire à partir du contexte de bagages actif. La distribution prend en charge trois approches.

Résolveur de jeton manuel

Utilisez un programme de résolution manuel lorsque vous achetez des jetons en dehors du pipeline Agent Framework ou lorsque vous créez des applications non-Agent Framework.

Le programme de résolution doit être synchrone. Acquérir le jeton dans votre gestionnaire d’activités asynchrones et le mettre en cache pour le programme de résolution.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
import { TurnState, AgentApplication, TurnContext, MemoryStorage } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId: string, tenantId: string, authScopes?: string[]) =>
      myTokenService.getToken(agentId, tenantId),
  },
});


export class A365Agent extends AgentApplication<TurnState> {
  isApplicationInstalled: boolean = true;
  termsAndConditionsAccepted: boolean = true;
  agentName = 'A365 Agent';
  authHandlerName = 'agentic';
 
  constructor() {
    const useAgenticAuth = process.env.USE_AGENTIC_AUTH === 'true';

    super({
      storage: new MemoryStorage(),
      ...(useAgenticAuth && {
        authorization: {
          agentic: {
            type: 'agentic',
          }
        }
      })
    });

    this.onActivity(ActivityTypes.Message, async (context: TurnContext, state: TurnState) => {
      await this.handleAgentMessageActivity(context, state);
    });
  }

  async handleAgentMessageActivity(turnContext: TurnContext, _state: TurnState): Promise<void> {
    if (process.env.USE_AGENTIC_AUTH !== 'true') {
      console.log('[A365Agent] Authorization not configured, skipping observability token preload');
      return;
    }

    const agentId = turnContext?.activity?.recipient?.agenticAppId ?? '';
    const tenantId = turnContext?.activity?.recipient?.tenantId ?? '';

    // Acquire auth token via OBO exchange
    const authToken = await this.authorization.exchangeToken(turnContext, 'agentic', {
      scopes: ['api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite']
    });

    // Cache the token so it can be returned by the token resolver
    myTokenService.set(agentId, tenantId, authToken?.token || '');
  }
}

using Microsoft.OpenTelemetry;

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
    {
        return await MyTokenService.GetTokenAsync(agentId, tenantId);
    };
});

Lorsque vous définissez TokenResolver explicitement, le cache de jetons DI automatique n’est pas inscrit : votre résolveur est utilisé à la place.

Cache de jetons agentique avec des applications Agent Framework

Pour les IExporterTokenCache<AgenticTokenStruct> applications Agent Framework, la distribution s’inscrit automatiquement via DI lorsque vous ne définissez pas de code personnalisé TokenResolver. Votre agent appelle RegisterObservability() au moment de l’exécution pour fournir des informations d’identification, et le cache gère l’acquisition et l’actualisation des jetons.

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

Utilisez configureA365Hosting pour enregistrer le middleware A365 sur l'adaptateur. Ce middleware gère automatiquement les bagages et la plomberie des jetons.

import { configureA365Hosting } from "@microsoft/opentelemetry";

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: false,
});

Définissez si le contenu de réponse ne doit pas être capturé en tant qu’attributs .

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // IExporterTokenCache<AgenticTokenStruct> is auto-registered via DI
});

Dans votre classe d’agent, appelez RegisterObservability() à chaque tour :

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

Exemples d’applications et configuration avancée

Pour obtenir des exemples de travail et des options de configuration avancées, consultez les référentiels GitHub pour chaque langue :

Résolution des problèmes

Cette section décrit les problèmes courants lors de l’implémentation et de l’utilisation de la Microsoft distribution OpenTelemetry avec l’agent 365.

Conseil / Astuce

Le Guide de dépannage de l’Agent 365 contient des recommandations générales de dépannage, les meilleures pratiques et des liens vers du contenu de dépannage pour chaque étape du cycle de développement de l’Agent 365.

Les données d’observabilité n’apparaissent pas

Symptômes :

L’agent est en fuite
Pas de télémétrie dans le centre administratif
Impossible de voir l’activité des agents

Cause racine :

L’exportation Agent 365 n’est pas activée
Erreurs de configuration
Problèmes de résolution de jetons

Solutions : Essayez les étapes suivantes pour résoudre le problème :

Vérifier que l’exportation agent 365 est activée

Vous devez activer explicitement l’exportateur Agent 365. Lorsque vous ne le définissez pas, la distribution peut se replier sur un exportateur de console ou ne rien exporter. Activez-le dans le code :

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

Ou définissez la variable d’environnement :

export ENABLE_A365_OBSERVABILITY_EXPORTER=true

useMicrosoftOpenTelemetry({
  a365: { enabled: true },
});

Ou définissez la variable d’environnement :

ENABLE_A365_OBSERVABILITY_EXPORTER=true

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
        await myTokenService.GetTokenAsync(agentId, tenantId);
});

Vérifier la configuration du résolveur de jeton

L’exportateur requiert un programme de résolution de jeton valide qui retourne un jeton porteur pour chaque demande d’exportation. Si le programme de résolution de jeton est manquant ou retourne null, l’exportation est ignorée sans notification.
Activer l’exportation et la vérification de la télémétrie localement dans la console

Ajoutez un exportateur de console pour vérifier que la télémétrie est générée avant d’atteindre le point de terminaison de l'Agent 365 :
- Python
- Node.js
- .NET
```
use_microsoft_opentelemetry(enable_a365=True, enable_console=True)
```
```
useMicrosoftOpenTelemetry({ enableConsoleExporters: true });
```
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365 | ExportTarget.Console;
});
```

Activez la journalisation commentée
- Python
- Node.js
- .NET
```
import logging

logging.basicConfig(level=logging.DEBUG)
```
Définissez A365_OBSERVABILITY_LOG_LEVEL sur info ou warn pour afficher les diagnostics internes de l'exportateur A365.
```
A365_OBSERVABILITY_LOG_LEVEL=info
```
Les composants internes enregistrent via ILoggerFactory depuis le DI. Dans ASP.NET Core applications, la journalisation transite automatiquement par le pipeline configuré de l'application. Pour les applications console, connectez-la explicitement :
```
builder.Services.AddLogging(logging => logging.AddConsole());
```

Vérifier les journaux d’activité pour les erreurs d’exportation

Utilisez la az webapp log tailcommande pour rechercher des erreurs liées à l’observabilité dans les journaux d’activité :
```
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```

ID de locataire ou ID d’agent manquant : sections ignorées

Symptômes: Le système supprime silencieusement les étendues et ne les exporte jamais. Certaines plateformes enregistrent un nombre d’étendues ignorées ou un message tel que No spans with tenant/agent identity found. D’autres les suppriment sans enregistrement.

Résolution :

Avant l’exportation, les partitions du système sont segmentées par l'identité du locataire et de l'agent. Les étendues qui n’ont pas d’ID de locataire ou d’ID d’agent sont supprimées et ne sont jamais envoyées au service.
Vérifiez que BaggageBuilder soit configuré avec l’ID de locataire et l’ID de l’agent avant de créer des spans. Ces valeurs se propagent via le contexte OpenTelemetry et s’attachent à toutes les traces créées dans le contexte du baggage. Pour obtenir l’API spécifique à la plateforme, consultez les attributs de bagages.
Si vous utilisez le middleware pour les bagages ou l'assistant de contexte du package d'intégration d'hébergement, vérifiez que l'activité TurnContext a un destinataire valide avec une identité d'agent.

Échec de résolution de jeton : exportation ignorée ou non autorisée

Symptômes: Le programme de résolution de jeton retourne null ou lève une erreur. Selon la plateforme, l’exportation est ignorée entièrement ou échoue avec HTTP 401.

Résolution :

Le résolveur de jeton est requis. S’il est manquant, l’exportateur génère une erreur au démarrage. Vérifiez qu’un programme de résolution de jeton est fourni et retourne un jeton porteur valide.
Assurez-vous que l’ID de locataire et l’ID d’agent appropriés sont passés à BaggageBuilder, car ces valeurs sont transférées au résolveur de jeton.
Pour les agents hébergés Azure, vérifiez que l’identité managée dispose de l’autorisation API requise pour l’étendue d’observabilité.
Pour les applications .NET à l’aide du package d’hébergement Agent Framework, l’échange de jetons est géré automatiquement via l’API. Si des jetons sont manquants, vérifiez que Microsoft.Agents.A365.Observability.Hosting est installé et inscrit.

HTTP 401 Non autorisé

Symptômes: L’exportation échoue avec HTTP 401. L’exportateur ne réessaye pas cette erreur.

Résolution :

Vérifiez que l’audience du jeton correspond à l’étendue du point de terminaison d’observabilité.
Vérifiez que le résolveur de jetons ne retourne pas de jeton d'utilisateur délégué, un jeton pour un public incorrect ou un jeton expiré.

HTTP 403 Interdit

Symptômes: L’exportation échoue avec HTTP 403. L’exportateur ne réessaye pas cette erreur.

Cause: Une erreur HTTP 403 peut avoir des causes différentes. Vérifiez les résolutions suivantes dans l’ordre.

Résolution :

Licence manquante — Vérifiez que votre client dispose de l'une des licences suivantes attribuées dans le Centre d'administration Microsoft 365 :
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
Autorisation manquante Agent365.Observability.OtelWrite : vous devez accorder cette autorisation à votre identité (identité managée ou inscription d’application). Sans cela, l’exportation de télémétrie échoue avec HTTP 403.

Accordez l’autorisation à l’aide de l’une des options suivantes.

Option A — Agent 365 CLI (nécessite a365.config.json et a365.generated.config.json dans votre répertoire de configuration, un compte Administrateur général et Agent 365 CLI v1.1.139-preview ou version ultérieure)
```
a365 setup admin --config-dir "<path-to-config-dir>"
```
Option B — Entra Portal (aucun fichier de configuration requis ; nécessite l’accès administrateur général à l’inscription de l’application blueprint)
1. Accédez au portail Entra>inscriptions d'applications> sélectionnez votre application Blueprint.
2. Accédez aux autorisations d’API>Ajouter une autorisation>APIs que mon organisation utilise> recherchez9b975845-388f-4429-889e-eab1ef63949c.
3. Sélectionnez Autorisations déléguées> pour vérifier Agent365.Observability.OtelWrite>Ajouter des autorisations.
4. Répétez les étapes 2 à 3, cette fois,sélectionnez Autorisations > pour vérifier Agent365.Observability.OtelWrite>Ajouter des autorisations.
5. Cliquez sur Accorder le consentement de l’administrateur et confirmez.
Les deux Agent365.Observability.OtelWrite (délégués) et Agent365.Observability.OtelWrite (Application) doivent afficher l’état Granted .

HTTP 429 / 5xx — Erreurs temporaires

Symptômes: L’exportation échoue avec un code d’état HTTP temporaire tel que 429 ou 5xx.

Résolution :

Ces erreurs sont généralement temporaires et résolues par elles-mêmes. Les distributions Python et JavaScript réessayent automatiquement sur les codes d’état HTTP 408, 429 et 5xx. La distribution .NET ne réessaye pas automatiquement.
Si les erreurs persistent, consultez le tableau de bord d’intégrité du service.
Envisagez de réduire la fréquence d’exportation en augmentant le délai planifié entre les lots ou la taille maximale du lot d’exportation. Pour Python et JavaScript, utilisez les paramètres exporterOptions ou a365_* documentés dans les référentiels GitHub. Pour .NET, utilisez o.Agent365.Exporter.ScheduledDelayMilliseconds et o.Agent365.Exporter.MaxExportBatchSize.

Délai d’expiration de l’exportation

Symptômes: Les tentatives d’exportation expirent.

Résolution :

Vérifiez la connectivité réseau au point de terminaison d’observabilité.

Le délai d’expiration de la requête HTTP par défaut est de 30 secondes sur toutes les plateformes. Si des délais d’expiration se produisent fréquemment, augmentez la valeur du délai d’expiration dans vos options d’exportation :

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

Consultez le référentiel Python pour obtenir la liste complète des options a365_*.

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: myTokenResolver,
    exporterOptions: {
      httpRequestTimeoutMilliseconds: 60000,
    },
  },
});

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.ExporterTimeoutMilliseconds = 60000;
});

L'exportation réussit, mais la télémétrie n'apparaît pas dans Defender ou Purview

Symptômes : Les journaux indiquent une exportation réussie (HTTP 200), mais la télémétrie n'apparaît pas dans Microsoft Defender ou Microsoft Purview.

Résolution :

Vérifiez que vous répondez à des conditions préalables à l’affichage des journaux exportés :
- Microsoft Purview : l’audit doit être activé pour votre organisation. Consultez Activer ou désactiver l’audit.
- Microsoft Defender : la recherche avancée doit être configurée pour permettre l'accès à la table CloudAppEvents. Consultez la table CloudAppEvents dans le schéma de repérage avancé.
La télémétrie peut prendre plusieurs minutes pour se mettre à jour après une exportation réussie. Attendez avant d’enquêter plus loin.
Vérifiez que les plages contiennent des attributs microsoft.tenant.id et gen_ai.agent.id valides. Les attributs d'identité manquants entraînent la suppression des traces côté serveur même si l'exportation via HTTP retourne un code 200.

Commentaires

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

Last updated on 2026-05-01

Distribution OpenTelemetry de Microsoft

Principaux avantages

Installation et configuration

Installer la bibliothèque

Paramétrage

Propager le contexte

Attributs des bagages

Intergiciels de bagages

Valider que les données circulent dans le produit

Instrumentation automatique

Couverture de l’instrumentation

Bibliothèques d’instrumentation intégrées

Noyau sémantique

OpenAI

Infrastructure de l’agent

LangChain

Instrumentation manuelle

Invocation de l’agent

Exécution de l’outil

Inférence

Sortie

Validation locale

Valider avec un point de terminaison OTLP local

Valider avec la sortie locale

Configurer manuellement l’authentification

Résolveur de jeton manuel

Cache de jetons agentique avec des applications Agent Framework

Exemples d’applications et configuration avancée

Résolution des problèmes

Les données d’observabilité n’apparaissent pas

ID de locataire ou ID d’agent manquant : sections ignorées

Échec de résolution de jeton : exportation ignorée ou non autorisée

HTTP 401 Non autorisé

HTTP 403 Interdit

HTTP 429 / 5xx — Erreurs temporaires

Délai d’expiration de l’exportation

L'exportation réussit, mais la télémétrie n'apparaît pas dans Defender ou Purview

Commentaires

Ressources supplémentaires