OpenTelemetry Distro de Microsoft

Microsoft OpenTelemetry Distro est une distribution d’observabilité unifiée qui fournit une expérience d’intégration unique pour collecter les traces, les métriques et les journaux des applications agentiques et non agentiques. Il prend en charge l’observabilité pour Microsoft Agent 365, Microsoft Foundry, Azure Monitor, ainsi que tout backend compatible avec le protocole OpenTelemetry (OTLP). La distribution prend en charge .NET, Node.js et Python, et remplace la configuration fragmentée sur plusieurs solutions d’observabilité par une seule importation et une seule configuration.

Principaux avantages

La distribution Microsoft OpenTelemetry offre les avantages suivants :

  • Un package, une API : remplace plusieurs paquets d’exportation et d’instrumentation par une seule dépendance.
  • Prise en charge de plusieurs backends : envoyez la télémétrie vers Azure Monitor, tout point de terminaison compatible OTLP (OpenTelemetry Protocol) tel que Datadog, Grafana ou New Relic, et Microsoft Agent 365 simultanément.
  • Instrumentations intégrées : utilisez l’instrumentation automatique pour HTTP, bases de données, Kit de développement logiciel Azure, Azure Functions, et plus encore, sans configuration additionnelle.
  • Basé sur des standards : s’appuie sur OpenTelemetry, le cadre de référence d’observabilité standard de l’industrie.
  • Code minimal : ajoutez une importation et un appel de fonction au point d’entrée de votre application.

Installation et configuration

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

Installer la bibliothèque

Pour commencer avec la distribution Microsoft OpenTelemetry, installez la bibliothèque appropriée pour votre plateforme de développement en utilisant le gestionnaire de packages de votre langage.

Prérequis : Python 3.10 ou plus récent.

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 Agent 365, spécifiez la cible de l’exportateur et fournissez un programme de résolution de jetons qui retourne un jeton d’accès pour un identifiant d’assistant et un identifiant de locataire donnés.

Appelez 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 une résolution personnalisée de jetons (au lieu du résolveur de jeton par défaut), voir programme de résolution de jetons.

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

Paramètre Description Par défaut
a365_use_s2s_endpoint Lorsque True, le chemin du point de terminaison de service à service est utilisé. False
a365_max_queue_size Taille maximale de la file d’attente pour le processeur par lots. 2048
a365_scheduled_delay_ms Délai 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 maximale de lots pour les opérations d’exportation. 512

Propager le contexte

Pour maintenir l’observabilité à travers les opérations distribuées de l’Agent 365, propagez le contexte. Lorsque vous propagez le contexte à travers vos assistants et services, vous garantissez que les traces, journaux et métriques sont correctement corrélés sur l’ensemble du cycle de vie de la requête. Cette corrélation est nécessaire pour une expérience de surveillance Microsoft Agent 365 complète et efficace.

Attributs de bagage

Permet BaggageBuilder de définir des informations contextuelles qui transitent par toutes les étendues d’une requête. Le kit de développement logiciel (SDK) implémente une SpanProcessor et copie de toutes les entrées de bagages sans avoir à remplacer 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’aide populate dans le package microsoft-opentelemetry. Cet utilitaire extrait automatiquement l’appelant, l’assistant, le locataire, 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

Intergiciel de bagages

Si votre assistant utilise le package d’intégration d’hébergement, enregistrez l’intergiciel de bagage pour renseigner automatiquement le bagage à chaque requête entrante. Cette étape élimine le besoin d’appeler BaggageBuilder manuellement dans chaque gestionnaire d’activité.

En Python, enregistrez l’intergiciel de bagage 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 (événements ContinueConversation) afin d’éviter de remplacer les bagages que la demande d’origine a déjà définie.

Validez que les données circulent en produit

Pour consulter la télémétrie des assistants dans Microsoft Purview ou Microsoft Defender, assurez-vous que les exigences suivantes sont remplies :

Instrumentation automatique

Le Microsoft OpenTelemetry Distro combine les pipelines OpenTelemetry standard avec des instrumentations sélectionnées par Microsoft. Le Distro peut collecter la télémétrie des applications, la télémétrie de l’infrastructure ainsi que la télémétrie des assistants ou de l’IA générative, selon le langage et la configuration.

