Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro é uma distribuição de observabilidade unificada que fornece uma única experiência de integração para coletar rastreamentos, métricas e logs de aplicativos agentes e não-agentes. Oferece suporte à observabilidade para Microsoft Agent 365, Microsoft Foundry, Azure Monitor e qualquer back-end compatível com o protocolo OpenTelemetry (OTLP). A distribuição oferece suporte a .NET, Node.js, e Python e substitui as configurações fragmentadas em várias pilhas de observabilidade por uma importação e uma chamada de configuração.

Principais benefícios

O Microsoft OpenTelemetry Distro oferece os seguintes benefícios:

  • Um pacote, uma API: substitua vários pacotes de exportadores e de instrumentação por uma única dependência.
  • Suporte a múltiplos back-ends: enviar telemetria para o Azure Monitor, qualquer ponto de extremidade compatível com o protocolo OTLP (OpenTelemetry Protocol), como Datadog, Grafana ou New Relic e Microsoft Agent 365 ao mesmo tempo.
  • Instrumentações internas: utilize instrumentação automática para HTTP, bancos de dados, SDK do Azure, Azure Functions e muito mais, sem necessidade de configuração adicional.
  • Baseado em padrões: crie com base no OpenTelemetry, a estrutura de observabilidade padrão do setor.
  • Código padrão mínimo: basta adicionar uma importação e uma chamada de função ao ponto de entrada do seu aplicativo.

Instalação e configuração

Este guia mostra como adicionar observabilidade ao seu aplicativo com o Microsoft OpenTelemetry Distro. A Distro coleta automaticamente traços, métricas e logs com instrumentações internas e exporta a telemetria para o Azure Monitor, qualquer ponto de extremidade do OTLP (Protocolo OpenTelemetry) ou Microsoft Agent 365.

Instalar biblioteca

Para começar a usar o Microsoft OpenTelemetry Distro, instale a biblioteca adequada para sua plataforma de desenvolvimento usando o gerenciador de pacotes da linguagem.

Pré-requisitos: Python 3.10 ou superior.

pip install microsoft-opentelemetry

Configuração

O exportador do Agent 365 não utiliza uma cadeia de conexão. Ele descobre seu ponto de extremidade automaticamente com base no locatário. Para habilitar a exportação para o Agent 365, defina o destino do exportador e forneça um resolver de token que retorne um token de acesso para um determinado ID de agente e ID de locatário.

Chame use_microsoft_opentelemetry() para habilitar 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 resolução de token personalizada (em vez do resolvedor de token padrão), consulte Resolvedor de token manual.

Você pode personalizar o comportamento do exportador passando argumentos a365_* opcionais para use_microsoft_opentelemetry().

Parâmetro Descrição Padrão
a365_use_s2s_endpoint Quando True, usa o caminho do ponto de extremidade 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 os 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 de lote para operações de exportação. 512

Propagar contexto

Para manter a observabilidade em operações distribuídas do Agent 365, propague o contexto. Quando você propaga o contexto por meio de seus agentes e serviços, garante que rastreamentos, logs e métricas sejam devidamente correlacionados ao longo de todo o ciclo de vida da solicitação. Essa correlação é necessária para uma experiência completa e eficaz de monitoramento do Microsoft Agent 365.

Atributos de bagagem

Use BaggageBuilder para definir informações contextuais que fluem por todos os spans em uma solicitação. O SDK implementa um SpanProcessor que copia todas as entradas de bagagem não vazias para novos intervalos sem sobrescrever 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, use o auxiliar populate no pacote microsoft-opentelemetry. Esse auxiliar extrai automaticamente os detalhes do chamador, agente, locatário, 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 bagagem

Se o agente usar o pacote de integração de hospedagem, registre o middleware de bagagem para preencher automaticamente a bagagem para cada solicitação de entrada. Essa etapa elimina a necessidade de chamar BaggageBuilder manualmente em cada manipulador de atividade.

Em Python, registre o middleware de bagagem usando 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 de baggage para respostas assíncronas (eventos ContinueConversation) para evitar substituir as informações que a solicitação de origem já estabeleceu.

Os dados de validação estão fluindo no produto

Para visualizar a telemetria do agente no Microsoft Purview ou no Microsoft Defender, certifique-se de que os seguintes requisitos sejam cumpridos:

