Distribuzione Microsoft di OpenTelemetry

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 backend compatibile con OpenTelemetry Protocol (OTLP). La distribuzione supporta .NET, Node.js e Python e sostituisce la configurazione frammentata tra diversi stack di osservabilità con un'unica importazione e una sola chiamata di configurazione.

Vantaggi chiave

Microsoft OpenTelemetry Distro offre questi vantaggi:

  • Un pacchetto, una sola API: Sostituisce più pacchetti di esportazione e strumentazione con una singola dipendenza.
  • Supporto multi-backend: invia la telemetria simultaneamente a Monitoraggio di Azure, a qualsiasi endpoint compatibile con OpenTelemetry Protocol (OTLP) come Datadog, Grafana o New Relic, e a Microsoft Agent 365.
  • Strumentazione integrata: Usa strumentazione automatica per HTTP, database, Azure SDK, Funzioni di Azure e altro senza configurazione aggiuntiva.
  • Basato su standard: Sfrutta OpenTelemetry, il framework di osservabilità di riferimento per il settore.
  • Boilerplate minimo: Aggiungi un'importazione e una chiamata di funzione al punto di ingresso dell'applicazione.

Installazione e configurazione

Questa guida mostra come aggiungere osservabilità alla tua applicazione con Microsoft OpenTelemetry Distro. La distribuzione raccoglie automaticamente tracce, metriche e log con strumenti integrati ed esporta la telemetria in Monitoraggio di Azure, in qualsiasi endpoint OpenTelemetry Protocol (OTLP) o in Microsoft Agent 365.

Installare la raccolta

Per iniziare con Microsoft OpenTelemetry Distro, installa la raccolta appropriata per la tua piattaforma di sviluppo utilizzando il gestore di pacchetti del tuo linguaggio.

Prerequisiti: Python 3.10 o successivo.

pip install microsoft-opentelemetry

Configurazione

L'esportatore Agent 365 non usa una stringa di connessione. Individua automaticamente l'endpoint in base al tenant. Per abilitare l'esportazione verso Agent 365, imposta la destinazione dell'esportatore e fornisci un risolutore di token che restituisca un token di accesso per uno specifico ID agente e ID tenant.

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 personalizzata dei token (anziché il risolutore di token predefinito), vedi Risolutore di token manuale.

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

Parametro Descrizione Default
a365_use_s2s_endpoint Quando True, utilizza il percorso dell'endpoint tra servizi. False
a365_max_queue_size Dimensione massima della coda per il processore batch. 2048
a365_scheduled_delay_ms Ritardo in millisecondi tra i batch di esportazione. 5000
a365_exporter_timeout_ms Timeout in millisecondi per l'operazione di esportazione. 30000
a365_max_export_batch_size Dimensione massima del batch per le operazioni di esportazione. 512

Propagare il contesto

Per mantenere l'osservabilità nelle operazioni distribuite di Agent 365, propagare il contesto. Quando propaghi il contesto attraverso i tuoi agenti e servizi, ti assicuri che tracce, log e metriche siano correttamente correlati lungo tutto il ciclo di vita delle richieste. Questa correlazione è necessaria per un'esperienza di monitoraggio Microsoft Agent 365 completa ed efficace.

Attributi di baggage

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, usa 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 baggage

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 elimina la necessità di invocare BaggageBuilder manualmente in ogni gestore di attività.

In Python, registra il baggage middleware tramite ObservabilityHostingManager.configure() invece che 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.

Validare che i dati fluiscono nel prodotto

Per visualizzare la telemetria degli agenti in Microsoft Purview o Microsoft Defender, assicurati che siano soddisfatti i seguenti requisiti:

Strumentazione automatica

