Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro è una distribuzione unificata per l'osservabilità che offre un'esperienza unica di onboarding per la raccolta di tracce, metriche e log da applicazioni con agente e senza agente. Supporta l'osservabilità per Microsoft Agent 365, Microsoft Foundry, Monitoraggio di Azure e qualsiasi back-end compatibile con OTLP (OpenTelemetry Protocol). La distribuzione supporta .NET, Node.jse Python e sostituisce la configurazione frammentata in più stack di osservabilità con un'importazione e una chiamata di configurazione.

Note

Se mantieni un'integrazione esistente che utilizza il precedente SDK di osservabilità di Agent 365, consulta la documentazione obsoleta dell'SDK e le guide di migrazione.

Vantaggi principali

La distribuzione Microsoft OpenTelemetry offre questi vantaggi:

  • Un pacchetto, un'API: sostituire più pacchetti di utilità di esportazione e strumentazione con una singola dipendenza.
  • Supporto multi-back-end: inviare dati di telemetria a Monitoraggio di Azure, qualsiasi endpoint compatibile con OPENTelemetry Protocol (OTLP), ad esempio Datadog, Grafana o New Relic e Microsoft Agent 365 contemporaneamente.
  • Strumentazioni predefinite: usare la strumentazione automatica per HTTP, database, Azure SDK, Funzioni di Azure e altro ancora senza alcuna configurazione aggiuntiva.
  • Basato sugli standard: basato su OpenTelemetry, il framework di osservabilità standard del settore.
  • Boilerplate minimo: aggiungi un'importazione e una chiamata di funzione al punto di ingresso dell'applicazione.

Installazione e configurazione

Questa guida illustra come aggiungere l'osservabilità all'applicazione con la Distribuzione OpenTelemetry di Microsoft. La distribuzione raccoglie automaticamente tracce, metriche e log con strumentazioni predefinite ed esporta i dati di telemetria in Monitoraggio di Azure, qualsiasi endpoint OTLP (OpenTelemetry Protocol) o Microsoft Agent 365.

Installare la libreria

Per iniziare a usare la distribuzione Microsoft OpenTelemetry, installare la libreria appropriata per la piattaforma di sviluppo usando la gestione pacchetti del linguaggio.

Prerequisites: Python 3.10 o versione successiva.

pip install microsoft-opentelemetry

Configuration

L'utilità di esportazione Agent 365 non usa una stringa di connessione. Individua automaticamente l'endpoint in base al tenant. Per abilitare l'esportazione in Agent 365, impostare la destinazione dell'esportazione e fornire un resolver di token che restituisce un token di accesso per un ID agente e un ID tenant specificati.

Per impostazione predefinita, la distro esporta sulla route delegata, che richiede il permesso delegato Agent365.Observability.OtelWrite e il consenso dell'amministratore. Il a365 setup all comando non configura quel permesso per gli agenti blueprint, quindi usa S2S con un resolver solo app per quegli agenti. Un'istanza di agente registrato può esportare sulla rotta S2S senza un permesso di Observability o il consenso dell'amministratore.

Chiama use_microsoft_opentelemetry() per abilitare l'osservabilità.

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

Per la risoluzione dei token personalizzata (anziché il resolver di token predefinito), vedere Resolver di token manuale.

È possibile personalizzare il comportamento del componente di esportazione passando facoltativamente a365_* a use_microsoft_opentelemetry().

Parametro Description Default
a365_use_s2s_endpoint Quando True, utilizza il percorso dell'endpoint tra servizi. Da usare con uno strumento di risoluzione di token solo app. False
a365_max_queue_size Dimensione massima della coda per il processore batch. 2048
a365_scheduled_delay_ms Ritardo in millisecondi tra batch di esportazione. 5000
a365_exporter_timeout_ms Timeout in millisecondi per l'operazione di esportazione. 30000
a365_max_export_batch_size Dimensioni massime del batch per le operazioni di esportazione. 512

Propaga contesto

Per mantenere l'osservabilità tra le operazioni distribuite di Agent 365, propagare il contesto. Quando propaghi il contesto tramite agenti e servizi, assicurati che le tracce, i log e le metriche siano correlate correttamente nell'intero ciclo di vita della richiesta. Questa correlazione è necessaria per un'esperienza di monitoraggio completa ed efficace Microsoft Agent 365.

