Microsoft OpenTelemetry Distro

O Microsoft OpenTelemetry Distro é uma distribuição unificada de observabilidade que proporciona uma experiência de integração única para a recolha de rastreios, métricas e registos de aplicações com ou sem agente. Suporta a observabilidade para o Microsoft Agent 365, o Microsoft Foundry, o Azure Monitor e qualquer back-end compatível com o OpenTelemetry Protocol (OTLP). O distro suporta .NET, Node.js e Python, e substitui a configuração fragmentada em múltiplas pilhas de observabilidade por uma única importação e uma única chamada de configuração.

Principais benefícios

O Microsoft OpenTelemetry Distro fornece os seguintes benefícios:

  • Um pacote, uma API: substitui múltiplos pacotes de exportação e instrumentação por uma única dependência.
  • Suporte multi-back-end: envie telemetria para o Azure Monitor, qualquer ponto final compatível com o Protocolo OpenTelemetry (OTLP), como Datadog, Grafana ou New Relic, e para o Microsoft Agent 365 ao mesmo tempo.
  • Instrumentações incorporadas: utilize instrumentação automática para HTTP, bases de dados, SDK do Azure, Funções do Azure e muito mais, sem configuração adicional.
  • Baseado em padrões: criado com base no OpenTelemetry, a arquitetura de observabilidade padrão da indústria.
  • Configuração mínima: basta adicionar uma importação e uma chamada de função ao ponto de entrada da sua aplicação.

Instalação e configuração

Este guia explica como adicionar observabilidade à sua aplicação com o Microsoft OpenTelemetry Distro. O Distro recolhe automaticamente rastreios, métricas e registos com instrumentação integrada e exporta a telemetria para o Azure Monitor, qualquer ponto final compatível com o OpenTelemetry Protocol (OTLP) ou para o Microsoft Agent 365.

Instalar biblioteca

Para começar com o Microsoft OpenTelemetry Distro, instale a biblioteca apropriada para a sua plataforma de desenvolvimento utilizando o gestor de pacotes da sua linguagem.

Pré-requisitos: Python 3.10 ou posterior.

pip install microsoft-opentelemetry

Configuração

O exportador do Agent 365 não utiliza uma cadeia de ligação. Descobre automaticamente o seu ponto final com base no inquilino. Para ativar a exportação para o Agent 365, defina o alvo do exportador e forneça um resolver de tokens que devolva um token de acesso para um determinado ID de agente e ID de inquilino.

Chame use_microsoft_opentelemetry() para ativar a observabilidade.

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

Para a resolução personalizada de tokens (em vez do resolver de tokens predefinido), consulte Resolver de tokens manual.

Pode personalizar o comportamento do exportador passando kwargs opcionais do a365_* para use_microsoft_opentelemetry().

Parâmetro Description Predefinição
a365_use_s2s_endpoint Quando True, utilize o caminho do ponto final de serviço a serviço. False
a365_max_queue_size Tamanho máximo da fila para o processador em lote. 2048
a365_scheduled_delay_ms Atraso em milissegundos entre lotes de exportação. 5000
a365_exporter_timeout_ms Tempo limite em milissegundos para a operação de exportação. 30000
a365_max_export_batch_size Tamanho máximo do lote para operações de exportação. 512

Propagar contexto

Para manter a observabilidade nas operações distribuídas do Agent 365, propague o contexto. Quando propaga o contexto pelos seus agentes e serviços, garante que os rastreios, registos e métricas estão devidamente correlacionados ao longo de todo o ciclo de vida do pedido. Esta correlação é necessária para uma experiência de monitorização completa e eficaz do Microsoft Agent 365.

Atributos do baggage

Utilize BaggageBuilder para definir informações contextuais que fluem por todos os intervalos de um pedido. O SDK implementa um SpanProcessor que copia todas as entradas do baggage não vazias para spans recém-iniciados sem substituir os atributos existentes.

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

Para preencher automaticamente o BaggageBuilder a partir do TurnContext, utilize o programa auxiliar populate do pacote microsoft-opentelemetry. Este programa auxiliar extrai automaticamente detalhes do chamador, agente, inquilino, canal e conversa da atividade.

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 de baggage