Catégorie Ce que cela couvre
Pipelines de signaux Traçage, mesures et journaux.
Détection des ressources Contexte de service, d’hôte, de cloud et d’exécution Azure, lorsque 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, lorsque pris en charge.
Instrumentation de l’IA générative OpenAI, Azure OpenAI, Noyau sémantique, LangChain, OpenAI Agents SDK et Agent Framework, lorsque pris en charge.
Étendues manuelles des assistants Télémétrie des invocations d’assistants, de l’exécution des outils, de l’inférence et des sorties, lorsque cela est pris en charge.
Exportateurs et processeurs Azure Monitor, Microsoft Agent 365, OTLP, sortie console, processeurs de spans, processeurs de journal et lecteurs de métriques.

Couverture de l’instrumentation

Langage Instrumentation d’application commune Instrumentations courantes pour les assistants et l’IA générative
Python Ressources OpenTelemetry, processeurs, lecteurs, journalisation, métriques et traces. Noyau sémantique, OpenAI Agents SDK, Agent Framework, LangChain, baggage Microsoft Agent 365 et scopes Microsoft Agent 365.
Node.js HTTP, Kit de développement logiciel (SDK) Azure, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan et Winston. OpenAI Agents SDK, LangChain, baggage Microsoft Agent 365 et scopes 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, baggage Microsoft Agent 365 et scopes Microsoft Agent 365.

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

Ajoutez des sources, compteurs, processeurs ou lecteurs OpenTelemetry personnalisés lorsque votre application émet de la télémétrie qui n’est pas couverte par les instrumentations intégrées.

Important

L’instrumentation automatique renseigne uniquement les attributs OpenTelemetry standard. Elle n’inclut pas tous les attributs requis par Agent 365. Vous devez ajouter des attributs spécifiques à Microsoft à l’aide de BaggageBuilder. Pour voir quels attributs sont requis, consultez Attributs de validation du magasin.

Bibliothèques d’instrumentation intégrées

L’auto-instrumentation écoute la télémétrie émise par les frameworks pris en charge et la transmet via le pipeline OpenTelemetry du Distro. Pour les scénarios d’assistant, définissez les bagages, tels que l’ID du locataire et l’ID de l’assistant, avant que le framework instrumenté ne crée des spans.

Structure Python Node.js .NET
Noyau sémantique Pris en charge Non pris en charge Prise en charge
OpenAI et SDK Agents OpenAI Prise en charge Pris en charge Prise en charge
Agent Framework Pris en charge Non pris en charge Prise en charge
LangChain Prise en charge Prise en charge Non listé

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

Agent Framework

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

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 le fonctionnement de l’assistant avec suffisamment de détails. Les étendues manuelles permettent à une application de décrire les activités courantes des assistants de manière cohérente à travers les langages.

Portée Utiliser pour
InvokeAgentScope Le début et l’achèvement d’un appel d’agent.
ExecuteToolScope Un appel d’outil effectué par un assistant.
InferenceScope Une opération d’inférence de modèle IA.
OutputScope Sortie devant être enregistrée après la fin du scope d’origine.

Réutilisez les mêmes valeurs de requête et d’identité d’assistant à travers les portées d’une requête afin que la télémétrie associée puisse être corrélée.

Appel de l’assistant

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

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

La documentation du produit doit définir toutes les exigences de validation spécifiques au produit pour ces périmètres.

Validation locale

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

Valider avec un point de terminaison OTLP local

Configurez la distribution pour envoyer la télémétrie vers 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 sortie locale

Utilisez la sortie locale lorsque vous souhaitez confirmer l’instrumentation avant d’envoyer la télémétrie vers 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.

Vérifiez la sortie locale afin d’identifier les spans provenant des sources attendues, telles que les requêtes HTTP, les appels à OpenAI ou à Azure OpenAI, les scopes d’invocation d’assistants, les scopes d’exécution d’outils ou les scopes d’inférence. La validation propre à chaque destination est décrite dans la documentation du produit concerné.

Configurer manuellement l’authentification

