Microsoft OpenTelemetry Distro

Distribuzione OpenTelemetry di Microsoft è una distribuzione unificata per l'osservabilità che offre un'esperienza unica di integrazione 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.

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

Impostazione

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.

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.

Propaga contesto

Per mantenere l'osservabilità tra le operazioni distribuite di Agent 365, è necessario 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 che copia tutte le informazioni di contesto non vuote in span appena avviate senza sovrascrivere 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, registrare il middleware del bagaglio per popolare automaticamente i bagagli 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 bagaglio per risposte asincrone (ContinueConversation eventi) per evitare di sovrascrivere il bagaglio già impostato dalla richiesta di origine.

Verificare che i dati fluiscano correttamente nel prodotto

Per visualizzare i dati di telemetria dell'agente in Microsoft Purview o Microsoft Defender, assicurarsi che siano soddisfatti i requisiti seguenti:

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 dell'agente manuali 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 Bagaglio agente 365 e ambiti Microsoft Agent 365.
Node.js HTTP, Azure SDK, Funzioni di Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan e Winston. OpenAI Agents SDK, LangChain, metadata Microsoft Agent 365 e scope 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, Bagaglio dati Microsoft Agent 365 e scopi 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.

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, impostare bagagli 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

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.

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

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 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 bagaglio attivo. La distribuzione supporta tre approcci.

Risolutore manuale di token

Usare un sistema di risoluzione manuale quando si acquisiscono token all'esterno della pipeline di Agent Framework o quando si creano app non di Agent Framework.

Il sistema di risoluzione deve essere sincrono. Acquisire il token nel gestore attività asincrona 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, la distribuzione esegue automaticamente la registrazione tramite l'inserimento delle dipendenze IExporterTokenCache<AgenticTokenStruct> quando non si imposta un oggetto personalizzato TokenResolver. L'agente chiama RegisterObservability() in fase di esecuzione per fornire le credenziali e la cache gestisce l'acquisizione e l'aggiornamento 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,
    )

Applicazioni di esempio e configurazione avanzata

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

Troubleshooting

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

Suggerimento

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 distro potrebbe eseguire il fallback a un exporter 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

  • Controlla la configurazione del token resolver

    L'utilità di esportazione richiede un resolver di token valido che restituisce un token Bearer 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

    Aggiungere un'utilità di esportazione della console per verificare che la telemetria sia generata prima che raggiunga l'endpoint dell'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 come No spans with tenant/agent identity found, ad esempio. 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 non dispongono di un ID tenant o di un ID agente vengono eliminati e non vengono mai inviati al servizio.
  • Assicurarsi 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 bagaglio. Per l'API specifica della piattaforma, vedere Attributi del bagaglio.
  • Se si usa il middleware del bagaglio o l'helper del contesto di turno dal pacchetto di integrazione dell'hosting, verificare che l'attività TurnContext abbia un destinatario valido con l'identità dell'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 manca, 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 gli agenti Azure ospitati, verificare che l'identità gestita disponga dell'autorizzazione API necessaria 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 injection 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:

  • Verificare che il gruppo di destinatari del token corrisponda all'ambito dell'endpoint di osservabilità.
  • Verificare che il resolver del token non restituisca un token utente delegato, un token per un gruppo di destinatari non corretto 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 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

  • Autorizzazione mancante Agent365.Observability.OtelWrite : è necessario concedere questa autorizzazione all'identità (identità gestita o registrazione dell'app). Senza di esso, l'esportazione dei dati di telemetria non riesce con HTTP 403.

    Concedere l'autorizzazione usando una delle opzioni seguenti.

    Opzione A — CLI di Agent 365 (richiede a365.config.json e a365.generated.config.json nella directory di configurazione, un account amministratore globale e Agent 365 CLI v1.1.139-preview o versione successiva)

    a365 setup admin --config-dir "<path-to-config-dir>"

    Opzione B - Entra Portal (nessun file di configurazione richiesto; richiede l'accesso amministratore globale alla registrazione dell'app del progetto)

    1. Passare a Entra portal>Registrazioni app>, quindi selezionare l'app Blueprint.
    2. Passare a Autorizzazioni API>Aggiungi un'autorizzazione>API utilizzate dalla mia organizzazione>9b975845-388f-4429-889e-eab1ef63949ccercare.
    3. Selezionare Autorizzazioni delegate> selezionare Agent365.Observability.OtelWrite>Aggiungi autorizzazioni.
    4. Ripetere i passaggi da 2 a 3, questa volta selezionare Autorizzazioni> applicazione selezionare Agent365.Observability.OtelWrite>Aggiungi autorizzazioni.
    5. Fare clic su Concedi consenso amministratore e confermare.

    Sia Agent365.Observability.OtelWrite (Delegato) che Agent365.Observability.OtelWrite (Applicazione) devono mostrare lo stato Granted.

HTTP 429/ 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.

Il 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 la perdita dei segmenti lato server anche se l'esportazione HTTP restituisce il codice 200.
  • Last updated on