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.

Note

Si vous maintenez une intégration existante utilisant l’ancien SDK d’observabilité Agent 365, consultez la documentation du SDK obsolète et les guides de migration.

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

Configuration

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.

Par défaut, la distro exporte sur la route déléguée, ce qui nécessite l’autorisation déléguée Agent365.Observability.OtelWrite et le consentement de l’administrateur. La a365 setup all commande ne configure pas cette permission pour les agents blueprint, donc utilisez S2S avec un résolveur uniquement applicatif pour ces agents. Une instance d’agent enregistré peut exporter sur la route S2S sans autorisation d’observabilité ni consentement administrateur.

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.

Vous pouvez personnaliser le comportement de l’exportateur en passant des kwargs facultatifs a365_* à use_microsoft_opentelemetry().

Paramètre Description Default
a365_use_s2s_endpoint Quand True est utilisé, le chemin du point de terminaison de service à service est employé. Utilisez avec un résolveur de jetons App-Only. False
a365_max_queue_size Taille de file d’attente maximale pour le processeur par lots. 2048
a365_scheduled_delay_ms Retard en millisecondes entre les lots d’exportation. 5000
a365_exporter_timeout_ms Délai d’expiration en millisecondes pour l’opération d’exportation. 30000
a365_max_export_batch_size Taille de lot maximale pour les opérations d’exportation. 512

Propager le contexte

Pour maintenir l’observabilité sur l’ensemble des opérations distribuées d’Agent 365, propagez 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

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.

Valider que les données circulent dans le produit

Pour consulter la télémétrie des agents dans Microsoft Purview ou Microsoft Defender, assurez-vous de respecter les exigences suivantes :

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.

Category 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.

Important

L’instrumentation automatique renseigne uniquement les attributs OpenTelemetry standards. Il n’inclut pas tous les attributs requis par Agent 365. Vous devez ajouter des attributs spécifiques à Microsoft via BaggageBuilder. Pour voir quels attributs sont requis, consultez les attributs de validation du Windows Store.

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.

Framework Python Node.js .NET
Noyau sémantique Supported Non pris en charge Supported
OpenAI et SDK d'agents OpenAI Supported Supported Supported
Infrastructure de l’agent Supported Non pris en charge Supported
LangChain Supported Supported 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},
    },
)

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

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

LangChain

Note

L’instrumentation automatique pour l’infrastructure LangChain prend également en charge LangGraph et Deep Agents. La même instrumentation capture automatiquement les données de télémétrie pour les agents créés avec l’une de ces infrastructures.

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

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.

Scope Utilisé 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."])

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)

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

Output

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

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

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.

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 distro prend en charge deux approches.

Pour les agents blueprint compatibles Agent 365 configurés avec a365 setup all, utilisez S2S avec un résolveur uniquement applicatif. Le cache de jetons agentique intégré et les exemples OBO sur cette page utilisent la route déléguée, qui nécessite la permission déléguée Agent365.Observability.OtelWrite et le consentement de l’administrateur. La a365 setup all commande ne configure pas cette permission pour les agents blueprint.

Tip

Si vous créez des agents avec le Microsoft 365 Agents SDK, consultez Configuration de l’authentification d’observabilité pour le SDK Agent pour obtenir des instructions pas à pas sur la façon de configurer l’obtention de jetons OBO et S2S pour les agents agentiques et non agentiques.

Résolveur de jeton manuel

Utilisez un résolveur manuel lorsque vous acquérez des jetons en dehors du pipeline Agent Framework, lorsque vous développez des applications non-Agent Framework, ou lorsque vous utilisez l’authentification service-à-service (S2S). Le jeton que votre résolveur retourne doit correspondre à la route. Pour la route déléguée, retournez un jeton délégué avec la portée Agent365.Observability.OtelWrite. Pour la route S2S, retournez le dernier jeton uniquement applicatif que vous demandez avec la api://9b975845-388f-4429-889e-eab1ef63949c/.default portée. Un agent blueprint enregistré sur S2S n’a pas besoin du Agent365.Observability.OtelWrite rôle ni du consentement administrateur.

Note

Pour l’authentification de service à service (S2S), vous devez utiliser cette approche manuelle de résolution de jeton. Le cache de jetons agentique prend uniquement en charge les flux d’authentification de type on-behalf-of (OBO).

Les exemples suivants montrent le modèle de résolution de jeton OBO (on-behalf-of) — l’agent acquiert un jeton utilisateur via le gestionnaire d’authentification agentique et l’échange contre un jeton limité à la portée de l’observabilité. Ces exemples nécessitent la permission déléguée Agent365.Observability.OtelWrite et le consentement de l’administrateur. Pour des exemples de S2S (service-à-service) et une comparaison entre les authentifications OBO et S2S, consultez Configuration de l’authentification Observability pour le SDK d’agent.

Le programme de résolution doit être synchrone. Acquérir le jeton dans votre gestionnaire d’activités asynchrones (ou via MSAL) 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",
    )

Cache de jetons agentique avec des applications Agent Framework