Lorsque vous utilisez l’exportateur Agent 365, vous devez mettre en place un mécanisme pour fournir un jeton d’authentification. Le résolveur de jetons fonctionne par lot d’exportation en utilisant l’ID de l’assistant et l’ID du locataire issus du contexte baggage actif. La distribution prend en charge deux approches.

Astuce

Si vous créez des assistants avec Microsoft 365 Agents SDK, consultez Configuration de l’authentification pour l’observabilité avec le Kit de développement logiciel (SDK) Agent pour des instructions étape par étape sur la configuration de l’acquisition de jetons OBO et S2S, aussi bien pour les assistants agentiques que non agentiques.

Programme de résolution de jetons

Utilisez un programme de résolution de jetons manuel lorsque vous acquérez des jetons en dehors du pipeline Agent Framework, lorsque vous développez des applications qui ne reposent pas sur l’Agent Framework, ou lorsque vous utilisez l’authentification service à service (S2S) (flux d’informations d’identification du client). Les assistants peuvent générer eux-mêmes un jeton, par exemple en utilisant Microsoft Authentication Library (MSAL) ou toute autre méthode d’acquisition de jetons, mais ils doivent s’assurer que le jeton dispose de la portée d’observabilité correcte (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Note

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

Les exemples suivants montrent le modèle de résolution de jeton OBO (on-behalf-of) : l’assistant acquiert un jeton utilisateur via le gestionnaire d’authentification agentique et l’échange contre un jeton limité à la portée de l’observabilité. Pour des exemples S2S (service-à-service) et une comparaison entre l’authentification OBO et S2S, voir Configuration de l’authentification d’observabilité pour le SDK Agent.

Le programme de résolution doit être synchrone. Acquérez le jeton dans votre gestionnaire d’activité asynchrone (ou via MSAL) et mettez-le 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 assistant appelle RegisterObservability() à l’exécution pour fournir les identifiants, et le cache gère l’acquisition et l’actualisation des jetons.

Note

Cette approche prend uniquement en charge les flux d’authentification On-Behalf-Of (OBO). Pour l’authentification service-à-service (S2S), utilisez plutôt le programme de résolution manuel de 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,
    )

Attributs de validation de magasin

Pour une validation réussie du store, votre assistant doit implémenter InvokeAgentScope, InferenceScope et ExecuteToolScope. Chaque étendue correspond à une opération de span dans le schéma canonique :

Étendue 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 la liste complète des attributs requis et optionnels par périmètre — y compris la sémantique de chaque attribut, les conseils de sélection des valeurs et les attributs interrogeables via Microsoft Defender advanced hunting — consultez la référence des attributs d’observabilité Agent 365. La colonne S’applique à identifie la portée à laquelle chaque attribut appartient, et la colonne Obligatoire distingue les attributs obligatoires (M) des attributs optionnels (O).

Tester votre assistant avec l’observabilité

Après avoir implémenté l’observabilité, vérifiez que la télémétrie est capturée :

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

Exemples d’applications et configuration avancée

Pour des exemples fonctionnels et des options de configuration avancées, voir les dépôts GitHub pour chaque langage :

Résolution des problèmes

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

Problème Description
Les données d’observabilité n’apparaissent pas Aucune télémétrie n’est visible car l’export pour Agent 365 n’est pas activé, la configuration est incomplète ou la résolution du jeton échoue.
ID de locataire ou ID d’assistant manquant : spans ignorés Les spans sont filtrés avant leur exportation lorsque les attributs d’identité requis du locataire ou de l’assistant sont absents.
Échec de résolution de jeton : exportation ignorée ou non autorisée 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 requêtes atteignent le service mais l’authentification échoue car le jeton est invalide, expiré ou destiné à une audience incorrecte.
HTTP 403 Interdit L’autorisation échoue en raison de licences de locataire manquantes ou d’autorisations d’écriture d’observabilité manquantes.
HTTP 403 Interdit — incompatibilité d’ID d’assistant Le service refuse l’exportation lorsque l’identifiant de l’assistant dans la requête ne correspond pas à l’identité d’assistant autorisée par le jeton.
Erreurs HTTP 429 ou 5xx - Erreurs transitoires Une limitation temporaire du débit ou une instabilité du backend interrompt l’exportation et peut nécessiter de nouvelles tentatives ou un ajustement de la taille des lots.
Délai d’expiration de l’exportation Les opérations d’exportation dépassent les limites de délai en raison de 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 ni dans Defender ni dans 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 du schéma.