Se o seu agente utilizar o pacote de integração de alojamento, registe o middleware do baggage para preencher automaticamente o baggage em cada pedido recebido. Este passo elimina a necessidade de chamar BaggageBuilder manualmente em cada processador de atividades.

Em Python, registe o middleware do baggage através de ObservabilityHostingManager.configure(), em vez de diretamente no adaptador.

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

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

O middleware ignora a configuração do baggage para respostas assíncronas (eventos ContinueConversation) para evitar substituir o baggage que o pedido original já definiu.

Validar se os dados estão a fluir para o produto

Para ver a telemetria do agente no Microsoft Purview ou Microsoft Defender, certifique-se de que os seguintes requisitos são satisfeitos:

  • Microsoft Purview: a auditoria deve estar ativada para a sua organização. Para obter instruções, consulte Ativar ou desativar a auditoria.
  • Microsoft Defender: a procura avançada deve ser configurada para aceder à tabela CloudAppEvents. Para mais informações, consulte a tabela CloudAppEvents no esquema de procura avançada.

Instrumentação automática

O Microsoft OpenTelemetry Distro combina pipelines OpenTelemetry padrão com instrumentação curada pela Microsoft. O Distro pode recolher telemetria de aplicações, telemetria de infraestrutura e telemetria de agentes ou IA generativa, consoante a linguagem e a configuração.

Categoria O que cobre
Pipelines de sinais Rastreios, métricas e registos.
Deteção de recursos Contexto de serviço, anfitrião, cloud e runtime do Azure, quando suportado.
Instrumentação de infraestrutura HTTP, ASP.NET Core, SDK do Azure, clientes de bases de dados e arquiteturas de registo, quando suportados.
Instrumentação de IA generativa OpenAI, Azure OpenAI, Kernel Semântico, LangChain, SDK de Agentes do OpenAI e Agent Framework quando suportados.
Âmbitos manuais de agentes Invocação de agentes, execução de ferramentas, inferência e telemetria de saída quando suportados.
Exportadores e processadores Azure Monitor, Microsoft Agent 365, OTLP, saída de consola, processadores de spans, processadores de registos e leitores de métricas.

Cobertura de instrumentação

Idioma Instrumentação comum de aplicações Instrumentação comum de agentes e de IA generativa
Python Recursos, processadores, leitores, registos, métricas e rastreios do OpenTelemetry. Kernel Semântico, SDK de Agentes do OpenAI, Agent Framework, LangChain, baggage do Microsoft Agent 365 e âmbitos do Microsoft Agent 365.
Node.js HTTP, SDK do Azure, Funções do Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan e Winston. SDK de Agentes do OpenAI, LangChain, baggage do Microsoft Agent 365 e âmbitos do Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, SDK do Azure, deteção de recursos, métricas e registos. Kernel Semântico, OpenAI e Azure OpenAI, Agent Framework, baggage do Microsoft Agent 365 e âmbitos do Microsoft Agent 365.

A instrumentação automática monitoriza os sinais de telemetria emitidos pelas bibliotecas e arquiteturas suportadas. A instrumentação manual é utilizada quando uma aplicação precisa de descrever operações específicas do agente, como a invocação, a execução de ferramentas, a inferência ou a saída assíncrona.

Adicione origens do OpenTelemetry personalizadas, medidores, processadores ou leitores quando a sua aplicação emitir telemetria que não está coberta pelas instrumentações incorporadas.

Importante

A instrumentação automática preenche apenas os atributos padrão do OpenTelemetry. Não inclui todos os atributos que o Agent 365 requer. Deve adicionar atributos específicos da Microsoft através de BaggageBuilder. Para ver quais são os atributos necessários, consulte Armazenar atributos de validação.

Bibliotecas de instrumentação incorporadas

A instrumentação automática deteta a telemetria emitida pelas arquiteturas suportadas e encaminha-a através do pipeline do OpenTelemetry do Distro. Para obter cenários de agente, defina o baggage como o ID do inquilino e o ID do agente antes de a arquitetura instrumentada criar os spans.