Pour les applications Agent Framework qui utilisent l’authentification On-Behalf-Of (OBO), la distribution enregistre automatiquement IExporterTokenCache<AgenticTokenStruct> via DI lorsque vous ne définissez pas de TokenResolver personnalisé. Votre agent appelle RegisterObservability() à l’exécution pour fournir des identifiants, et le cache gère l’acquisition et le rafraîchissement des tokens délégués.

Note

Cette approche ne prend en charge que les flux d’authentification en nom de (OBO) sur la route déléguée, ce qui nécessite l’autorisation déléguée Agent365.Observability.OtelWrite et le consentement de l’administrateur. Pour l’authentification service-à-service (S2S), y compris les agents Blueprint configurés avec a365 setup all, utilisez le résolveur manuel de jeton avec un jeton uniquement applicatif. Pour les étapes de configuration, voir Agent 365 activé avec S2S.

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,
    )

Stocker les attributs de validation

Pour une validation réussie du magasin, votre agent doit implémenter InvokeAgentScope, InferenceScopeet ExecuteToolScope. Chaque portée correspond à une opération de span dans le schéma canonique :

Étendue du Kit de développement logiciel (SDK Opération de span Code de référence universel
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Pour consulter les listes complètes des attributs obligatoires et facultatifs pour chaque portée, y compris la signification de chaque attribut, des conseils pour le choix des valeurs et les attributs qui peuvent faire l’objet de requêtes via Microsoft Defender Advanced Hunting, consultez Référence des attributs d’observabilité d’Agent 365. La colonne S’applique à la colonne identifie l’étendue à laquelle appartient chaque attribut, et la colonne Obligatoire distingue les attributs obligatoires (M) des attributs facultatifs (O).

Testez votre agent avec l’observabilité

Après avoir implémenté l’observabilité, vérifiez que les données de télémétrie sont capturées :

  1. Accédez à https://admin.cloud.microsoft/#/agents/all.
  2. Sélectionnez votre agent, puis sélectionnez Activité.
  3. Vérifiez que les sessions et les appels d’outil s’affichent.

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éférence de programmation

Pour examiner les types de Microsoft OpenTelemetry Distro, consultez les articles de référence en programmation suivants :

Troubleshooting

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.

Problème Description
Les données d’observabilité n’apparaissent pas Aucune télémétrie n’est visible car l’export de l’Agent 365 n’est pas activé, la configuration n’est pas terminée ou la résolution des jetons échoue.
ID du locataire ou ID de l’agent manquant - segments ignorés Les spans sont filtrés avant leur exportation lorsque les attributs d’identité requis du locataire ou de l’agent sont absents.
Échec de la résolution du jeton - export ignoré ou non autorisé L’exportation est ignorée ou rejetée lorsque le programme de résolution de jeton ne retourne aucun jeton ou erreur lors de l’acquisition du jeton.
HTTP 401 Non autorisé Les demandes atteignent le service, mais l’authentification échoue, car le jeton n’est pas valide, a expiré ou pour le mauvais public.
HTTP 403 Interdit L’autorisation échoue en raison de l’absence de licence locataire, d’une identité S2S non enregistrée, ou de permissions d’écriture d’observabilité manquantes là où elles sont requises.
HTTP 403 Interdit - Incompatibilité de l’ID de l’agent Le service rejette l’exportation lorsque l’ID de l’agent dans la demande ne correspond pas à l’identité de l’agent autorisé par jeton.
Erreurs HTTP 429 ou 5xx - Erreurs temporaires Une limitation temporaire ou une instabilité backend interrompt l’exportation et peut nécessiter de nouvelles tentatives ou un réglage en lot.
Délai d’expiration d’exportation Les opérations d’exportation dépassent les limites de délai d’expiration en raison des retards réseau ou de la latence de réponse du point de terminaison.
L'exportation réussit, mais la télémétrie n'apparaît pas dans Defender ou Purview L’ingestion des données réussit, mais la visibilité est retardée ou bloquée par les prérequis en aval et les exigences de schéma.

Tip

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

    Note

    ENABLE_A365_OBSERVABILITY_EXPORTER est un bouton bascule secondaire qui prend effet uniquement lorsqu’il enable_a365=True est défini dans le code. Vous pouvez également le contrôler via le a365_enable_observability_exporter kwarg.

  • 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 :

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Activez la journalisation commentée

    import logging

logging.basicConfig(level=logging.DEBUG)

  • 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 S2S, retournez le jeton d’observabilité uniquement applicatif final pour 9b975845-388f-4429-889e-eab1ef63949c ou api://9b975845-388f-4429-889e-eab1ef63949c. Ne retournez pas l’assertion intermédiaire de blueprint, un jeton blueprint, ni un token utilisateur ou OBO.
  • Pour la route déléguée, retournez un jeton délégué avec la portée Agent365.Observability.OtelWrite.
  • Pour les agents hébergés sur Azure qui exportent directement avec une identité gérée, vérifiez que l’identité gérée a le rôle d’applicationAgent365.Observability.OtelWrite. Les instances enregistrées de l’agent blueprint sur S2S n’en ont pas besoin.
  • 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 est 9b975845-388f-4429-889e-eab1ef63949c ou api://9b975845-388f-4429-889e-eab1ef63949c, et que le type de jeton correspond à la route : un jeton délégué pour la route déléguée, ou un jeton uniquement applicatif pour la route S2S.
  • Pour S2S, vérifiez que le résolveur ne retourne pas un jeton utilisateur délégué, une assertion de blueprint intermédiaire, un jeton blueprint, un token pour une audience incorrecte, ou un jeton expiré.
  • Pour la route déléguée, vérifiez que le claim du jeton scp contient Agent365.Observability.OtelWrite et que le jeton n’est pas 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

  • Identité non enregistrée sur S2S — Une instance d’agent blueprint enregistrée peut exporter sur la route S2S avec un jeton uniquement applicatif qui n’a aucun Agent365.Observability.OtelWrite rôle. Si l’identité n’est pas enregistrée auprès de l’Agent 365, le service renvoie HTTP 403 insufficient_scope. Pour les agents blueprint, a365 setup all enregistre l’instance de l’agent. Pour relancer un enregistrement échoué, exécutez a365 setup all --agent-registration-only. Créer une identité Microsoft Entra seule ne permet pas d'enregistrer l'instance de l'agent.

  • Permission manquante Agent365.Observability.OtelWrite là où elle est requise — Accordez l’autorisation pour la route déléguée ou pour les identités non enregistrées, y compris les enregistrements d’application standard. Les agents blueprint enregistrés sur S2S n’ont pas besoin de cette autorisation.

Accorder l’autorisation

N’accordez Agent365.Observability.OtelWrite que lorsque vous utilisez la route déléguée ou une identité non enregistrée. Les agents Blueprint enregistrés qui utilisent S2S n’ont pas besoin de cette permission ni du consentement administrateur. N’accordez que le type d’autorisation utilisé par votre route :

  • Route déléguée : Ajoutez l’autorisation déléguée.
  • Route S2S avec une identité non enregistrée, comme l’enregistrement standard de l’application utilisé par un agent du moteur personnalisé : ajouter la permission de l’application (rôle application).

Utilisez une de ces options :

  • Agent 365 CLI (agents de plan sur le chemin délégué)

    Cette commande ajoute la permission déléguée à votre blueprint ainsi que ses permissions héréditaires, puis accorde le consentement de l’administrateur. Il n’ajoute pas la permission d’application. Cela nécessite un compte administrateur global. Exécutez la commande depuis le répertoire du projet agent qui contient a365.config.json, ou ajoutez --agent-name "<agent-name>".

    a365 setup permissions custom --resource-app-id 9b975845-388f-4429-889e-eab1ef63949c --scopes Agent365.Observability.OtelWrite

  • centre d’administration Microsoft Entra (par l’une ou l’autre voie)

    Aucun fichier de configuration requis ; nécessite un accès Administrateur général à l’enregistrement de l’application. Pour un blueprint sur la route déléguée, utilisez cette option uniquement si le blueprint possède déjà l’API d’observabilité dans ses autorisations héritables, comme un blueprint configuré par une version antérieure de la CLI. Sinon, utilisez la CLI de l’Agent 365.

    1. Allez dans le centre d’administration centre d’administration Microsoft Entra, sélectionnez inscriptions d'applications, puis sélectionnez votre enregistrement d’application Blueprint ou Standard.
    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 la route déléguée, ou Autorisations Application pour une identité non enregistrée sur la route S2S.
    4. Cochez Agent365.Observability.OtelWrite, puis sélectionnez Ajouter les permissions.
    5. Sélectionnez Accorder le consentement de l’administrateur et confirmez.

    L’autorisation que vous avez ajoutée affiche le statut Granted.

HTTP 403 Interdit — Incompatibilité de l’ID de l’agent

Symptômes: L’exportation échoue avec HTTP 403 et un message du serveur similaire à 403 Forbidden, avec des échecs agent-ID-mismatch lors de l’appel aux points de terminaison de traçage d’Agent 365.

Cause: Cette erreur se produit lorsque vous utilisez l’ID client du blueprint au lieu de l’ID client de l’instance de l’agent lors de la définition des détails de l’agent. L’ID de l’agent dans l’URL d’exportation ne correspond pas à l’identité autorisée par le jeton. Par conséquent, le point de terminaison de trace rejette la requête.

Résolution :

  • Vérifiez si l’identifiant du locataire figure dans la liste des locataires autorisés d’Agent 365.
  • Définissez les détails de l’agent avec l’ID client de l’instance de l’agent (et non l’ID client du blueprint).
  • Vérifiez l’URL d’exportation générée : elle est journalisée si vous activez votre enregistreur d’événements. Vérifiez que l’ID de l’agent dans l’URL correspond à l’ID client de l’instance de l’agent.
  • Pour activer la journalisation des diagnostics par kit SDK, consultez validation locale.

Erreurs HTTP 429 ou 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_*.

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 :
  • 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.

Contenu connexe

  • Last updated on