Attributi di bagaglio

Utilizza BaggageBuilder per impostare informazioni contestuali che passano attraverso tutti gli intervalli di una richiesta. L'SDK implementa una SpanProcessor copia di tutte le voci di baggage non interrotte in intervalli appena avviati senza sovrascrivere gli attributi esistenti.

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

Per popolare automaticamente il BaggageBuilder dal TurnContext, usare l'helper populate nel pacchetto microsoft-opentelemetry. Questo helper estrae automaticamente il chiamante, l'agente, il tenant, il canale e i dettagli della conversazione dall'attività.

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

Middleware per la gestione dei bagagli

Se l'agente usa il pacchetto di integrazione dell'hosting, registra il middleware del baggage per popolare automaticamente baggage per ogni richiesta in ingresso. Questo passaggio rimuove la necessità di chiamare BaggageBuilder manualmente in ogni gestore attività.

In Python, configurare il middleware per la gestione dei bagagli tramite ObservabilityHostingManager.configure() anziché direttamente sull'adattatore.

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

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

Il middleware ignora la configurazione del baggage per risposte asincrone (eventi ContinueConversation) per evitare di sovrascrivere baggage già impostati dalla richiesta di origine.

Verificare che i dati fluiscano correttamente nel prodotto

Per visualizzare la telemetria degli agenti in Microsoft Purview o Microsoft Defender, assicurati di soddisfare i seguenti requisiti:

Strumentazione automatica

La distribuzione Microsoft OpenTelemetry combina pipeline OpenTelemetry standard con strumentazione curata da Microsoft. Distro può raccogliere i dati di telemetria dell'applicazione, i dati di telemetria dell'infrastruttura e la telemetria dell'agente o la telemetria generativa dell'intelligenza artificiale a seconda del linguaggio e della configurazione.

Categoria Cosa copre
Pipeline di segnale Tracce, metriche e log.
Rilevamento delle risorse Servizio, host, cloud e contesto di runtime di Azure, se supportato.
Strumentazione dell'infrastruttura Http, ASP.NET Core, Azure SDK, client di database e framework di registrazione, se supportati.
Strumentazione di intelligenza artificiale generativa OpenAI, Azure OpenAI, Kernel semantico, LangChain, OpenAI Agents SDK e Agent Framework, dove supportato.
Ambiti manuali dell'agente Chiamata dell'agente, esecuzione degli strumenti, inferenza e telemetria di output, se supportati.
Esportazioni e processori Monitoraggio di Azure, Microsoft Agent 365, OTLP, output della console, processori di span, processori di log e lettori di metriche.

Copertura della strumentazione

Language Strumentazione comune delle applicazioni Agente comune e strumentazione di intelligenza artificiale generativa
Python Risorse OpenTelemetry, processori, lettori, registrazione, metriche e tracce. Kernel semantico, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 baggage e ambiti Microsoft Agent 365.
Node.js HTTP, Azure SDK, Funzioni di Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan e Winston. OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage e ambiti Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, rilevamento delle risorse, metriche e log. Kernel semantico, OpenAI e Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage e ambiti Microsoft Agent 365.

La strumentazione automatica è in ascolto dei segnali di telemetria generati da librerie e framework supportati. La strumentazione manuale viene usata quando un'applicazione deve descrivere operazioni specifiche dell'agente, ad esempio chiamate, esecuzione degli strumenti, inferenza o output asincrono.

Aggiungere fonti OpenTelemetry personalizzate, metri, processori o lettori quando l'applicazione genera dati di telemetria non coperti dalle strumentazioni integrate.

Important

La strumentazione automatica popola solo gli attributi OpenTelemetry standard. Non include tutti gli attributi richiesti da Agent 365. È necessario aggiungere attributi specifici di Microsoft tramite BaggageBuilder. Per visualizzare gli attributi necessari, vedere Archiviare gli attributi di convalida.

Librerie di strumentazione integrate

La strumentazione automatica è in ascolto dei dati di telemetria generati dai framework supportati e la inoltra tramite la pipeline OpenTelemetry della distribuzione. Per gli scenari dell'agente, imposta baggage come ID tenant e ID agente prima che il framework instrumentato crei intervalli.