Estrutura Python Node.js .NET
Kernel Semântico Suportado Não suportado Suportado
OpenAI e SDK de Agentes do OpenAI Suportado Suportado Suportado
Agent Framework Suportado Não suportado Suportado
LangChain Suportado Suportado Não está presente na lista

Kernel Semântico

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

Instrumentação manual

Utilize a instrumentação manual quando a instrumentação automática não descrever a operação do agente com detalhes suficientes. Os âmbitos manuais permitem que uma aplicação descreva as atividades comuns do agente de forma consistente entre linguagens.

Âmbito Utilizar para
InvokeAgentScope O início e a conclusão de uma invocação de agente.
ExecuteToolScope Uma chamada de ferramenta efetuada por um agente.
InferenceScope Uma operação de inferência de modelo de IA.
OutputScope Saída que deve ser registada após o âmbito de origem já ter sido concluído.

Reutilize os mesmos valores de identidade de pedido e agente entre os âmbitos de um pedido para que a telemetria relacionada possa ser correlacionada.

Invocação do 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."])

Execução da ferramenta

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)

Inferência

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

Saída

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

A documentação do produto deve definir quaisquer requisitos específicos de validação do produto para esses âmbitos.

Validação local

A validação local confirma que a aplicação produz telemetria antes da validação de um destino específico do produto. Utilize a saída da consola ou um ponto final OTLP local para verificar se os rastreios, as métricas e os registos são criados.

Validar com um ponto final OTLP local

Configure o Distro para enviar telemetria para um coletor local ou para outro ponto final compatível com OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Validar com saída local

Utilize a saída local quando quiser confirmar a instrumentação antes de enviar a telemetria para um destino remoto.

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.

Reveja a saída local para spans provenientes de origens esperadas, como pedidos HTTP, chamadas OpenAI ou Azure OpenAI, âmbitos de invocação de agentes, âmbitos de execução de ferramentas ou âmbitos de inferência. A validação específica do destino pertence à documentação do produto desse destino.

Configurar a autenticação manualmente

Ao utilizar o exportador do Agent 365, é necessário implementar um mecanismo para fornecer um token de autenticação. O resolver de tokens opera por lote de exportação, utilizando o ID do agente e o ID do inquilino do contexto do baggage ativo. O distro suporta duas abordagens.

Sugestão

Se estiver a criar agentes com o SDK de Agentes do Microsoft 365, consulte Configuração de Autenticação de Observabilidade para Agent SDK para obter instruções passo a passo sobre como configurar a aquisição de tokens OBO e S2S para agentes por meio de agentes e não por meio de agentes.

Resolução manual de tokens