La distribuzione Microsoft OpenTelemetry combina pipeline OpenTelemetry standard con strumentazione curata da Microsoft. La Distro può raccogliere telemetria applicativa, telemetria infrastrutturale e telemetria degli agenti o di IA generativa 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 runtime di Azure ove supportato.
Strumentazione dell’infrastruttura HTTP, ASP.NET Core, Azure SDK, client di database e framework di logging ove supportato.
Strumentazione di IA generativa OpenAI, Azure OpenAI, Kernel semantico, LangChain, OpenAI Agents SDK e Agent Framework dove supportati.
Ambiti manuali dell'agente Invocazione dell'agente, esecuzione dello strumento, inferenza e telemetria dell'output ove supportato.
Esportatori 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

Lingua Strumentazione comune delle applicazioni Strumentazione comune per agente e IA generativa
Python Risorse, processori, lettori, log, metriche e tracce OpenTelemetry. 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 risorse, metriche e log. Kernel semantico, OpenAI e Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage e ambiti Microsoft Agent 365.

La strumentazione automatica ascolta i segnali di telemetria emessi da librerie e framework supportati. La strumentazione manuale viene utilizzata quando un'applicazione deve descrivere operazioni specifiche per agente, come invocazione, esecuzione dello strumento, inferenza o output asincrono.

Aggiungi sorgenti, contatori, processori o lettori personalizzati di OpenTelemetry quando la tua applicazione emette telemetria non coperta dalle strumentazioni integrate.

Importante

La strumentazione automatica popola solo gli attributi standard di OpenTelemetry. Non include tutti gli attributi richiesti da Agent 365. Devi aggiungere attributi specifici di Microsoft tramite BaggageBuilder. Per vedere quali attributi sono richiesti, consulta Archiviare gli attributi di convalida.

Librerie di strumentazione predefinite

L'auto-strumentazione ascolta la telemetria emessa dai framework supportati e la inoltra attraverso la pipeline OpenTelemetry della Distro. Per gli scenari dell'agente, imposta baggage come ID tenant e ID agente prima che il framework instrumentato crei intervalli.

Framework Python Node.js .NET
Kernel semantico Supportata Non supportato Supportato
OpenAI e OpenAI Agents SDK Supportata Supportato Supportata
Agent Framework Supportata Non supportato Supportato
LangChain Supportata Supportata Non elencato

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

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

Strumentazione manuale

Usa la strumentazione manuale quando la strumentazione automatica non descrive il funzionamento dell'agente con sufficiente dettaglio. Gli ambiti manuali consentono a un'applicazione di descrivere le attività comuni degli agenti in modo uniforme tra diversi linguaggi.

Ambito Usare per
InvokeAgentScope L'inizio e il completamento di un'invocazione di agente.
ExecuteToolScope Richiesta strumento effettuata da un agente.
InferenceScope Un'operazione di inferenza di modello di intelligenza artificiale.
OutputScope Output che deve essere registrato dopo il completamento dell'ambito di origine.

Riutilizza gli stessi valori di richiesta e identità dell'agente tra i diversi ambiti di una richiesta, così che la telemetria possa essere correlata.

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

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

Convalida locale

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

Convalidare con un endpoint OTLP locale

Configura la Distro per inviare la telemetria a un collettore 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()

Convalidare utilizzando l'output locale

Usa l'output locale quando vuoi verificare la strumentazione prima di inviare la 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.

Esamina l'output locale per gli span provenienti da fonti previste, come richieste HTTP, chiamate OpenAI o Azure OpenAI, scope di invocazione dell'agente, scope di esecuzione degli strumenti o scope di inferenza. La validazione specifica della destinazione si trova nella documentazione del prodotto corrispondente.

Configurare manualmente l'autenticazione

Quando si utilizza l'esportatore Agent 365, è necessario predisporre un meccanismo per l'acquisizione di 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.

Suggerimento

Se stai sviluppando agenti con l'SDK per agenti Microsoft 365, consulta Configurazione dell'autenticazione per l'osservabilità nell'Agent SDK per istruzioni passo-passo sulla configurazione dell'acquisizione di token OBO e S2S sia per agenti che per non agenti.

Strumento di risoluzione manuale di token