Struttura Python Node.js .NET
Nucleo Semantico Supportato Non supportato Supportato
OpenAI e OpenAI Agents SDK Supportato Supportato Supportato
Framework dell'agente Supportato Non supportato Supportato
LangChain Supportato Supportato Non elencato

Nucleo Semantico

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

Framework dell'agente

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

La strumentazione automatica per il framework LangChain supporta anche LangGraph e Deep Agents. La stessa strumentazione acquisisce automaticamente i dati di telemetria per gli agenti compilati con uno di questi 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={
        "langchain": {"enabled": True},
    },
)

Strumentazione manuale

Usare la strumentazione manuale quando la strumentazione automatica non descrive l'operazione dell'agente con dettagli sufficienti. Gli ambiti manuali consentono a un'applicazione di descrivere le attività comuni degli agenti in modo coerente tra i linguaggi.

Scope Usare per
InvokeAgentScope Inizio e completamento di un'invocazione dell'agente.
ExecuteToolScope Richiesta strumento effettuata da un agente.
InferenceScope Operazione di inferenza del modello di intelligenza artificiale.
OutputScope Output che deve essere registrato dopo il completamento dell'ambito di origine.

Riutilizzare gli stessi valori di identità di richiesta e agente tra gli ambiti di una richiesta in modo che i dati di telemetria correlati possano essere correlati.

Invocazione dell'agente

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

Esecuzione dello strumento

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)

Inferenza

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

Risultato

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 documentazione del prodotto deve definire i requisiti di convalida specifici del prodotto per questi ambiti.

Convalida locale

La convalida locale conferma che l'applicazione produce dati di telemetria prima che venga convalidata una destinazione specifica del prodotto. Usare l'output della console o un endpoint OTLP locale per verificare che vengano create tracce, metriche e log.

Convalidare con un endpoint OTLP locale

Configurare la distribuzione per inviare dati di telemetria a un agente di raccolta locale o a un altro endpoint compatibile con OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Validare con l'output locale

Usare l'output locale quando si vuole confermare la strumentazione prima di inviare dati di telemetria a una destinazione remota.

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.

Esaminare l'output locale per gli intervalli provenienti da fonti previste, come richieste HTTP, chiamate di OpenAI o Azure OpenAI, ambiti di invocazione dell'agente, ambiti di esecuzione degli strumenti, o ambiti di inferenza. La convalida specifica della destinazione appartiene alla documentazione del prodotto per tale destinazione.

Configurare manualmente l'autenticazione

Quando si usa l'utilità di esportazione di Agent 365, è necessario fornire un meccanismo per fornire un token di autenticazione. Il sistema di risoluzione dei token funziona per batch di esportazione usando l'ID agente e l'ID tenant dal contesto del baggage attivo. La distribuzione supporta due approcci.

Per gli agenti blueprint abilitati per Agent 365 configurati con a365 setup all, usa S2S con un resolver solo app. La cache di token agentico integrata e gli esempi OBO in questa pagina utilizzano il flusso delegato, che richiede il permesso delegato Agent365.Observability.OtelWrite e il consenso dell'amministratore. Il a365 setup all comando non configura quel permesso per gli agenti blueprint.

Tip

Se si stanno sviluppando agenti con il Managed Disks, consultare Observability Authentication Setup for Agent SDK per istruzioni dettagliate su come configurare l'acquisizione di token OBO e S2S per agenti agentici e non agentici.

Risolutore manuale di token

Usa un risolver manuale quando acquisisci token al di fuori della pipeline dell'Agent Framework, quando stai costruendo app non Agent Framework o quando usi l'autenticazione service-to-service (S2S). Il token che il tuo resolver restituisce deve corrispondere alla route. Per la rotta delegata, restituisci un token delegato con lo scope Agent365.Observability.OtelWrite. Per la route S2S, restituisci il token finale per la sola app che richiedi con lo scope api://9b975845-388f-4429-889e-eab1ef63949c/.default. Un agente blueprint registrato su S2S non ha bisogno del Agent365.Observability.OtelWrite ruolo o del consenso amministrativo.

Note

Per l'autenticazione tra servizi (S2S), è necessario utilizzare questo approccio manuale di risoluzione dei token. La cache dei token agentici supporta solo flussi di autenticazione on-behalf-of (OBO).