Utilize uma resolução manual de tokens quando adquirir tokens fora do pipeline do Agent Framework, ao desenvolver aplicações que não usam o Agent Framework ou ao utilizar a autenticação serviço a serviço (S2S) (fluxo de credenciais de cliente). Os agentes podem gerar um token por si próprios, por exemplo, utilizando o Biblioteca de Autenticação da Microsoft (MSAL) ou qualquer outro método de aquisição de tokens, mas precisam garantir que o token tenha o âmbito de observabilidade correto (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Nota

Para a autenticação serviço a serviço (S2S), deve utilizar esta abordagem de resolução manual de tokens. A cache de tokens por meio de agentes apenas suporta fluxos de autenticação on-behalf-of (OBO).

Os exemplos seguintes mostram o padrão do resolver de tokens OBO (on-behalf-of) — o agente obtém um token de utilizador através do processador de autenticação por meio de agentes e troca-o por um token com âmbito de observabilidade. Para exemplos de S2S (serviço a serviço) e uma comparação entre autenticação OBO e S2S, consulte Configuração de Autenticação de Observabilidade para o Agent SDK.

O resolver tem de ser síncrono. Obtenha o token no seu processador de atividades assíncronas (ou via MSAL) e coloque-o em cache para o 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 de tokens por meio de agentes com aplicações do Agent Framework

Para as aplicações do Agent Framework que utilizam autenticação on-behalf-of (OBO), o distro regista automaticamente o IExporterTokenCache<AgenticTokenStruct> via DI, caso não seja definido um TokenResolver personalizado. O seu agente chama RegisterObservability() em runtime para fornecer credenciais, e a cache processa a aquisição e a atualização dos tokens.

Nota

Esta abordagem suporta apenas fluxos de autenticação on-behalf-of (OBO). Para a autenticação serviço a serviço (S2S), utilize a resolução manual de tokens.

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

Armazenar os atributos de validação

Para que a validação do armazenamento seja bem-sucedida, o seu agente deve implementar InvokeAgentScope, InferenceScope e ExecuteToolScope. Cada âmbito corresponde a uma operação de span no esquema canónico:

Âmbito do SDK Operação de span Código de referência universal
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Para obter as listas completas de atributos obrigatórios e opcionais por âmbito – incluindo a semântica de cada atributo, orientações para escolha de valores e quais atributos podem ser consultados através da procura avançada do Microsoft Defender – consulte referência de atributos de observabilidade do Agent 365. A coluna Aplica-se a identifica a que âmbito pertence cada atributo, e a coluna Obrigatório distingue os atributos obrigatórios (M) dos opcionais (O).

Testar o seu agente com observabilidade

Após implementar a observabilidade, verifique se a telemetria está a ser capturada:

  1. Vá para https://admin.cloud.microsoft/#/agents/all.
  2. Selecione o seu agente e, em seguida, selecione Atividade.
  3. Verifique se as sessões e as chamadas de ferramenta aparecem.

Aplicações de exemplo e configuração avançada

Para obter exemplos funcionais e opções de configuração avançada, consulte os repositórios do GitHub para cada linguagem:

Resolução de Problemas

Esta secção descreve problemas comuns ao implementar e utilizar o Microsoft OpenTelemetry Distro com o Agent 365.

Problema Descrição
Os dados de observabilidade não aparecem Não há telemetria visível porque a exportação do Agent 365 não está ativada, a configuração está incompleta ou a resolução do token falha.
ID do inquilino ou ID do agente em falta – spans ignorados Os spans são filtrados antes da exportação quando os atributos necessários de identidade de inquilino ou agente estão ausentes.
Falha na resolução do token - exportação ignorada ou não autorizada A exportação é ignorada ou rejeitada quando o resolver de tokens não devolve nenhum token ou quando ocorrem erros durante a aquisição do token.
HTTP 401 Não autorizado Os pedidos chegam ao serviço, mas a autenticação falha porque o token é inválido, está expirado ou destinado à audiência incorreta.
HTTP 403 Proibido A autorização falha devido à falta de licenciamento do inquilino ou à falta de permissões de escrita de observabilidade.
HTTP 403 Proibido - O ID do agente não corresponde O serviço rejeita a exportação quando o ID do agente no pedido não corresponde à identidade do agente autorizada pelo token.
Erros HTTP 429 ou 5xx - Erros transitórios A limitação temporária ou a instabilidade do back-end interrompe a exportação e pode exigir novas tentativas ou ajuste em lote.
Tempo limite de exportação As operações de exportação excedem os limites de tempo limite devido a atrasos na rede ou latência de resposta do ponto final.
A exportação é bem-sucedida, mas a telemetria não aparece no Defender ou no Purview A ingestão de dados é bem-sucedida, mas a visibilidade é atrasada ou bloqueada por pré-requisitos a jusante e requisitos de esquema.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

Os dados de observabilidade não aparecem

Sintomas:

  • O agente está em execução
  • Sem telemetria no centro de administração
  • Não é possível ver a atividade do agente

Causa raiz:

  • A exportação do Agent 365 não está ativada
  • Erros de configuração
  • Problemas com o resolver de tokens

Soluções: tente os seguintes passos para resolver o problema:

  • Verificar se a exportação do Agent 365 está ativada

    Deve ativar explicitamente o exportador do Agent 365. Se não for definido, o distro pode recorrer a um exportador de consola ou não exportar nada. Ative-o no código:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

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

    Ou defina a variável de ambiente:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Nota

    ENABLE_A365_OBSERVABILITY_EXPORTER é um comutador secundário que só tem efeito quando enable_a365=True está definido no código. Também pode controlá-lo através do kwarg a365_enable_observability_exporter.

  • Verificar a configuração do resolver de tokens

    O exportador requer um resolver de tokens válido que devolva um token de Portador para cada pedido de exportação. Se o resolver de tokens estiver em falta ou devolver null, a exportação é ignorada silenciosamente.

  • Ativar a exportação da consola e verificar a telemetria localmente

    Adicione um exportador da consola para verificar se a telemetria está a ser gerada antes de chegar ao ponto final do Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Ativar registo verboso

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Verificar os registos para erros de exportação

    Utilize o comando az webapp log tail para pesquisar registos em busca de erros relacionados com observabilidade:

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

ID do inquilino ou do agente em falta — spans ignorados

Sintomas: o sistema descarta os spans silenciosamente e nunca os exporta. Algumas plataformas registam uma contagem de spans ignorados ou uma mensagem como No spans with tenant/agent identity found. Outros descartam-nos sem registo.

Resolução:

  • Antes da exportação, a distribuição particiona os spans por identidade do inquilino e do agente. Os spans que não possuem um ID do inquilino ou um ID do agente são descartados e nunca enviados para o serviço.
  • Garanta que BaggageBuilder está configurado com o ID do inquilino e o ID do agente antes de criar spans. Estes valores propagam-se através do contexto OpenTelemetry e ligam-se a todos os spans criados dentro do âmbito do baggage. Para a API específica da plataforma, consulte atributos do baggage.
  • Se estiver a utilizar o middleware do baggage ou o programa auxiliar de contexto do pacote de integração de alojamento, confirme se a atividade TurnContext tem um destinatário válido com a identidade do agente.

Falha na resolução do token — exportação ignorada ou não autorizada

Sintomas: o resolver de tokens devolve null ou lança um erro. Dependendo da plataforma, a exportação é ignorada ou falha com HTTP 401.

Resolução:

  • O resolver de tokens é necessário. Se estiver em falta, o exportador lança um erro no arranque. Verifique se um resolver de tokens é fornecido e devolve um token de Portador válido.
  • Certifique-se de que o ID do inquilino e o ID do agente corretos são passados para BaggageBuilder, porque estes valores são encaminhados para o resolver de tokens.
  • Para os agentes alojados no Azure, verifique se a Identidade Gerida tem a permissão necessária da API para o âmbito de observabilidade.
  • Para as aplicações .NET que utilizam o pacote de alojamento do Agent Framework, a troca de tokens é gerida automaticamente via DI. Se faltarem tokens, confirme que Microsoft.Agents.A365.Observability.Hosting está instalado e registado.

HTTP 401 Não autorizado

Sintomas: a exportação falha com HTTP 401. O exportador não volta a tentar este erro.

Resolução:

  • Verifique se a audiência do token corresponde ao âmbito do ponto final de observabilidade.
  • Verifique se o resolver de tokens não está a devolver um token de utilizador delegado, um token para uma audiência incorreta ou um token expirado.

HTTP 403 Proibido

Sintomas: a exportação falha com HTTP 403. O exportador não volta a tentar este erro.

Causa principal: um erro HTTP 403 pode ter diferentes causas. Verifique as seguintes resoluções pela ordem apresentada.

Resolução:

  • Licença em falta — Certifique-se de que o seu inquilino tem uma das seguintes licenças atribuídas no Centro de administração do Microsoft 365:

    • Testar - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Permissão Agent365.Observability.OtelWrite em falta — Conceda a permissão à sua identidade (Identidade Gerida ou registo da aplicação). Sem esta permissão, a exportação de telemetria falha com o erro HTTP 403.

Conceder a permissão

Utilize uma destas opções:

  • CLI do Agent 365

    Requer uma conta de Administrador Global; execute a partir do diretório do projeto do agente com a365.config.json ou utilize --agent-name.

    a365 setup permissions bot

    Ou, sem um ficheiro de configuração:

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

  • Portal do Entra

    Não são necessários ficheiros de configuração; requer acesso de Administrador Global ao registo da aplicação do esquema.

    1. Vá para o portal do Entra>Registos de aplicações>, selecione a sua aplicação de Esquema.
    2. Vá para Permissões da API>Adicionar uma permissão>APIs que a minha organização utiliza>, procure 9b975845-388f-4429-889e-eab1ef63949c.
    3. Selecione Permissões delegadas,>, verifique Agent365.Observability.OtelWrite>Adicionar permissões.
    4. Repita os passos 2–3, desta vez selecione Permissões de aplicação>, verifique Agent365.Observability.OtelWrite>Adicionar permissões.
    5. Clique em Conceder consentimento do administrador e confirme.

    Tanto Agent365.Observability.OtelWrite (Delegado) como Agent365.Observability.OtelWrite (Aplicação) apresentam o estado Granted.

HTTP 403 Proibido — O ID do agente não corresponde

Sintomas: a exportação falha com o HTTP 403 e uma mensagem do servidor semelhante a 403 Forbidden, com falhas de agent-ID-mismatch ao chamar os pontos finais de rastreios do Agent 365.

Causa raiz: este erro ocorre quando usa o ID do cliente do esquema, em vez do ID do cliente da instância de agente ao definir os detalhes do agente. O ID do agente no URL de exportação não corresponde à identidade autorizada pelo token, por isso o ponto final dos rastreios rejeita o pedido.

Resolução:

  • Verifique se o ID do inquilino foi adicionado à lista de inquilinos permitidos do Agent 365.
  • Defina os detalhes do agente com o ID do cliente da instância de agente (não o ID do cliente do esquema).
  • Verifique o URL de exportação gerado – está registado se ativar o seu logger. Confirme se o ID do agente no URL corresponde ao ID do cliente da instância de agente.
  • Para ativar o registo de diagnóstico para cada SDK, consulte Validação local.

Erros HTTP 429 ou 5xx - Erros transitórios

Sintomas: a exportação falha com um código de estado HTTP transitório como 429 ou 5xx.

Resolução:

  • Estes erros são geralmente transitórios e resolvem-se por si mesmos. Os distros do Python e JavaScript tentam novamente automaticamente em casos de códigos de estado HTTP 408, 429 e 5xx. O distro do .NET não tenta novamente automaticamente.
  • Se persistirem erros, verifique o dashboard do estado de funcionamento do serviço.
  • Considere reduzir a frequência de exportação aumentando o atraso programado entre lotes ou o tamanho máximo do lote de exportação. Para o Python e o JavaScript, utilize os parâmetros exporterOptions ou a365_* relevantes documentados nos repositórios do GitHub . Para o .NET, utilize o.Agent365.Exporter.ScheduledDelayMilliseconds e o.Agent365.Exporter.MaxExportBatchSize.

Tempo limite de exportação

Sintomas: as tentativas de exportação excedem o tempo limite.

Resolução:

  • Verifique a conectividade de rede com o ponto final de observabilidade.

  • O tempo limite predefinido para pedidos HTTP é de 30 segundos em todas as plataformas. Se ocorrerem tempos limite com frequência, aumente o valor do tempo limite nas opções do seu exportador:

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

    Consulte o repositório do Python para obter a lista completa de opções do a365_*.

A exportação é bem-sucedida, mas a telemetria não aparece no Defender ou no Purview

Sintomas: os registos mostram uma exportação bem-sucedida (HTTP 200), mas a telemetria não é visível no Microsoft Defender ou no Microsoft Purview.

Resolução:

  • Certifique-se de que cumpre os pré-requisitos para ver os registos exportados:
  • A telemetria pode demorar vários minutos a ser disponibilizada após uma exportação bem-sucedida. Aguarde antes de investigar mais a fundo.
  • Verifique se os spans contêm os atributos válidos microsoft.tenant.id e gen_ai.agent.id. A ausência de atributos de identidade faz com que os spans sejam descartados no servidor, mesmo que a exportação HTTP devolva 200.

Conteúdos relacionados

  • Last updated on