Usa uno strumento di risoluzione manuale quando acquisisci token al di fuori del pipeline di Agent Framework, quando sviluppi applicazioni non basate su Agent Framework o quando utilizzi l'autenticazione service-to-service (S2S) (flusso delle credenziali client). Gli agenti possono generare un token autonomamente, ad esempio utilizzando la Libreria di Autenticazione Microsoft (MSAL) o qualsiasi altro metodo di acquisizione di token, ma devono assicurarsi che il token abbia il corretto ambito di osservabilità (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Nota

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

I seguenti esempi mostrano il pattern di risolutore di token OBO (on-behalf-of): l'agente acquisisce un token utente tramite il gestore di autenticazione dell'agente e lo scambia con un token con scopo di osservabilità. Per esempi S2S (service-to-service) e un confronto tra autenticazione OBO e S2S, vedi Configurazione autenticazione osservabilità per l'SDK per gli agenti.

Lo strumento di risoluzione deve essere sincrono. Acquisisci il token nel tuo handler di attività asincrona (o tramite MSAL) e memorizzalo in cache per lo strumento di risoluzione.

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 di token agentici con app 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. L'agente richiama RegisterObservability() durante l'esecuzione per fornire le credenziali, e la cache gestisce l'acquisizione e l'aggiornamento dei token.

Nota

Questo approccio supporta solo i flussi di autenticazione on-behalf-of (OBO). Per l'autenticazione service-to-service (S2S), usa invece lo strumento di risoluzione manuale dei token.

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 di span nello schema canonico:

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

Per l'elenco completo degli attributi obbligatori e opzionali per ciascun ambito – inclusa la semantica di ciascun attributo, le indicazioni sulla scelta dei valori e quali attributi sono interrogabili tramite la ricerca avanzata di Microsoft Defender – vedi Agent 365 observability attribute reference. La colonna Si applica a identifica l’ambito di appartenenza di ciascun attributo, mentre la colonna Obbligatorio distingue gli attributi obbligatori (M) da quelli opzionali (O).

Testare l'agente con l'osservabilità

Dopo aver implementato l'osservabilità, verifica che la telemetria venga catturata:

  1. Andare a https://admin.cloud.microsoft/#/agents/all.
  2. Seleziona l'agente e fai clic su Attività.
  3. Verifica che compaiano sessioni e chiamate di strumenti.

Applicazioni di esempio e configurazione avanzata

Per esempi funzionanti e opzioni di configurazione avanzate, consulta i repository GitHub per ciascun linguaggio:

Risoluzione dei problemi

Questa sezione descrive i problemi comuni durante l'implementazione e l'utilizzo della Microsoft OpenTelemetry Distro con Agent 365.

Problema Descrizione
I dati di osservabilità non sono visibili Non è visibile alcuna telemetria perché l'esportazione tramite Agent 365 non è abilitata, la configurazione è incompleta oppure la risoluzione del token non va a buon fine.
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.
Risoluzione del token non riuscita - esportazione ignorata o non autorizzata L'esportazione viene ignorata o rifiutata quando lo strumento di risoluzione dei token non restituisce alcun token o si verificano errori durante l'acquisizione del token.
HTTP 401 Non autorizzato Le richieste raggiungono il servizio, ma l'autenticazione non va a buon fine perché il token è non valido, scaduto o associato a un destinatario errato.
HTTP 403 Negato L'autorizzazione non riesce a causa di licenze del tenant mancanti o di autorizzazioni di scrittura di osservabilità mancanti.
HTTP 403 Negato - Mancata corrispondenza dell'ID agente Il servizio rifiuta l'esportazione quando l'ID dell'agente nella richiesta non corrisponde all'identità dell'agente autorizzata dal token.
Errori HTTP 429 o 5xx - Errori transitori La limitazione temporanea della velocità o l'instabilità del back-end interrompono l'esportazione e possono richiedere nuovi tentativi o la regolazione dei batch.
Timeout di esportazione Le operazioni di esportazione superano i limiti di timeout a causa di ritardi di rete o della latenza di risposta degli endpoint.
L'esportazione ha successo ma la telemetria non appare né in Defender né in Purview L'inserimento dati va a buon fine, ma la visibilità è ritardata o bloccata da prerequisiti a valle e requisiti di schema.