Gli esempi seguenti illustrano lo schema di risoluzione dei token OBO (on-behalf-of) — l'agente acquisisce un token utente tramite il gestore di autenticazione agentica e lo scambia con un token con ambito limitato all'osservabilità. Questi esempi richiedono il permesso delegato Agent365.Observability.OtelWrite e il consenso dell'amministratore. Per esempi di S2S (da servizio a servizio) e per un confronto tra l'autenticazione OBO e S2S, vedere Observability Authentication Setup for Agent SDK.

Il sistema di risoluzione deve essere sincrono. Acquisire il token nel gestore attività asincrona (o tramite MSAL) e memorizzarlo nella cache per il resolver.

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 dei token agentic con le app di Agent Framework

Per le app di Agent Framework che usano l'autenticazione OBO (on-behalf-of), la distribuzione registra automaticamente IExporterTokenCache<AgenticTokenStruct> tramite DI quando non imposti un TokenResolver personalizzato. Il tuo agente chiama RegisterObservability() in runtime per fornire credenziali, e la cache gestisce l'acquisizione e l'aggiornamento dei token delegati.

Note

Questo approccio supporta solo i flussi di autenticazione on-behalf-of (OBO) sulla rotta delegata, che richiede il permesso delegato Agent365.Observability.OtelWrite e il consenso dell'amministratore. Per l'autenticazione service-to-service (S2S), inclusi gli agenti del progetto configurati con a365 setup all, usa lo strumento di risoluzione manuale dei token con un token per la sola app. Per i passaggi di configurazione, consulta Agent 365-abilitato usando 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,
    )

Archiviare gli attributi di convalida

Per la convalida del negozio, l'agente deve implementare gli scopi InvokeAgentScope, InferenceScope e ExecuteToolScope. Ogni ambito corrisponde a un'operazione span nello schema canonico:

Ambito dell'SDK Operazione span Codice di riferimento universale
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Per gli elenchi completi di attributi obbligatori e facoltativi per ambito, tra cui la semantica per attributo, le linee guida per la selezione dei valori e gli attributi che possono essere sottoposti a query tramite Microsoft Defender ricerca avanzata, vedere Agent 365 observability attribute reference. La colonna Si applica a identifica l'ambito a cui appartiene ogni attributo e la colonna Obbligatorio distingue gli attributi obbligatori (M) dagli attributi facoltativi (O).

Testare l'agente utilizzando funzioni di monitoraggio e analisi

Dopo l'implementazione dell'osservabilità, verificare che i dati di telemetria vengano acquisiti:

  1. Andare alla pagina https://admin.cloud.microsoft/#/agents/all.
  2. Selezionare l'agente e quindi Selezionare Attività.
  3. Verificare che vengano visualizzate le sessioni e le chiamate agli strumenti.

Applicazioni di esempio e configurazione avanzata

Per esempi funzionanti e opzioni di configurazione avanzate, vedere i repository di GitHub per ogni lingua:

Informazioni di riferimento sulla programmazione

Per esaminare i tipi di Microsoft OpenTelemetry Distro, consulta i seguenti articoli di riferimento sulla programmazione:

Troubleshooting

Questa sezione descrive i problemi comuni durante l'implementazione e l'uso della distribuzione di OpenTelemetry Microsoft con Agent 365.

Problema Description
I dati di osservabilità non vengono visualizzati Non è visibile alcuna telemetria perché l'esportazione dell'Agent 365 non è abilitata, la configurazione non è completa o la risoluzione dei token fallisce.
ID tenant o ID agente mancanti: intervalli ignorati Gli span vengono esclusi prima dell'esportazione quando mancano gli attributi di identità richiesti del tenant o dell'agente.
Errore di risoluzione del token - esportazione saltata o non autorizzata L'esportazione viene saltata o rifiutata quando il risolutore di token non restituisce alcun token o si verificano errori durante l'ottenimento del token.
HTTP 401 Non autorizzato Le richieste raggiungono il servizio ma l'autenticazione ha esito negativo perché il token non è valido, è scaduto o per il gruppo di destinatari errato.
HTTP 403 Vietato L'autorizzazione fallisce a causa della mancanza di licenze del tenant, un'identità S2S non registrata o permessi di scrittura di osservabilità mancanti quando sono necessari.
HTTP 403 Accesso negato - ID agente non corrispondente Il servizio rifiuta l'esportazione quando l'ID agente nella richiesta non corrisponde all'identità dell'agente autorizzato dal token.
Errori HTTP 429 o 5xx - Errori temporanei Il throttling temporaneo o l'instabilità del backend interrompono l'esportazione e potrebbero richiedere ritentativi o messa a punto batch.
Timeout di esportazione Le operazioni di esportazione superano i limiti di timeout a causa di ritardi di rete o la latenza di risposta dell'endpoint.
L'esportazione ha esito positivo, ma i dati di telemetria non vengono visualizzati in Defender o Purview L'inserimento dei dati ha esito positivo, ma la visibilità viene ritardata o bloccata dai prerequisiti downstream e dai requisiti dello schema.