Astuce

Le Guide de dépannage 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’assistant est en cours d’exécution
  • Pas de télémétrie dans le centre d’administration
  • Impossible de voir l’activité de l’assistant

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érifiez que l’exportation Agent 365 est activée

    Vous devez explicitement activer l’exportateur Agent 365. Lorsque vous ne le définissez pas, le Distro peut revenir à un exportateur de console ou ne rien exporter du tout. 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 basculement secondaire qui ne prend effet que lorsque enable_a365=True est défini dans le code. Vous pouvez également le contrôler via le kwarg a365_enable_observability_exporter.

  • Vérifier la configuration du programme de résolution de jetons

    L’exportateur nécessite un programme de résolution de jetons valide qui renvoie un jeton porteur pour chaque demande d’exportation. Si le résolveur de jeton est manquant ou retourne null, l’exportation est ignorée sans notification.

  • Activez l’exportation sur console et vérifiez la télémétrie localement

    Ajoutez un exportateur console pour vérifier que la télémétrie est générée avant qu’elle n’atteigne le point de terminaison d’Agent 365 :

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Activer la journalisation détaillée

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Consultez les journaux pour des erreurs d’exportation

    Utilisez la commande az webapp log tail pour rechercher dans les journaux des erreurs liées à l’observabilité :

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

ID de locataire ou ID d’assistant manquant : spans ignorés

Symptômes : le système écarte silencieusement les spans 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 ignorent sans journalisation.

Solution :

  • Avant l’exportation, le distro partitionne les spans selon l’identité du locataire et de l’assistant. Les spans dépourvus d’un ID de locataire ou d’un ID d’assistant sont ignorés et ne sont jamais envoyés au service.
  • Assurez-vous que BaggageBuilder soit configuré avec l’ID de locataire et l’ID d’assistant avant de créer des spans. Ces valeurs se propagent via le contexte OpenTelemetry et s’attachent à tous les spans créés dans le contexte de bagages. Pour l’API spécifique à la plateforme, consultez Attributs des bagages.
  • Si vous utilisez le middleware baggage ou l’assistant de contexte de tour du package d’intégration d’hébergement, vérifiez que l’activité TurnContext possède un destinataire valide avec une identité d’assistant.

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

Symptômes : le programme de résolution de jetons renvoie null ou lance une erreur. Selon la plateforme, l’exportation peut être entièrement ignorée ou échouer avec une erreur HTTP 401.

Solution :

  • Le programme de résolution de jetons est obligatoire. S’il manque, l’exportateur affiche une erreur au démarrage. Vérifiez qu’un programme de résolution de jetons est fourni et retourne un jeton Bearer valide.
  • Assurez-vous que l’ID de locataire et l’identifiant de l’assistant corrects sont transmis à BaggageBuilder, car ces valeurs sont ensuite transmises au programme de résolution de jetons.
  • Pour les assistants hébergés sur Azure, vérifiez que l’identité managée dispose des autorisations API requises pour la portée d’observabilité.
  • Pour les applications .NET utilisant le package d’hébergement Agent Framework, l’échange de jetons est géré automatiquement via DI. Si des jetons manquent, confirmez que Microsoft.Agents.A365.Observability.Hosting est installé et l’enregistrement sont faits.

HTTP 401 Non autorisé

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

Solution :

  • Vérifiez que l’audience du jeton correspond à l’étendue du point de terminaison d’observabilité.
  • Vérifiez que le programme de résolution de jetons ne retourne pas un 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éessaie pas cette erreur.

Cause profonde : une erreur HTTP 403 peut avoir différentes causes. Consultez les résolutions suivantes dans l’ordre.

Solution :

  • Licence manquante — Assurez-vous que votre locataire dispose de l’une des licences suivantes dans le centre d’administration Microsoft 365 :

    • Test - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Autorisation Agent365.Observability.OtelWrite manquante — Accorder l’autorisation à votre identité (identité gérée ou inscription à l’application). Sans cela, l’exportation de la télémétrie échoue avec HTTP 403.

Accorder l’autorisation