Instrumentação automática

O Microsoft OpenTelemetry Distro combina pipelines padrão do OpenTelemetry com instrumentação selecionada pela Microsoft. O Distro pode coletar telemetria de aplicativo, telemetria de infraestrutura e telemetria de agente ou IA generativa, dependendo da linguagem e configuração.

Categoria O que ela cobre
Pipelines de sinais Rastreamentos, métricas e logs.
Detecção de recursos Contexto de serviço, host, nuvem e runtime do Azure, quando suportado.
Instrumentação de infraestrutura HTTP, ASP.NET Core, SDK do Azure, clientes de banco de dados e estruturas de registros, onde suportado.
Instrumentação de IA generativa OpenAI, OpenAI do Azure, Kernel semântico, LangChain, SDK de Agentes do OpenAI e Agent Framework, quando suportados.
Escopos manuais do agente Invocação de agente, execução de ferramenta, inferência e telemetria de saída onde suportado.
Exportadores e processadores Azure Monitor, Microsoft Agent 365, OTLP, saída do console, processadores de intervalo, processadores de log e leitores de métricas.

Cobertura de instrumentação

Linguagem Instrumentação comum de aplicativos Instrumentação comum para agentes e IA generativa
Python Recursos, processadores, leitores, registros em log, métricas e rastreamentos do OpenTelemetry. Kernel semântico, SDK de Agentes do OpenAI, Agent Framework, LangChain, Microsoft Agent 365 e escopos do Microsoft Agent 365.
Node.js HTTP, SDK do Azure, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan e Winston. SDK de Agentes do OpenAI, LangChain, bagagem do Microsoft Agent 365 e escopos do Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, SDK do Azure, detecção de recursos, métricas e logs. Kernel semântico, OpenAI e Azure OpenAI, Agent Framework, bagagem do Microsoft Agent 365 e escopos do Microsoft Agent 365.

A instrumentação automática escuta sinais de telemetria emitidos por estruturas e bibliotecas com suporte. A instrumentação manual é usada quando um aplicativo precisa descrever operações específicas do agente, como invocação, execução de ferramentas, inferência ou saída assíncrona.

Adicione fontes, medidores, processadores ou leitores personalizados do OpenTelemetry quando seu aplicativo emitir telemetria que não está coberta pelas instrumentações internas.

Importante

A instrumentação automática preenche apenas os atributos padrão do OpenTelemetry. Ela não inclui todos os atributos que o Agent 365 exige. Você deve adicionar atributos específicos da Microsoft por meio de BaggageBuilder. Para saber quais atributos são necessários, consulte Armazenar atributos de validação.

Bibliotecas de instrumentação internas

A instrumentação automática escuta a telemetria emitida por estruturas com suporte e a encaminha por meio do pipeline OpenTelemetry da Distro. Para cenários de agente, defina bagagem, como ID de locatário e ID do agente antes que a estrutura instrumentada crie intervalos.

Estrutura Python Node.js .NET
Kernel semântico Compatível Sem suporte Compatível
OpenAI e SDK de Agentes do OpenAI Compatível Com suporte Compatível
Agent Framework Compatível Sem suporte Compatível
LangChain Compatível Compatível Não listado

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

Use a instrumentação manual quando a instrumentação automática não descrever a operação do agente com detalhes suficientes. Escopos manuais permitem que uma aplicativo descreva atividades comuns de agentes de maneira consistente entre diferentes linguagens.

Escopo Usar para
InvokeAgentScope O início e a conclusão de uma invocação de agente.
ExecuteToolScope Uma chamada de ferramenta feita por um agente.
InferenceScope Uma operação de inferência de modelo de IA.
OutputScope Saída que deve ser registrada após a conclusão do escopo original.

Reutilize os mesmos valores de identidade da solicitação e do agente entre escopos em uma solicitação 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 de 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 para esses escopos.

Validação local

A validação local confirma que o aplicativo gera telemetria antes da validação de um destino específico do produto. Use a saída do console ou um ponto de extremidade OTLP local para verificar se rastreamentos, métricas e logs estão sendo criados.

Validar com um ponto de extremidade OTLP local