Tip

La Guida alla risoluzione dei problemi dell'Agente 365 contiene raccomandazioni di alto livello, best practice e link a contenuti di risoluzione dei problemi per ogni fase del ciclo di sviluppo dell'Agente 365.

I dati di osservabilità non compaiono

Sintomi:

  • L'agente è in corsa
  • Niente telemetria nel centro amministrativo
  • Non si vede l'attività degli agenti

Causa radice:

  • L'esportazione dell'agente 365 non è abilitata
  • Errori di configurazione
  • Problemi di risoluzione dei token

Soluzioni: Prova i seguenti passaggi per risolvere il problema:

  • Verificare che l'esportazione dell'agente 365 sia abilitata

    È necessario abilitare in modo esplicito l'utilità di esportazione di Agent 365. Quando non lo imposti, la distribuzione potrebbe eseguire il fallback a un esportatore di console o non esportare nulla. Abilitarlo nel codice:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    In alternativa, impostare la variabile di ambiente:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Note

    ENABLE_A365_OBSERVABILITY_EXPORTER è un interruttore secondario che diventa effettivo solo quando enable_a365=True viene impostato nel codice. È anche possibile controllarlo tramite il a365_enable_observability_exporter kwarg.

  • Controlla la configurazione del token resolver

    L'utilità di esportazione richiede un resolver di token valido che restituisce un token di connessione per ogni richiesta di esportazione. Se il resolver del token è mancante o restituisce null, l'esportazione viene ignorata automaticamente.

  • Abilitare l'esportazione della console e verificare la presenza di dati di telemetria in locale

    Aggiungi un esportatore della console per verificare che la telemetria sia generata prima che raggiunga l'endpoint di Agent 365.

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Abilitare la registrazione dettagliata

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Controllare la presenza di errori di esportazione nei log

    Usare il az webapp log tail comando per cercare i log per individuare gli errori correlati all'osservabilità:

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

ID tenant o ID agente mancanti: intervalli ignorati

Sintomi: Il sistema elimina silenziosamente i segmenti e non li esporta mai. Alcune piattaforme registrano un numero di intervalli ignorati o un messaggio No spans with tenant/agent identity found. Altri li scaricano senza registrazione.

Risoluzione:

  • Prima dell'esportazione, le partizioni di distribuzione vengono suddivise in base all'identità del tenant e dell'agente. Gli intervalli che mancano di un ID tenant o di un ID agente vengono eliminati e non inviati al servizio.
  • Assicurati che BaggageBuilder sia configurato con l'ID tenant e l'ID agente prima di creare intervalli. Questi valori vengono propagati attraverso il contesto OpenTelemetry e si collegano a tutti gli intervalli creati nell'ambito del baggage. Per l'API specifica della piattaforma, vedere Attributi del bagaglio.
  • Se si utilizza il middleware del baggage o l'helper del contesto di turno dal pacchetto di integrazione dell'hosting per popolare gli ID, verifica che l'attività TurnContext abbia un destinatario valido con identità agente.

Errore di risoluzione del token: esportazione ignorata o non autorizzata

Sintomi: Il resolver del token restituisce null o genera un errore. A seconda della piattaforma, l'esportazione viene ignorata completamente o ha esito negativo con HTTP 401.