Suggerimento

Guida alla risoluzione dei problemi di Agent 365 contiene raccomandazioni di alto livello per la risoluzione dei problemi, procedure consigliate e collegamenti a contenuti di risoluzione dei problemi per ogni fase del ciclo di vita dello sviluppo di Agent 365.

I dati di osservabilità non sono visibili

Sintomi:

  • L'agente è in esecuzione
  • Telemetria assente nell’interfaccia di amministrazione
  • Non è visibile l’attività dell’agente

Causa radice:

  • L'esportazione dell'Agent 365 non è abilitata
  • Errori di configurazione
  • Problemi con lo strumento di risoluzione dei token

Soluzioni: Prova i seguenti passaggi per risolvere il problema:

  • Verifica che l'esportazione Agent 365 sia abilitata

    Devi abilitare esplicitamente l'esportatore Agent 365. Quando non lo imposti, la distribuzione potrebbe eseguire il fallback a un esportatore di console o non esportare nulla. Abilita 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,
)

    Oppure imposta la variabile di ambiente:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Nota

    ENABLE_A365_OBSERVABILITY_EXPORTER è un'opzione secondaria che ha effetto solo quando enable_a365=True è impostato nel codice. Puoi anche controllarla tramite il kwarg a365_enable_observability_exporter.

  • Controlla la configurazione dello strumento di risoluzione dei token

    L'utilità di esportazione richiede un resolver di token valido che restituisce un token di connessione per ogni richiesta di esportazione. Se lo strumento di risoluzione dei token è assente o restituisce null, l'esportazione viene ignorata senza notifiche.

  • Abilita l'esportazione su console e verifica la telemetria localmente

    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)

  • Abilita registrazione dettagliata

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Controlla i log per errori di esportazione

    Usa il comando az webapp log tail per cercare nei log errori di 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 scarta silenziosamente gli span 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 scartano senza registrarli nei log.

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, vedi Attributi Baggage.
  • Se si utilizza il baggage middleware o il turn context helper 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 omessa o non autorizzata

Sintomi: Lo strumento di risoluzione dei token restituisce null o solleva un errore. A seconda della piattaforma, l'esportazione viene omessa completamente o fallisce con HTTP 401.

Risoluzione:

  • Lo strumento di risoluzione dei token è obbligatorio. Se è mancante, l'esportatore genera un errore all'avvio. Verifica che sia fornito uno strumento di risoluzione dei token e che restituisca un Bearer token valido.
  • Assicurati che l'ID tenant corretto e l'ID dell'agente siano passati a BaggageBuilder, perché questi valori vengono inoltrati allo strumento di risoluzione dei token.
  • Per gli agenti ospitati su Azure, verifica che l'Identità Gestita disponga delle autorizzazioni API richieste per l'ambito di osservabilità.
  • 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 i token, verifica 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 partecipante del token corrisponda all'ambito dell'endpoint di osservabilità.
  • Verifica che lo strumento di risoluzione dei token non restituisca un token utente delegato, un token per un partecipante errato o un token scaduto.

HTTP 403 Non consentito

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

Causa principale: Un errore HTTP 403 può avere diverse cause. Controlla le seguenti soluzioni nell'ordine indicato.