Utilisez l’une ou l’autre de ces options :

  • CLI Agent 365

    Nécessite un compte administrateur général ; exécuter depuis le répertoire du projet assistant contenant a365.config.json, ou utiliser --agent-name.

    a365 setup permissions bot

    Ou, sans fichier de configuration :

    a365 setup permissions bot --agent-name "<agent-name>"

  • Portail Entra

    Aucun fichier de configuration requis ; accès administrateur général requis à l’enregistrement de l’application Blueprint.

    1. Allez dans le portail Entra>Inscriptions d’applications>, puis sélectionnez votre application Blueprint.
    2. Allez dans Autorisations d’API>Ajouter une autorisation>Les API utilisées par mon organisation> recherchez 9b975845-388f-4429-889e-eab1ef63949c.
    3. Sélectionnez Autorisations déléguées> cochez Agent365.Observability.OtelWrite>Ajouter des autorisations.
    4. Répétez les étapes 2–3, cette fois sélectionnez Autorisations d’application> cochez Agent365.Observability.OtelWrite>Ajouter des autorisations.
    5. Cliquez sur Accorder le consentement d’administrateur et confirmez.

    Les deux Agent365.Observability.OtelWrite (Délégué) et Agent365.Observability.OtelWrite (Application) affichent l’état Granted.

HTTP 403 Interdit — incompatibilité d’ID d’assistant

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 traces d’Agent 365.

Cause principale : cette erreur survient lorsque vous utilisez l’ID client blueprint au lieu de l’ID client de l’instance de l’assistant lors de la définition des détails de l’assistant. L’identifiant de l’assistant dans l’URL d’exportation ne correspond pas à l’identité autorisée par le jeton, donc le point de terminaison des traces rejette la requête.

Solution :

  • Vérifiez si l’ID de locataire est ajouté à la liste des locataires autorisés d’Agent 365.
  • Définissez les détails de l’assistant avec l’ID client de l’instance de l’assistant (et non l’ID client blueprint).
  • Vérifiez l’URL d’exportation générée – elle est enregistrée si vous activez votre enregistreur. Confirmez que l’ID de l’assistant dans l’URL correspond à l’ID de l’assistant de l’instance de l’assistant.
  • Pour activer la journalisation des diagnostics par Kit de développement logiciel (SDK), voir Validation locale.

Erreurs HTTP 429 ou 5xx - Erreurs transitoires

Symptômes : l’exportation échoue avec un code de statut HTTP transitoire tel que 429 ou 5xx.

Solution :

  • Ces erreurs sont généralement temporaires et se résolvent d’elles-mêmes. Les distributions Python et JavaScript réessaient automatiquement en cas de codes d’état HTTP 408, 429 ou 5xx. La distribution .NET ne réessaie pas automatiquement.
  • Si les erreurs persistent, vérifiez le tableau de bord de santé du service.
  • Envisagez de réduire la fréquence d’exportation en augmentant le délai prévu entre les lots ou la taille maximale des lots d’exportation. Pour Python et JavaScript, utilisez les paramètres pertinents exporterOptions ou a365_* documentés dans les dépôts 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.

Solution :

  • Vérifiez la connectivité réseau vers le point d’extrémité d’observabilité.

  • Le délai d’expiration par défaut des requêtes HTTP est de 30 secondes sur toutes les plateformes. Si des délais d’expiration surviennent fréquemment, augmentez la valeur du délai d’expiration dans les options de votre exportateur :

    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 la liste complète des options a365_*.

L’exportation réussit, mais la télémétrie n’apparaît ni dans Defender ni dans Purview

Symptômes : les journaux indiquent une exportation réussie (HTTP 200), mais la télémétrie n’est pas visible dans Microsoft Defender ou Microsoft Purview.

Solution :

  • Vérifiez que vous remplissez les conditions préalables pour afficher les journaux exportés :
  • La télémétrie peut prendre plusieurs minutes pour être renseignée après une exportation réussie. Attendez avant d’enquêter davantage.
  • Vérifiez que les spans contiennent des attributs microsoft.tenant.id et gen_ai.agent.id valides. L’absence d’attributs d’identité entraîne l’abandon des spans côté serveur, même si l’exportation HTTP renvoie un code 200.

Contenu associé

  • Last updated on