Risoluzione:

  • Il sistema di risoluzione dei token è obbligatorio. Se è mancante, l'esportatore genera un errore all'avvio. Verificare che venga fornito un risolutore di token e che restituisca un token Bearer valido.
  • Assicurarsi che l'ID tenant e l'ID agente corretti vengano passati a BaggageBuilderperché questi valori vengono inoltrati al resolver del token.
  • Per S2S, restituire il token finale di osservabilità solo app per 9b975845-388f-4429-889e-eab1ef63949c o api://9b975845-388f-4429-889e-eab1ef63949c. Non restituire l'asserzione intermedia del blueprint, un token blueprint, o un token utente o OBO.
  • Per la rotta delegata, restituisci un token delegato con lo scope Agent365.Observability.OtelWrite.
  • Per gli agenti ospitati su Azure che esportano direttamente con un'identità gestita, verifica che l'identità gestita abbia il ruolo app Agent365.Observability.OtelWrite. Le istanze di blueprint agent registrate su S2S non ne hanno bisogno.
  • Per le app .NET che usano il pacchetto di hosting di Agent Framework, lo scambio di token viene gestito automaticamente tramite inserimento delle dipendenze. Se mancano token, verificare che Microsoft.Agents.A365.Observability.Hosting sia installato e registrato.

HTTP 401 Non autorizzato

Sintomi: L'esportazione non riesce con HTTP 401. L'esportatore non ritenta di risolvere questo errore.

Risoluzione:

  • Verifica che il pubblico del token sia 9b975845-388f-4429-889e-eab1ef63949c o api://9b975845-388f-4429-889e-eab1ef63949c, e che il tipo di token corrisponda alla route: un token delegato per la route delegata, o un token solo app per la route S2S.
  • Per S2S, verifica che il resolver non stia restituendo un token utente delegato, un'asserzione di blueprint intermedio, un token blueprint, un token per un pubblico errato o un token scaduto.
  • Per la rotta delegata, verifica che il claim del scp token contenga Agent365.Observability.OtelWrite e che il token non sia scaduto.

HTTP 403 Non consentito

Sintomi: L'esportazione non riesce con HTTP 403. L'esportatore non ritenta di risolvere questo errore.

Causa radice: Un errore HTTP 403 può avere cause diverse. Controllare le risoluzioni seguenti nell'ordine indicato.

Risoluzione:

  • Missing license: verificare che al tenant sia assegnata una delle licenze seguenti in interfaccia di amministrazione di Microsoft 365:

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

  • Identità non registrata su S2S — Un'istanza di agente blueprint registrato può esportare sulla rotta S2S con un token solo app che non ha alcun ruolo Agent365.Observability.OtelWrite. Se l'identità non è registrata presso Agent 365, il servizio restituisce HTTP 403 insufficient_scope. Per gli agenti blueprint, a365 setup all registra l'istanza dell'agente. Per riprovare una registrazione fallita, esegui a365 setup all --agent-registration-only. Creare da solo un'identità Microsoft Entra non registra l'istanza dell'agente.

  • Permesso mancante Agent365.Observability.OtelWrite dove necessario — Concedere il permesso per il percorso delegato o per identità non registrate, incluse le registrazioni standard dell'app. Gli agenti blueprint registrati su S2S non hanno bisogno di questo permesso.

Concedere l'autorizzazione

Concedi Agent365.Observability.OtelWrite solo quando usi la via delegata o un'identità non registrata. Gli agenti blueprint registrati che usano S2S non hanno bisogno di questo permesso o del consenso dell'amministratore. Concedi solo il tipo di permesso che il tuo percorso utilizza:

  • Rotta delegata: Aggiungi il permesso delegato.
  • Percorso S2S con un'identità non registrata, come la registrazione standard dell'app che un agente custom engine usa: Aggiungi il permesso dell'applicazione (ruolo nell'app).