Risoluzione:

  • Licenza mancante: Verifica che il tuo tenant abbia una delle seguenti licenze assegnate nell'interfaccia di amministrazione di Microsoft 365:

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

  • Autorizzazione Agent365.Observability.OtelWrite mancante: Concedi l'autorizzazione all'identità (identità gestita o registrazione dell'app). Senza di essa, l'esportazione della telemetria fallisce con errore HTTP 403.

Concedere l'autorizzazione

Utilizza una delle seguenti opzioni:

  • Interfaccia della riga di comando di Agent 365

    Richiede un account di amministratore globale; esegui dalla directory del progetto dell'agente contenente a365.config.json o usa --agent-name.

    a365 setup permissions bot

    Oppure, senza un file di configurazione:

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

  • Portale di Entra

    Nessun file di configurazione necessario; è richiesto l'accesso come Amministratore Globale alla registrazione dell'app Blueprint.

    1. Vai al portale di Entra>Registrazioni app> seleziona l'app Blueprint.
    2. Vai a Autorizzazioni API>Aggiungi un'autorizzazione> cerca API utilizzate dalla mia organizzazione> per 9b975845-388f-4429-889e-eab1ef63949c.
    3. Seleziona Autorizzazioni delegate> e Agent365.Observability.OtelWrite>Aggiungi autorizzazioni.
    4. Ripeti i passaggi 2–3, questa volta seleziona Autorizzazioni dell'applicazione> controlla Agent365.Observability.OtelWrite>Aggiungi autorizzazione.
    5. Clicca su Concedi il consenso dell'amministratore e conferma.

    Sia Agent365.Observability.OtelWrite (Delegata) che Agent365.Observability.OtelWrite (Applicazione) mostrano lo stato Granted.

HTTP 403 Negato - Mancata corrispondenza dell'ID agente

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 principale: Questo errore si verifica quando utilizzi l'ID client del progetto invece dell'ID client dell'istanza dell'agente durante la configurazione dei dettagli dell'agente. L'ID dell'agente nell'URL di esportazione non corrisponde all'identità autorizzata dal token, quindi l'endpoint delle tracce rifiuta la richiesta.

Risoluzione:

  • Verifica se l'ID tenant viene aggiunto all'elenco dei tenant consentiti di Agent 365.
  • Configura i dettagli dell'agente con l'ID client dell'istanza dell'agente (non con l'ID client del progetto).
  • Verifica l'URL di esportazione che viene generato - viene registrato se abiliti il logger. Conferma che l'ID dell'agente nell'URL corrisponda all'ID client dell'istanza dell'agente.
  • Per abilitare la registrazione diagnostica per ciascun SDK, consulta Validazione locale.

Errori HTTP 429 o 5xx - Errori transitori

Sintomi: L'esportazione fallisce con un codice di stato HTTP temporaneo come 429 o 5xx.

Risoluzione:

  • Questi errori sono solitamente transitori e si risolvono da soli. Le distribuzioni Python e JavaScript eseguono automaticamente nuovi tentativi sui codici di stato HTTP 408, 429 e 5xx. La distribuzione .NET non esegue automaticamente nuovi tentativi.
  • Se persistono errori, controlla il pannello di stato del servizio.
  • Considera la possibilità di ridurre la frequenza di esportazione aumentando l'intervallo programmato tra i batch o la dimensione massima del batch di esportazione. Per Python e JavaScript, utilizza i parametri rilevanti exporterOptions o a365_* documentati nei repository GitHub. Per .NET, usa o.Agent365.Exporter.ScheduledDelayMilliseconds e o.Agent365.Exporter.MaxExportBatchSize.

Timeout di esportazione

Sintomi: Timeout dei tentativi di esportazione.

Risoluzione:

  • Verifica la connettività di rete verso l'endpoint di osservabilità.

  • Il timeout predefinito per le richieste HTTP è di 30 secondi su tutte le piattaforme. Se i timeout si verificano frequentemente, aumenta il valore del 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
)

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

L'esportazione ha successo ma la telemetria non appare né in Defender né in Purview

Sintomi: I log mostrano un'esportazione riuscita (HTTP 200) ma la telemetria non è visibile in Microsoft Defender o Microsoft Purview.

Risoluzione:

  • Verifica di soddisfare i prerequisiti per visualizzare i log esportati:
  • La telemetria può richiedere diversi minuti per essere popolata dopo un'esportazione riuscita. Attendi prima di indagare ulteriormente.
  • Verifica che gli span contengano attributi validi microsoft.tenant.id e gen_ai.agent.id. Gli attributi identità mancanti causano l'eliminazione degli intervalli lato server anche se l'esportazione HTTP restituisce il codice 200.

Contenuto correlato

  • Last updated on