Configurar a Distro para enviar telemetria para um coletor local ou outro ponto de extremidade 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

Use a saída local quando quiser confirmar a instrumentação antes de enviar 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.

Revise a saída local para intervalos de fontes esperadas, como solicitações HTTP, chamadas do OpenAI ou Azure OpenAI, escopos de invocação do agente, escopos de execução de ferramentas ou escopos de inferência. A validação específica do destino pertence à documentação do produto desse destino.

Configurar manualmente a autenticação

Quando você usa o exportador do Agent 365, é preciso disponibilizar um mecanismo para fornecer um token de autenticação. O resolvedor de token funciona por lote de exportação usando a ID do agente e a ID do locatário do contexto de bagagem ativa. A distribuição suporta duas abordagens.

Dica

Se você estiver criando agentes com o SDK de Agentes do Microsoft 365, consulte Configuração de Autenticação de Observabilidade para SDK do Agente para obter instruções passo a passo sobre como configurar a aquisição de token OBO e S2S para agentes agente e não agente.

Resolvedor de token manual

Use um resolvedor manual quando adquirir tokens fora do pipeline do Agent Framework, ao construir aplicativos que não sejam do Agent Framework ou quando usar autenticação S2S (service-to-service) (fluxo de credenciais do cliente). Os agentes podem gerar um token diretamente, por exemplo, usando a MSAL (Biblioteca de Autenticação da Microsoft) ou qualquer outro método de aquisição de token, mas precisam garantir que o token tenha o escopo de observabilidade correto (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Observação

Para autenticação de serviço para serviço (S2S), você deve usar esta abordagem manual do resolvedor de token. O cache de tokens do agente oferece suporte apenas fluxos de autenticação em nome de (OBO).

Os exemplos a seguir mostram o padrão do resolvedor de token OBO (em nome de), o agente adquire um token de usuário por meio do manipulador de autenticação do agente e o troca por um token com escopo para observabilidade. Para exemplos de S2S (service-to-service) e uma comparação entre os métodos de autenticação OBO e S2S, consulte Configuração de autenticação de observabilidade para SDK do agente.

O resolver deve ser síncrono. Adquira o token no seu manipulador de atividade assíncrono (ou via MSAL) e armazene-o em cache para o resolvedor.

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 token do agente com aplicativos do Agent Framework

Para aplicativos do Agent Framework que usam autenticação em nome do usuário (OBO), a distribuição registra automaticamente IExporterTokenCache<AgenticTokenStruct> via DI quando você não define um TokenResolver personalizado. Seu agente chama RegisterObservability() em runtime para fornecer credenciais, e o cache cuida da aquisição e atualização dos tokens.

Observação

Essa abordagem só oferece suporte a fluxos de autenticação em nome de (OBO). Para autenticação de serviço para serviço (S2S), use o resolvedor de token manual em vez disso.

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 atributos de validação

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

Escopo 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 escopo — incluindo a semântica de cada atributo, orientações para escolha de valores e quais atributos podem ser consultados por meio da busca avançada do Microsoft Defender — consulte Referência de atributos de observabilidade do Agent 365. A coluna Aplica-se a identifica a qual escopo cada atributo pertence, e a coluna Obrigatório distingue atributos obrigatórios (M) de opcionais (O).

Testar seu agente com observabilidade

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

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

Exemplos de aplicativos e configuração avançada

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

Solução de Problemas

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

Problema descrição
Os dados de observabilidade não aparecem Nenhuma telemetria é visível porque a exportação do Agent 365 não está habilitada, a configuração está incompleta ou a resolução do token falha.
ID do locatário ou ID do agente ausente - spans ignorados Os spans são filtrados antes da exportação quando os atributos de identidade necessários do locatário ou do agente estão ausentes.
Falha na resolução de token – exportação ignorada ou não autorizada A exportação é ignorada ou rejeitada quando o resolvedor de tokens não retorna um token ou ocorre erro durante a aquisição do token.
HTTP 401 Não Autorizado As solicitações chegam ao serviço, mas a autenticação falha porque o token é inválido, expirou ou o público-alvo está incorreto.
HTTP 403 Proibido A autorização falha devido ao licenciamento de locatário ausente ou permissões de gravação de observabilidade ausentes.
HTTP 403 Proibido - incompatibilidade de ID de agente O serviço rejeita a exportação quando a ID do agente na solicitação é diferente da ID autorizado pelo token.
Erros HTTP 429 ou 5xx - erros transitórios A limitação temporária ou a instabilidade de 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 o tempo limite devido a atrasos na rede ou latência de resposta do ponto de extremidade.
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 está atrasada ou bloqueada por pré-requisitos de downstream e requisitos de esquema.

Dica

O Guia de Solução de Problemas do Agent 365 contém recomendações de solução de problemas de alto nível, melhores práticas e links para conteúdo de soluçã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á habilitada
  • Erros de configuração
  • Problemas do resolvedor de tokens

Soluções: tente as seguintes etapas para resolver o problema:

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

    É necessário habilitar explicitamente o exportador do Agent 365. Quando você não o configurar, a distribuição poderá usar um exportador de console ou não realizar nenhuma exportação. Habilite-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

    Observação

    ENABLE_A365_OBSERVABILITY_EXPORTER é uma alternância secundária que só entra em vigor quando enable_a365=True é definida no código. Você também pode controlá-la por meio do parâmetro a365_enable_observability_exporter.

  • Verificar a configuração do resolver de tokens

    O exportador exige um resolvedor válido de tokens que forneça um token de portador para cada solicitação de exportação. Se o resolvedor de tokens estiver ausente ou retornar null, a exportação será ignorada silenciosamente.

  • Habilitar a exportação do console e verificar a telemetria localmente

    Adicione um exportador de console para verificar se a telemetria está sendo gerada antes de atingir o ponto de extremidade do Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Habilitar registro detalhado

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Verificar logs para erros de exportação

    Use o comando az webapp log tail para pesquisar logs em busca de erros relacionados à observabilidade:

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

ID do locatário ou ID do agente ausente – intervalos ignorados

Sintomas: o sistema descarta silenciosamente intervalos e nunca os exporta. Algumas plataformas registram uma contagem de spans ignorados ou uma mensagem como No spans with tenant/agent identity found. Outras os largam sem registrar nada.

Resolução:

  • Antes da exportação, as partições da distribuição abrangem a identidade do locatário e do agente. Intervalos que não têm um ID de locatário ou um ID de agente são descartados e nunca enviados para o serviço.
  • Verifique se BaggageBuilder está configurado com a ID do locatário e a ID do agente antes de criar intervalos. Esses valores se propagam por meio do contexto OpenTelemetry e são anexados a todos os intervalos criados dentro do escopo da bagagem. Para a API específica da plataforma, consulte Atributos de bagagem.
  • Se você estiver usando o middleware de bagagem ou o auxiliar de contexto do pacote de integração de hospedagem, confirme se a atividade TurnContext tem um destinatário válido com identidade do agente.

Falha na resolução de token, exportação ignorada ou não autorizada

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

Resolução:

  • O resolver de tokens é obrigatório. Se estiver faltando, o exportador gera um erro na inicialização. Verifique se um resolver de tokens foi fornecido e retorna um token de portador válido.
  • Certifique-se de que a ID de locatário e a ID de agente corretas sejam passadas para BaggageBuilder, pois esses valores são encaminhados para o resolvedor de tokens.
  • Para agentes hospedados no Azure, verifique se a Identidade Gerenciada dispõe da permissão de API necessária para o escopo de observabilidade.
  • Para aplicativos .NET que usam o pacote de hospedagem do Agent Framework, a troca de tokens é gerenciada automaticamente via DI. Se os tokens estiverem faltando, confirme que Microsoft.Agents.A365.Observability.Hosting está instalado e registrado.

HTTP 401 Não Autorizado

Sintomas: a exportação falha com HTTP 401. O exportador não faz nova tentativa após esse erro.

Resolução:

  • Verifique se o público-alvo do token corresponde ao escopo do ponto de extremidade de observabilidade.
  • Verifique se o resolver de tokens não está retornando um token de usuário delegado, um token para um destinatário incorreto ou um token expirado.

HTTP 403 Forbidden

Sintomas: a exportação falha com HTTP 403. O exportador não faz nova tentativa após esse erro.

Causa raiz: um erro HTTP 403 pode ter várias causas. Verifique as resoluções a seguir na ordem.

Resolução:

  • Licença ausente — verifique se sua organização possui uma das seguintes licenças atribuídas no centro de administração do Microsoft 365:

    • Teste - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Permissão Agent365.Observability.OtelWrite ausente — conceda a permissão à sua identidade (Identidade Gerenciada ou registro de aplicativo). Sem ela, a exportação de telemetria falha com HTTP 403.

Conceder a permissão

Use uma destas opções:

  • CLI do Agent 365

    Requer uma conta de Administrador Global; executa no diretório do projeto do agente que contém a365.config.json, ou usa --agent-name.

    a365 setup permissions bot

    Ou, sem um arquivo de configuração:

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

  • Portal do Entra

    Nenhum arquivo de configuração necessário; requer acesso do Administrador Global ao registro do aplicativo blueprint.

    1. Acesse o portal do Entra>Registros de aplicativo>, selecione seu aplicativo Blueprint.
    2. Vá para Permissões de API>Adicionar uma permissão>APIs que minha organização usa> e pesquise por 9b975845-388f-4429-889e-eab1ef63949c.
    3. Selecione Permissões delegadas> marque Agent365.Observability.OtelWrite>Adicionar permissões.
    4. Repita as etapas 2 e 3, desta vez selecione Permissões de aplicativo> e marque Agent365.Observability.OtelWrite>Adicionar permissões.
    5. Clique em Conceder consentimento do administrador e confirme.

    Ambos Agent365.Observability.OtelWrite (Delegado) e Agent365.Observability.OtelWrite (Aplicativo) mostram o status Granted.

HTTP 403 Proibido — ID do agente não corresponde

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

Causa raiz: esse erro ocorre quando você usa a ID do cliente do blueprint em vez da ID do cliente da instância do agente ao definir os detalhes do agente. A ID do agente na URL de exportação não corresponde à identidade autorizada pelo token, portanto o ponto de extremidade de rastreamentos rejeita a solicitação.

Resolução:

  • Verifique se a ID do locatário foi adicionada à lista de locatários permitidos pelo Agent 365.
  • Configure os detalhes do agente utilizando a ID do cliente da instância do agente (não o ID do cliente do blueprint).
  • Verifique a URL de exportação gerada, ela é registrada se você habilitar o logger. Confirme que a ID do agente na URL corresponde ao ID do cliente da instância do agente.
  • Para habilitar o log de diagnósticos por SDK, veja Validação local.

Erros HTTP 429 ou 5xx - erros transitórios

Sintomas: falha na exportação com código de status HTTP transitório, como 429 ou 5xx.

Resolução:

  • Esses erros geralmente são transitórios e se resolvem sozinhos. As distribuições Python e JavaScript fazem nova tentativa automática de exportação quando ocorrem códigos de status HTTP 408, 429 ou 5xx. A distribuição do .NET não faz tentativas automáticas novamente.
  • Se os erros persistirem, verifique o painel de integridade do serviço.
  • Considere reduzir a frequência de exportação aumentando o atraso programado entre os lotes ou o tamanho máximo do lote de exportação. Para Python e JavaScript, use os parâmetros relevantes exporterOptions ou a365_* documentados nos repositórios do GitHub. Para .NET, use o.Agent365.Exporter.ScheduledDelayMilliseconds e o.Agent365.Exporter.MaxExportBatchSize .

Tempo limite de exportação

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

Resolução:

  • Verifique a conectividade da rede com o ponto de extremidade de observabilidade.

  • O tempo limite padrão para solicitação HTTP é de 30 segundos em todas as plataformas. Caso os tempos limite ocorram com frequência, aumente o valor de tempo limite nas opções do 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
)

    Confira o repositório Python para ver a lista completa de opções a365_*.

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

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

Resolução:

  • Verifique se você atende aos pré-requisitos para visualizar os registros exportados:
  • A telemetria pode levar vários minutos para ser preenchida após uma exportação bem-sucedida. Espere antes de investigar mais.
  • Verifique se os spans contêm atributos microsoft.tenant.id e gen_ai.agent.id válidos. A ausência de atributos de identidade faz com que os spans sejam removidos no lado do servidor, mesmo que a exportação HTTP retorne 200.

Conteúdo relacionado

  • Last updated on