Scegliere una di queste opzioni:

  • Agent 365 CLI (agenti blueprint nel percorso delegato)

    Questo comando aggiunge il permesso delegato al tuo progetto e i suoi permessi ereditabili, e poi concede il consenso dell'amministratore. Non aggiunge il permesso dell'applicazione. Richiede un account Amministratore Globale. Esegui il comando dalla directory del progetto agente che contiene a365.config.json, oppure aggiungi --agent-name "<agent-name>".

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

  • Interfaccia di amministrazione di Microsoft Entra (da entrambi i percorsi)

    Non sono necessari file di configurazione; richiede l'accesso Global Administrator alla registrazione dell'app. Per un blueprint nel percorso delegato, usa questa opzione solo se il blueprint ha già l'API di osservabilità nei suoi permessi ereditabili, come un blueprint configurato da una versione precedente della CLI. Altrimenti, usa la CLI di Agent 365.

    1. Vai all'interfaccia di amministrazione di Microsoft Entra, seleziona Registrazioni app e poi seleziona la registrazione dell'applicazione del progetto o standard.
    2. Vai a Autorizzazioni API>Aggiungi un'autorizzazione> cerca API utilizzate dalla mia organizzazione> per 9b975845-388f-4429-889e-eab1ef63949c.
    3. Seleziona Permessi delegati per la rotta delegata, oppure Autorizzazioni applicazione per un'identità non registrata sulla rotta S2S.
    4. Controlla Agent365.Observability.OtelWrite, quindi seleziona Aggiungi permessi.
    5. Seleziona Concedi il consenso dell'amministratore e conferma.

    Il permesso che hai aggiunto è nello stato Granted.

HTTP 403 Forbidden — l'ID dell'agente non corrisponde

Sintomi: l'esportazione non riesce con HTTP 403 e un messaggio del server simile a 403 Forbidden con errori agent-ID-mismatch durante la chiamata agli endpoint delle tracce di Agent 365.

Causa radice: Questo errore si verifica quando si usa l'ID client del progetto anziché l'ID client dell'istanza dell'agente quando si impostano i dettagli dell'agente. L'ID agente nell'URL di esportazione non corrisponde all'identità autorizzata dal token, quindi l'endpoint delle tracce rifiuta la richiesta.

Risoluzione:

  • Verificare se l'ID tenant viene aggiunto all'elenco di tenant consentiti di Agent 365.
  • Imposta i dettagli dell'agente con l'ID cliente dell'istanza dell'agente (non l'ID cliente del blueprint).
  • Verifica l'URL di esportazione generato: viene registrato nei log se si attiva il logger. Verifica che l'ID dell'agente nell'URL corrisponda all'ID client dell'istanza agente.
  • Per abilitare la registrazione diagnostica per SDK, vedere Convalida locale.

Errori HTTP 429 o 5xx - Errori temporanei

Sintomi: L'esportazione non riesce con un codice di stato HTTP temporaneo, ad esempio 429 o 5xx.

Risoluzione:

  • Questi errori sono in genere temporanei e risolti autonomamente. Le distribuzioni di Python e JavaScript riprovano automaticamente nei codici di stato HTTP 408, 429 e 5xx. La distribuzione .NET non riprova automaticamente.
  • Se gli errori continuano a verificarsi, controlla il dashboard dello stato del servizio.
  • Valutare la possibilità di ridurre la frequenza di esportazione aumentando il ritardo pianificato tra batch o le dimensioni massime del batch di esportazione. Per Python e JavaScript, usare i parametri exporterOptions o a365_* documentati nei repository GitHub. Per .NET, usare o.Agent365.Exporter.ScheduledDelayMilliseconds e o.Agent365.Exporter.MaxExportBatchSize.

Timeout di esportazione

Sintomi: Timeout dei tentativi di esportazione.

Risoluzione:

  • Controllare la connettività di rete all'endpoint di osservabilità.

  • Il timeout predefinito della richiesta HTTP è di 30 secondi in tutte le piattaforme. Se i timeout si verificano frequentemente, aumentare il valore di timeout nelle opzioni di esportazione:

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

    Vedere il repository Python per l'elenco completo delle opzioni a365_*.

L'esportazione ha esito positivo, ma i dati di telemetria non vengono visualizzati in Defender o Purview

Symptoms: I log mostrano un'esportazione riuscita (HTTP 200), ma i dati di telemetria non sono visibili in Microsoft Defender o Microsoft Purview.

Risoluzione:

  • Verificare di soddisfare i prerequisiti per la visualizzazione dei log esportati:
  • La compilazione dei dati di telemetria può richiedere alcuni minuti dopo un'esportazione riuscita. Attendere prima di approfondire l'analisi.
  • Verificare che gli intervalli contengano attributi microsoft.tenant.id e gen_ai.agent.id validi. Gli attributi identità mancanti causano l'eliminazione degli intervalli lato server anche se l'esportazione HTTP restituisce il codice 200.

Contenuti correlati

  • Ultimo aggiornamento: