Referência de telemetria do SDK de Agentes do Microsoft 365

O SDK de Agentes do Microsoft 365 oferece instrumentação embutida para ajudar você a monitorar e depurar seus aplicativos agentes. Cada SDK emite traços e métricas para operações-chave usando as primitivas padrão de observabilidade de seu tempo de execução: System.Diagnostics em C# e OpenTelemetry em Python e JavaScript. Todos os sinais são compatíveis com o ecossistema OpenTelemetry.

Use essa referência para configurar telemetria e consultar nomes de span, nomes de métricas e atributos para sua linguagem SDK. Nomes e tipos de atributos podem variar entre as linguagens, então escolha sua linguagem de desenvolvimento antes de criar consultas, dashboards ou alertas.

Quick navigation

Use esses links para encontrar instruções de configuração e sinais de telemetria para o idioma escolhido.

Use esta referência

Use os sinais de telemetria nesta referência para:

  • Entenda quais dados são coletados: Procure cada faixa e métrica por nome, atributos e propósito.
  • Construa dashboards e alertas: Use nomes métricos e de expansão em ferramentas como Azure Monitor, Jaeger ou Grafana.
  • Problemas de depuração: Use trace spans para identificar onde ocorrem latências ou erros no pipeline de processamento de requisições do seu agente.
  • Compare implementações de linguagem: Verifique nomes e atributos específicos de cada idioma antes de reutilizar painéis ou consultas.

JavaScript telemetry

Esta seção documenta os spans, métricas e registros de log do OpenTelemetry emitidos pelo SDK de Agentes JavaScript e TypeScript.

JavaScript setup

Instale os pacotes OpenTelemetry usados pelo exemplo de rastreamento a seguir:

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-trace-node

Configure o OpenTelemetry antes que seu agente comece a processar solicitações:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';

const sdk = new NodeSDK({
  traceExporter: new ConsoleSpanExporter(),
  // Configure your exporters (Jaeger, Azure Monitor, etc.)
});

sdk.start();

O pacote de telemetria JavaScript é @opentelemetry/api tratado como uma dependência opcional entre pares e usa no-op rastreamento e ajudantes de métricas quando não estão disponíveis. O exemplo exporta apenas traços. Configure um leitor de métricas e um exportador para exportar métricas. Para espelhar logs do SDK no OpenTelemetry, também instale @opentelemetry/api-logs e configure um provedor de logger e um processador e exportador; caso contrário, os logs continuam apenas pela saída do debug SDK.

JavaScript spans

Spans representam operações individuais dentro do processamento de solicitações do seu agente. Cada espaço inclui atributos que fornecem contexto sobre a operação.

O assistente de rastreamento JavaScript não é definido SpanKind explicitamente, então esses intervalos usam o tipo padrão INTERNAL do OpenTelemetry.

CloudAdapter spans

O CloudAdapter é o principal ponto de entrada para o processamento de atividades recebidas a partir dos canais.

agents.adapter.process

Principal alcance de processamento para atividades recebidas.

Attribute Tipo Description
activity.type cadeia O tipo de atividade (mensagem, conversaAtualização, etc.)
activity.channel_id cadeia O canal de onde a atividade se originou (msteams, webchat, etc.)
activity.delivery_mode cadeia O modo de entrega da atividade
activity.conversation_id cadeia O identificador da conversa
activity.is_agentic boolean Se isso é uma solicitação agentical (agente para agente)
agents.adapter.send_activities

Intervalo para enviar uma ou mais atividades para uma conversa.

Attribute Tipo Description
activity.count number Número de atividades enviadas

activity.sent Evento Span (por atividade):

Attribute Tipo Description
activity.id cadeia O identificador da atividade
activity.type cadeia O tipo de atividade
activity.channel_id cadeia O identificador do canal
activity.conversation_id cadeia O identificador da conversa
agents.adapter.update_activity

Span para atualizar uma atividade existente.

Attribute Tipo Description
activity.id cadeia O ID da atividade sendo atualizada
activity.conversation_id cadeia O identificador da conversa
agents.adapter.delete_activity

Span para excluir uma atividade de uma conversa.

Attribute Tipo Description
activity.id cadeia O ID da atividade que está sendo excluída
activity.conversation_id cadeia O identificador da conversa
agents.adapter.continue_conversation

Span por continuar uma conversa de forma proativa.

Attribute Tipo Description
bot.app_id cadeia O ID da aplicação do bot
activity.conversation_id cadeia O identificador da conversa
activity.is_agentic boolean Se isso é um pedido agente
agents.adapter.create_connector_client

Span para criar uma instância cliente conector.

Attribute Tipo Description
service_url cadeia URL do serviço Bot Framework
auth.scopes string[] Os escopos de autenticação
activity.is_agentic boolean Se isso é para uma requisição agente (quando se usa variante identidade)
agents.adapter.create_user_token_client

Span para criar uma instância de cliente de token de usuário.

Attribute Tipo Description
token.service.endpoint cadeia A URL do endpoint do serviço de token
auth.scope cadeia O escopo de autenticação

AgentApplication spans

A classe AgentApplication fornece uma abstração de nível mais alto para construir agentes com roteamento e handlers.

agents.app.run

Principal período de execução para o AgentApplication.

Attribute Tipo Description
activity.type cadeia O tipo de atividade que está sendo processada
activity.channel_id cadeia O identificador do canal
activity.name cadeia Nome da atividade
route.authorized boolean Se o pedido foi autorizado
route.matched boolean Se um manipulador de rotas correspondia à atividade

Child spans:

  • agents.app.route_handler: Inclui route.is_invoke e route.is_agentic atributos
  • agents.app.download_files: Inclui o agents.attachments.count atributo
  • agents.app.typing_indicator: Inclui o contexto da atividade e a sequência de notificação de digitação
  • agents.app.before_turn: Executa condutores antes do turno
  • agents.app.after_turn: Executa condutores após a curva
agents.app.route_handler

Span filho para executar um manipulador de rota pareado.

Attribute Tipo Description
route.is_invoke boolean Se esta é uma rota de atividade de invocação
route.is_agentic boolean Se essa é uma rota agentiva
agents.app.before_turn

Span para execução dos manipuladores antes do turno.

Sem atributos específicos. Encerra a execução dos manipuladores de eventos antes do turno registrados.

agents.app.after_turn

Espaço para execução dos condutores após o turno.

Sem atributos específicos. Encerra a execução dos manipuladores de eventos pós-turno registrados.

agents.app.download_files

Span para baixar anexos de arquivos.

Attribute Tipo Description
agents.attachments.count number Número de anexos sendo baixados
agents.app.typing_indicator

Span para enviar uma atividade periódica de digitação enquanto um turno está sendo processado. Um novo intervalo é emitido para cada notificação de digitação.

Attribute Tipo Description
activity.type cadeia O tipo de atividade (typing; como padrão é unknown quando não está disponível)
activity.channel_id cadeia O identificador do canal, ou unknown quando indisponível
activity.conversation_id cadeia O identificador da conversa, ou unknown quando indisponível
typing.notification.sequence number Número de sequência baseado em um da notificação de digitação para o temporizador de digitação atual

TurnContext spans

O TurnContext gerencia o rumo atual da conversa.

agents.turn.send_activities

Span para enviar atividades pelo contexto do turno.

Attribute Tipo Description
activity.count number Número de atividades enviadas

activity.sent Evento Span (por atividade):

Attribute Tipo Description
activity.id cadeia O identificador da atividade
activity.type cadeia O tipo de atividade
activity.delivery_mode cadeia O modo de entrega da atividade

ConnectorClient spans

O ConnectorClient gerencia a comunicação HTTP com o serviço Bot Framework Connector.

agents.connector.reply_to_activity

Intervalo para responder a uma atividade específica.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
activity.id cadeia A atividade que está sendo respondida
agents.connector.send_to_conversation

Intervalo para enviar uma atividade para uma conversa.

Attribute Tipo Description
activity.conversation_id cadeia O identificador de conversa alvo
agents.connector.update_activity

Span para atualizar uma atividade via conector.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
activity.id cadeia A atividade sendo atualizada
agents.connector.delete_activity

Span para deletar uma atividade via conector.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
activity.id cadeia A atividade sendo deletada
agents.connector.create_conversation

Espaço para criar uma nova conversa.

Sem atributos de nível de span. Métricas são registradas com operation, http.method e http.status_code.

agents.connector.get_conversations

Espaço para recuperar conversas.

Sem atributos de nível de span. Métricas são registradas com operation, http.method e http.status_code.

agents.connector.get_conversation_member

Span para recuperar um membro da conversa.

Sem atributos de nível de span. Métricas são registradas com operation, http.method e http.status_code.

agents.connector.upload_attachment

Span para upload de um anexo.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
agents.connector.get_attachment_info

Span para recuperar informações de apego.

Attribute Tipo Description
attachment.id cadeia O identificador do anexo
agents.connector.get_attachment

Span para recuperar conteúdo de anexos.

Attribute Tipo Description
attachment.id cadeia O identificador do anexo
view.id cadeia O identificador de visualização

AgentClient spans

O AgentClient cuida da comunicação entre agentes.

agents.agent_client.post_activity

Prazo para postar uma atividade para outro agente.

Attribute Tipo Description
target.endpoint cadeia A URL do endpoint do agente alvo
target.client_id cadeia O ID do cliente do agente alvo
http.status_code cadeia Código de status de resposta HTTP

Storage spans

Os intervalos de armazenamento são emitidos por todas as implementações de armazenamento (MemoryStorage, FileStorage, BlobsStorage, CosmosDbPartitionedStorage).

agents.storage.read

Espaço para ler itens do armazenamento.

Attribute Tipo Description
storage.operation cadeia Sempre "read"
storage.key.count number Número de chaves sendo lidas
agents.storage.write

Espaço para escrever itens para armazenamento.

Attribute Tipo Description
storage.operation cadeia Sempre "write"
storage.key.count number Número de chaves sendo escritas
agents.storage.delete

Span para excluir itens do armazenamento.

Attribute Tipo Description
storage.operation cadeia Sempre "delete"
storage.key.count number Número de chaves sendo excluídas

Authentication spans

A autenticação abrange operações de aquisição de tokens via provedor MSAL token.

agents.authentication.get_access_token

Span para adquirir um token de acesso.

Attribute Tipo Description
auth.scope cadeia O escopo de autenticação solicitado
auth.method cadeia O valor resolvido AuthType , como ClientSecret, Certificate, WorkloadIdentity, ou FederatedCredentials
agents.authentication.acquire_token_on_behalf_of

Span para adquirir um token usando o fluxo em nome de Flow.

Attribute Tipo Description
auth.scopes string[] Os escopos de autenticação solicitados
agents.authentication.get_agentic_instance_token

Span para adquirir um token de instância agente.

Attribute Tipo Description
agentic.instance_id cadeia O ID de instância de aplicação agente
agents.authentication.get_agentic_user_token

Span para adquirir um token de usuário agente.

Attribute Tipo Description
agentic.instance_id cadeia O ID de instância de aplicação agente
agentic.user_id cadeia A ID do usuário agente
auth.scopes string[] Os escopos de autenticação solicitados

Authorization spans

Os intervalos de autorização cobrem os manipuladores de autorização usados pelo AgentApplication.

agents.authorization.agentic_token

Span para recuperar um token de autorização agente.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão utilizado
auth.scopes string[] Os escopos de autenticação solicitados
agents.authorization.azure_bot_token

Span para recuperar um token de autorização Azure Serviço de Bot.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão utilizado
agents.authorization.azure_bot_obo_token

Span para recuperar um token Azure Serviço de Bot usando o on-behalf-of.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão utilizado
auth.scopes string[] Os escopos de autenticação solicitados
agents.authorization.azure_bot_signin

Span para o fluxo de Azure Serviço de Bot de login.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.handler.status cadeia O status de login resultante (por exemplo, APROVADO, REJEITADO, REVALIDADO)
auth.handler.status.reason cadeia O motivo do status de registro
auth.connection.name cadeia O nome da conexão utilizado
agents.authorization.azure_bot_signout

Span para desconectar um usuário via Azure Serviço de Bot.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão utilizado
activity.channel_id cadeia O identificador do canal

UserTokenClient spans

O UserTokenClient gerencia as operações de token de usuário contra o Bot Framework Token Service.

agents.user_token_client.get_user_token

Span para conseguir um token de usuário.

Attribute Tipo Description
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal
user.id cadeia O identificador do usuário
agents.user_token_client.sign_out

Span para logout de um usuário.

Attribute Tipo Description
user.id cadeia O identificador do usuário
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_sign_in_resource

Span para obter uma URL de recurso de login.

Attribute Tipo Description
auth.connection.name cadeia O nome da conexão
agents.user_token_client.exchange_token

Span para trocar um token.

Attribute Tipo Description
user.id cadeia O identificador do usuário
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_token_or_sign_in_resource

Span para obter um token ou recurso de login.

Attribute Tipo Description
user.id cadeia O identificador do usuário
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_token_status

Span para obter o status do token.

Attribute Tipo Description
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_aad_tokens

Span para obter tokens Microsoft Entra ID.

Attribute Tipo Description
user.id cadeia O identificador do usuário
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal

Proactive spans

As operações proativas abrangem operações para enviar mensagens e gerenciar conversas fora do turno iniciado pelo usuário.

agents.proactive.store_conversation

Span para armazenar uma referência de conversa para uso proativo posterior.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
agents.proactive.get_conversation

Span para recuperar uma referência de conversa armazenada.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
proactive.conversation_found boolean Se a conversa foi encontrada
agents.proactive.get_conversation_or_throw

Span para recuperar uma referência de conversa armazenada, lançando se não for encontrada.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
agents.proactive.delete_conversation

Span para deletar uma referência de conversa armazenada.

Attribute Tipo Description
activity.conversation_id cadeia O identificador da conversa
agents.proactive.send_activity

Espaço para enviar uma atividade proativa para uma conversa.

Attribute Tipo Description
activity.channel_id cadeia O identificador do canal
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
agents.proactive.continue_conversation

Span para continuar uma conversa de forma proativa com um retorno.

Attribute Tipo Description
activity.channel_id cadeia O identificador do canal
proactive.has_auto_sign_in boolean Se o login automático está configurado
activity.conversation_id cadeia O identificador da conversa
agents.proactive.create_conversation

Espaço para criar uma nova conversa proativa.

Attribute Tipo Description
activity.channel_id cadeia O identificador do canal
proactive.store_conversation boolean Se a conversa deve ser armazenada
proactive.has_handler boolean Se um callback do manipulador foi fornecido
proactive.members_count number Número de membros na conversa

Dialog spans

Os intervalos de diálogo são emitidos pelo @microsoft/agents-hosting-dialogs pacote para operações do ciclo de vida do diálogo.

agents.dialogs.run

Principal faixa de execução para rodar um conjunto de diálogo.

Attribute Tipo Description
dialog.root_id cadeia O identificador raiz do diálogo
activity.type cadeia O tipo de atividade que está sendo processada
activity.channel_id cadeia O identificador do canal
activity.conversation_id cadeia O identificador da conversa
dialog.status cadeia O status de mudança de diálogo
dialog.attempt_count number Número de tentativas de diálogo
agents.dialogs.context.begin

Span para iniciar um novo diálogo.

Attribute Tipo Description
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
dialog.id cadeia O identificador de diálogo
dialog.name cadeia O nome do diálogo
dialog.parent_id cadeia O identificador de diálogo pai
dialog.status cadeia O status de mudança de diálogo
agents.dialogs.context.continue

Span para manter um diálogo ativo.

Attribute Tipo Description
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
dialog.id cadeia O identificador de diálogo
dialog.name cadeia O nome do diálogo
dialog.status cadeia O status de mudança de diálogo
agents.dialogs.context.end

Span para encerrar um diálogo.

Attribute Tipo Description
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
dialog.id cadeia O identificador de diálogo
dialog.name cadeia O nome do diálogo
dialog.status cadeia O status de mudança de diálogo
agents.dialogs.context.replace

Span para substituir o diálogo atual por um novo.

Attribute Tipo Description
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
dialog.id cadeia O identificador atual do diálogo
dialog.name cadeia O nome atual do diálogo
dialog.replacement_id cadeia O identificador de diálogo substituto
dialog.replacement_name cadeia Nome do diálogo de substituição
dialog.status cadeia O status de mudança de diálogo
agents.dialogs.context.cancel_all

Span para cancelar todos os diálogos ativos.

Attribute Tipo Description
activity.type cadeia O tipo de atividade
activity.conversation_id cadeia O identificador da conversa
dialog.cancel_parents boolean Se os diálogos pais também deveriam ser cancelados
dialog.event_name cadeia Nome do evento de cancelamento
dialog.id cadeia O identificador de diálogo
dialog.name cadeia O nome do diálogo
dialog.status cadeia O status de mudança de diálogo

O cliente do Copilot Studio abrange

Os spans do Copilot Studio Client são emitidos pelo @microsoft/agents-copilotstudio-client pacote para comunicação direta com o motor.

agents.copilot_client.start_conversation

Span por iniciar uma nova conversa com um agente do Copilot Studio.

Attribute Tipo Description
copilot.emit_start_event boolean Se um evento de início foi emitido (condicional)
copilot.request boolean true quando a operação usa o caminho de requisição em vez de emitir um evento de início (condicional)
agents.copilot_client.send_activity

Span por enviar uma atividade para um agente do Copilot Studio.

Attribute Tipo Description
copilot.activity.type cadeia O tipo de atividade
copilot.activity.conversation_id cadeia O identificador da conversa
agents.copilot_client.post_request

Span para fazer uma requisição HTTP para a API do Copilot Studio.

Attribute Tipo Description
copilot.post_request.url cadeia A URL da solicitação
copilot.post_request.method cadeia O método HTTP

activity.received Evento de expansão (por atividade de resposta):

Attribute Tipo Description
copilot.post_request.activity.type cadeia O tipo de atividade de resposta
copilot.post_request.activity.conversation_id cadeia O identificador da conversa
agents.copilot_client.webchat.create_connection

Span para criar uma conexão por WebChat com um agente do Copilot Studio.

Attribute Tipo Description
copilot.webchat.show_typing boolean Se indicadores de digitação são mostrados
agents.copilot_client.webchat.start_conversation

Espaço para iniciar uma conversa por WebChat e receber suas atividades iniciais.

Attribute Tipo Description
copilot.webchat.activity.received_count number Número de atividades iniciais recebidas
copilot.webchat.conversation_id cadeia O identificador de conversa do WebChat
agents.copilot_client.webchat.post_activity

Intervalo para postar uma atividade em uma conversa WebChat e coletar atividades de resposta.

Attribute Tipo Description
copilot.webchat.activity.id cadeia O identificador de atividade postado
copilot.webchat.activity.type cadeia O tipo de atividade postado
copilot.webchat.activity.received_count number Número de atividades de resposta recebidas
copilot.webchat.conversation_id cadeia O identificador de conversa do WebChat

activity.sent Evento SPAN:

Attribute Tipo Description
copilot.webchat.activity.id cadeia O identificador de atividade enviada
copilot.webchat.activity.type cadeia O tipo de atividade enviada
copilot.webchat.activity.conversation_id cadeia O identificador de conversa do WebChat
agents.copilot_client.webchat.receive_activity

Span para receber uma atividade de uma conversa por WebChat.

Attribute Tipo Description
copilot.webchat.activity.id cadeia O identificador de atividade recebido
copilot.webchat.activity.type cadeia O tipo de atividade recebido
copilot.webchat.activity.conversation_id cadeia O identificador de conversa do WebChat
agents.copilot_client.webchat.end_connection

Span para encerrar uma conexão por WebChat.

Attribute Tipo Description
copilot.webchat.conversation_id cadeia O identificador de conversa do WebChat
agents.copilot_client.execute_streaming

Span para executar uma solicitação de streaming para um agente do Copilot Studio.

Attribute Tipo Description
copilot.activity.type cadeia O tipo de atividade
copilot.activity.conversation_id cadeia O identificador da conversa
agents.copilot_client.subscribe_async

Span para assinar eventos assíncronos de um agente do Copilot Studio.

Attribute Tipo Description
copilot.subscribe_async.conversation_id cadeia O identificador da conversa
copilot.subscribe_async.last_received_event_id cadeia O último ID de evento recebido

event.received Evento de Expansão (por Evento Recebido):

Attribute Tipo Description
copilot.subscribe_async.event.id cadeia O identificador do evento
copilot.subscribe_async.event.activity.type cadeia O tipo de atividade no evento

Vãos de tubos nomeados

Vãos de tubos nomeados são emitidos pelo @microsoft/agents-hosting-directline-namedpipes pacote.

agents.named_pipe.connect

Vão para estabelecer uma conexão de cano nomeada.

Attribute Tipo Description
agents.named_pipe.pipe_name cadeia O nome do cano conectado
agents.named_pipe.dispatch

Span para despachar uma solicitação de pipe nomeada de entrada para o manipulador de atividades.

Attribute Tipo Description
agents.named_pipe.request.verb cadeia O verbo de pedido
agents.named_pipe.request.path cadeia O caminho da solicitação
agents.named_pipe.response.status_code number O código de status de resposta
agents.named_pipe.send

Span para enviar uma resposta pelo pipe nomeado.

Attribute Tipo Description
agents.named_pipe.response.status_code number O código de status de resposta
agents.named_pipe.response.body_size number O tamanho do corpo da resposta em bytes

Slack spans

Vão de folga são emitidos pelo @microsoft/agents-hosting-extensions-slack pacote.

agents.slack.api.call

Span para uma chamada de API Web do Slack de saída.

Attribute Tipo Description
slack.api.method cadeia O método da API Web do Slack, como chat.postMessage
http.method cadeia Sempre POST
http.status_code cadeia O código de status de resposta HTTP, ou unknown quando nenhuma resposta está disponível
slack.api.error_code cadeia O código de erro da API do Slack (presente apenas quando o Slack retorna um)
server.address cadeia Sempre slack.com

Tratamento de erros em vãos

Todos os spans criados pelo SDK lidam automaticamente com erros. Quando ocorre uma exceção dentro de uma operação rastreada:

  1. O status do espanto é definido para ERROR com a mensagem de erro
  2. A exceção é registrada no vão via recordException()
  3. O gancho final específico da definição do vão é perfeito e pode inspecionar o erro
  4. O vão é encerrado e o erro original é relançado

Em caso de sucesso, o status de expansão é definido para OK.

Filter JavaScript abrange com um sampler baseado em pai

Warning

AGENTS_TELEMETRY_DISABLED_SPAN_CATEGORIES é preterido e será removido em uma versão futura. Ele permanece suportado temporariamente para compatibilidade retroativa, mas novas aplicações devem configurar um sampler OpenTelemetry em vez disso.

Filtragem pertence à configuração OpenTelemetry da aplicação. Um sampler personalizado pode rejeitar nomes de span SDK selecionados, enquanto um delegado baseado em pai preserva decisões normais de amostragem e rejeita descendentes de um span pai filtrado.

O seguinte sampler reutilizável filtra a telemetria automática do indicador de digitação. O agents.app.typing_indicator span é o pai dos spans do adaptador e do conector criados durante o envio dessa notificação, então rejeitá-lo suprime toda a operação de digitação:

Instale os pacotes adicionais usados pelo exemplo do sampler:

npm install @microsoft/agents-telemetry @opentelemetry/sdk-trace-base

Configure o sampler ao criar a NodeSDK instância:

import { SpanNames } from '@microsoft/agents-telemetry';
import { NodeSDK } from '@opentelemetry/sdk-node';
import {
  AlwaysOnSampler,
  ParentBasedSampler,
  SamplingDecision,
  type Sampler,
} from '@opentelemetry/sdk-trace-base';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';

class SpanNameFilteringSampler implements Sampler {
  private readonly filteredSpanNames: ReadonlySet<string>;
  private readonly parentBased = new ParentBasedSampler({
    root: new AlwaysOnSampler(),
  });

  constructor(spanNames: Iterable<string>) {
    this.filteredSpanNames = new Set(spanNames);
  }

  shouldSample: Sampler['shouldSample'] = (context, traceId, spanName, spanKind, attributes, links) => {
    return this.filteredSpanNames.has(spanName)
      ? { decision: SamplingDecision.NOT_RECORD }
      : this.parentBased.shouldSample(context, traceId, spanName, spanKind, attributes, links);
  }

  toString() {
    return `SpanNameFilteringSampler(${[...this.filteredSpanNames].join(',')})`;
  }
}

const sdk = new NodeSDK({
  sampler: new SpanNameFilteringSampler([
    SpanNames.AGENTS_APP_TYPING_INDICATOR,
  ]),
  traceExporter: new ConsoleSpanExporter(),
});

sdk.start();

Adicione outros valores a partir do SpanNames momento em que spans adicionais de SDK devem ser filtrados. Aplicações que migram das categorias STORAGEobsoletas , AUTHENTICATION, AUTHORIZATION, ou DIALOGS devem listar as constantes correspondentes do nome de espaço. Isso dá à aplicação controle explícito sobre sua política de amostragem sem exigir configuração específica do ambiente do SDK.

JavaScript metrics

Métricas fornecem medidas agregadas da operação do seu agente ao longo do tempo.

Activity counters

Contadores acompanham o número total de atividades processadas.

agents.activities.received

Tipo:Unidade de Contador: atividades Descrição: Número total de atividades recebidas pelo adaptador.

Attribute Tipo Description
activity.type cadeia Tipo de atividade recebida
activity.channel_id cadeia Canal de onde veio a atividade
agents.activities.sent

Tipo:Unidade de Contador: atividades Descrição: Número total de atividades de saída enviadas pelo adaptador.

Attribute Tipo Description
activity.type cadeia Tipo de atividade enviada
activity.channel_id cadeia Target channel
activity.conversation_id cadeia O identificador da conversa
agents.activities.updated

Tipo:Unidade de Contador: atividades Descrição: Número total de atividades atualizadas pelo adaptador.

Attribute Tipo Description
activity.channel_id cadeia Canal onde a atividade foi atualizada
agents.activities.deleted

Tipo:Unidade de Contador: atividades Descrição: Número total de atividades excluídas pelo adaptador.

Attribute Tipo Description
activity.channel_id cadeia Canal onde a atividade foi deletada

Request counters

Contadores para solicitações de saída.

agents.connector.request.count

Tipo:Unidade de Contador: requisição Descrição: Número total de requisições HTTP de conectores de saída.

Attribute Tipo Description
operation cadeia Nome da operação do conector (responder.para.atividade, enviar.para.conversa, etc.)
http.method cadeia Método HTTP usado (POST, GET, DELETE, PUT)
http.status_code cadeia Código de status de resposta HTTP
agents.agent_client.request.count

Tipo: Unidade de Caixa : solicitar Descrição: Número total de chamadas entre agentes.

Attribute Tipo Description
target.endpoint cadeia Endpoint do agente alvo
target.client_id cadeia ID do cliente do agente alvo
http.status_code cadeia Código de status de resposta HTTP
agents.auth.token.request.count

Tipo:Unidade de Contador:solicitação Descrição: Número total de tentativas de aquisição de token.

Attribute Tipo Description
auth.method cadeia O valor resolvido AuthType , ou obo, agentic_instance, ou agentic_user para esses fluxos
auth.success boolean Se a aquisição do token foi bem-sucedida
agents.user_token_client.request.count

Tipo:Unidade de Contador: requisição Descrição: Número total de requisições HTTP de cliente de token de usuário.

Attribute Tipo Description
operation cadeia Nome da operação (get.user.token, log.out, exchange.token, etc.)
http.method cadeia Método HTTP usado
http.status_code cadeia Código de status de resposta HTTP

Turn counters

Contadores para processamento de turnos.

agents.turn.count

Tipo:Unidade de Contra-Ataque:turno Descrição: Total de turnos processados.

Attribute Tipo Description
activity.type cadeia Tipo de atividade processada
activity.channel_id cadeia O identificador do canal
agents.turn.error.count

Tipo:Unidade de Contagem:Descrição do turno: Total de turnos que resultaram em erro.

Attribute Tipo Description
error.type cadeia Nome da classe de exceção/erro

Duration histograms

Histogramas acompanham a distribuição das durações das operações.

agents.adapter.process.duration

Tipo:Unidade de histograma: ms Descrição: Duração do método do processo adaptador em milissegundos.

Attribute Tipo Description
activity.type cadeia Tipo de atividade processada
agents.connector.request.duration

Tipo:Unidade de histograma: ms Descrição: Duração das requisições HTTP do conector de saída em milissegundos.

Attribute Tipo Description
operation cadeia Nome da operação do conector
http.method cadeia Método HTTP usado
http.status_code cadeia Código de status de resposta HTTP
agents.agent_client.request.duration

Tipo:Unidade de histograma: ms Descrição: Duração da latência da chamada entre agentes em milissegundos.

Attribute Tipo Description
target.endpoint cadeia Endpoint do agente alvo
target.client_id cadeia ID do cliente do agente alvo
http.status_code cadeia Código de status de resposta HTTP
agents.turn.duration

Tipo:Histograma Unidade: ms Descrição: Duração do processamento de turno de ponta a ponta em milissegundos.

Attribute Tipo Description
activity.type cadeia Tipo de atividade processada
activity.channel_id cadeia O identificador do canal
agents.storage.operation.duration

Tipo:Unidade de histograma: ms Descrição: Duração das operações de armazenamento em milissegundos.

Attribute Tipo Description
storage.operation cadeia Tipo de operação de armazenamento (ler, escrever, excluir)
storage.key.count number Número de chaves na operação
agents.auth.token.duration

Tipo:Unidade de histograma: ms Descrição: Duração da latência de aquisição do token em milissegundos.

Attribute Tipo Description
auth.method cadeia Método de autenticação utilizado
agents.user_token_client.request.duration

Tipo:Unidade de histograma: ms Descrição: Duração das requisições HTTP do cliente de token de usuário em milissegundos.

Attribute Tipo Description
operation cadeia Operation name
http.method cadeia Método HTTP usado
http.status_code cadeia Código de status de resposta HTTP

Dialog metrics

Métricas para operações do ciclo de vida do diálogo a partir de @microsoft/agents-hosting-dialogs.

agents.dialogs.context.count

Tipo:Unidade de Contador:operações Descrição: Número total de operações de contexto de diálogo (início, continuação, fim, substituição, cancel_all).

Attribute Tipo Description
operation cadeia begin, continue, end, replace ou cancel_all
result.status cadeia O status de turno de diálogo resultante
dialog.cancel_parents boolean Se os diálogos pais são cancelados (presente apenas para cancel_all)
agents.dialogs.context.duration

Tipo:Unidade de histograma: ms Descrição: Duração das operações de contexto do diálogo em milissegundos.

Attribute Tipo Description
operation cadeia begin, continue, end, replace ou cancel_all
result.status cadeia O status de turno de diálogo resultante
dialog.cancel_parents boolean Se os diálogos pais são cancelados (presente apenas para cancel_all)

Proactive metrics

Métricas para operações proativas de mensagens.

agents.proactive.operation.count

Tipo:Unidade de Contador:operação Descrição da operação: Número total de operações proativas de enviar, continuar e criar.

Attribute Tipo Description
operation cadeia send.activity, continue.conversation ou create.conversation
operation.success boolean Se a operação foi concluída sem erro
activity.channel_id cadeia O identificador do canal
activity.type cadeia O tipo de atividade (presente apenas para send.activity)
proactive.has_auto_sign_in boolean Se o login automático está configurado (presente apenas para continue.conversation)
proactive.store_conversation boolean Se a conversa é armazenada (presente apenas para create.conversation)
proactive.has_handler boolean Se um manipulador foi fornecido (presente apenas para create.conversation)
agents.proactive.operation.duration

Tipo:Unidade de histograma: ms Descrição: Duração das operações proativas em milissegundos.

Attribute Tipo Description
operation cadeia send.activity, continue.conversation ou create.conversation
operation.success boolean Se a operação foi concluída sem erro
activity.channel_id cadeia O identificador do canal
activity.type cadeia O tipo de atividade (presente apenas para send.activity)
proactive.has_auto_sign_in boolean Se o login automático está configurado (presente apenas para continue.conversation)
proactive.store_conversation boolean Se a conversa é armazenada (presente apenas para create.conversation)
proactive.has_handler boolean Se um manipulador foi fornecido (presente apenas para create.conversation)

Métricas de clientes do Copilot Studio

Métricas para o @microsoft/agents-copilotstudio-client pacote.

agents.copilot_client.activities.received

Tipo: Unidade de Caixa: atividades Descrição: Número total de atividades recebidas de um agente do Copilot Studio.

Attribute Tipo Description
copilot.activity.type cadeia O tipo de atividade recebido
agents.copilot_client.activities.sent

Tipo:Unidade de Caixa: atividades Descrição: Número total de atividades enviadas a um agente do Copilot Studio.

Attribute Tipo Description
copilot.activity.type cadeia O tipo de atividade enviada
agents.copilot_client.conversations.started

Tipo: Unidade de Caixa: conversas Descrição: Número total de conversas iniciadas com agentes do Copilot Studio.

Attribute Tipo Description
operation cadeia Sempre startConversationStreaming
copilot.emit_start_event boolean true quando um evento de início é emitido (condicional)
copilot.request boolean true quando o caminho de requisição é usado (condicional)
agents.copilot_client.webchat.connection.count

Tipo: Unidade de Contato : conexões Descrição: Número total de conexões por WebChat criadas.

Attribute Tipo Description
copilot.webchat.show_typing boolean Se indicadores de digitação são mostrados
agents.copilot_client.request.count

Tipo:Unidade Contadora: requisições Descrição: Número total de requisições HTTP/SSE para a API do Copilot Studio.

Attribute Tipo Description
operation cadeia Sempre postRequestAsync
copilot.post_request.url cadeia A URL da solicitação
copilot.post_request.method cadeia O método HTTP
agents.copilot_client.request.error.count

Tipo:Unidade de Contador: solicitações Descrição: Número total de solicitações falhadas para a API do Copilot Studio.

Attribute Tipo Description
operation cadeia Sempre postRequestAsync
copilot.post_request.url cadeia A URL da solicitação
copilot.post_request.method cadeia O método HTTP
error.type cadeia A classe de erro ou tipo de valor arremessado
agents.copilot_client.request.duration

Tipo:Unidade de histograma: ms Descrição: Duração das solicitações para a API do Copilot Studio em milissegundos.

Attribute Tipo Description
operation cadeia startConversationStreaming, sendActivityStreaming ou executeStreaming
copilot.emit_start_event boolean true para um caminho de evento de início de conversa (condicional)
copilot.request boolean true para um caminho de inicio-conversa (condicional)
copilot.activity.type cadeia Tipo de atividade para operações de envio e execução
agents.copilot_client.stream.duration

Tipo:Unidade de histograma: ms Descrição: Duração das sessões do fluxo SSE em milissegundos.

Attribute Tipo Description
operation cadeia postRequestAsync ou subscribeAsync
copilot.post_request.url cadeia A URL da solicitação (presente apenas para postRequestAsync)
copilot.post_request.method cadeia O método HTTP (presente apenas para postRequestAsync)
agents.copilot_client.execute_streaming.count

Tipo:Unidade de Contador:operações Descrição: Número total de operações de execução em streaming.

Attribute Tipo Description
copilot.activity.type cadeia O tipo de atividade
agents.copilot_client.subscribe_async.count

Tipo:Unidade de Contador:operações Descrição: Número total de operações de assinatura assíncrona.

Attribute Tipo Description
operation cadeia Sempre subscribeAsync
agents.copilot_client.subscribe_event.count

Tipo:Unidade de Contador: eventos Descrição: Número total de eventos recebidos via assinaturas assíncronas.

Attribute Tipo Description
copilot.subscribe_async.event.id cadeia O identificador do evento
copilot.subscribe_async.event.activity.type cadeia O tipo de atividade no evento

Métricas de tubos nomeadas

Métricas emitidas pelo @microsoft/agents-hosting-directline-namedpipes pacote.

agents.named_pipe.connection.count

Tipo: Unidade de contador : conexão Descrição: Número total de conexões de tubulação nomeadas estabelecidas.

Sem atributos de métrica.

agents.named_pipe.dispatch.count

Tipo:Unidade de Contador: solicitação Descrição: Número total de solicitações recebidas enviadas ao manipulador de atividades.

Attribute Tipo Description
request.verb cadeia O verbo de pedido
request.path cadeia O caminho da solicitação
agents.named_pipe.dispatch.duration

Tipo:Unidade de histograma: ms Descrição: Duração do despacho da solicitação do manipulador de atividades em milissegundos.

Attribute Tipo Description
request.verb cadeia O verbo de pedido
request.path cadeia O caminho da solicitação
agents.named_pipe.dispatch.error.count

Tipo:Unidade de Contador:Descrição do erro: Número total de erros de despacho de canos nomeados.

Attribute Tipo Description
error.type cadeia A classe de erro ou tipo de valor arremessado
agents.named_pipe.send.count

Tipo:Unidade de Contador: resposta Descrição: Número total de respostas enviadas pelo cano nomeado.

Sem atributos de métrica.

agents.named_pipe.send.duration

Tipo:Unidade histograma: ms Descrição: Duração das operações de envio de resposta de pipe nomeadas em milissegundos.

Sem atributos de métrica.

Slack metrics

Métricas emitidas pelo @microsoft/agents-hosting-extensions-slack pacote.

agents.slack.api.request.count

Tipo:Unidade de Contador: requisição Descrição: Número total de requisições de saída da API Web do Slack.

Attribute Tipo Description
slack.api.method cadeia O método da API Web do Slack
http.method cadeia Sempre POST
http.status_code cadeia O código de status da resposta HTTP, ou unknown
slack.api.error_code cadeia Código de erro da API do Slack (condicional)
operation.success boolean Se a operação foi concluída sem erro
agents.slack.api.request.duration

Tipo:Unidade de histograma: ms Descrição: Duração das requisições enviadas da API Web do Slack em milissegundos.

Attribute Tipo Description
slack.api.method cadeia O método da API Web do Slack
http.method cadeia Sempre POST
http.status_code cadeia O código de status da resposta HTTP, ou unknown
slack.api.error_code cadeia Código de erro da API do Slack (condicional)
operation.success boolean Se a operação foi concluída sem erro

Referência às constantes de varredura do JavaScript

Todos os nomes de span estão disponíveis como constantes no @microsoft/agents-telemetry pacote:

import { SpanNames } from '@microsoft/agents-telemetry';

// CloudAdapter
SpanNames.ADAPTER_PROCESS                  // 'agents.adapter.process'
SpanNames.ADAPTER_SEND_ACTIVITIES          // 'agents.adapter.send_activities'
SpanNames.ADAPTER_UPDATE_ACTIVITY          // 'agents.adapter.update_activity'
SpanNames.ADAPTER_DELETE_ACTIVITY          // 'agents.adapter.delete_activity'
SpanNames.ADAPTER_CONTINUE_CONVERSATION    // 'agents.adapter.continue_conversation'
SpanNames.ADAPTER_CREATE_CONNECTOR_CLIENT  // 'agents.adapter.create_connector_client'
SpanNames.ADAPTER_CREATE_USER_TOKEN_CLIENT // 'agents.adapter.create_user_token_client'

// AgentApplication
SpanNames.AGENTS_APP_RUN               // 'agents.app.run'
SpanNames.AGENTS_APP_ROUTE_HANDLER     // 'agents.app.route_handler'
SpanNames.AGENTS_APP_BEFORE_TURN       // 'agents.app.before_turn'
SpanNames.AGENTS_APP_AFTER_TURN        // 'agents.app.after_turn'
SpanNames.AGENTS_APP_DOWNLOAD_FILES    // 'agents.app.download_files'
SpanNames.AGENTS_APP_TYPING_INDICATOR  // 'agents.app.typing_indicator'

// ConnectorClient
SpanNames.CONNECTOR_SEND_TO_CONVERSATION   // 'agents.connector.send_to_conversation'
SpanNames.CONNECTOR_REPLY_TO_ACTIVITY      // 'agents.connector.reply_to_activity'
SpanNames.CONNECTOR_UPDATE_ACTIVITY        // 'agents.connector.update_activity'
SpanNames.CONNECTOR_DELETE_ACTIVITY        // 'agents.connector.delete_activity'
SpanNames.CONNECTOR_CREATE_CONVERSATION    // 'agents.connector.create_conversation'
SpanNames.CONNECTOR_GET_CONVERSATIONS      // 'agents.connector.get_conversations'
SpanNames.CONNECTOR_GET_CONVERSATION_MEMBER // 'agents.connector.get_conversation_member'
SpanNames.CONNECTOR_UPLOAD_ATTACHMENT      // 'agents.connector.upload_attachment'
SpanNames.CONNECTOR_GET_ATTACHMENT         // 'agents.connector.get_attachment'
SpanNames.CONNECTOR_GET_ATTACHMENT_INFO    // 'agents.connector.get_attachment_info'

// Storage
SpanNames.STORAGE_READ                 // 'agents.storage.read'
SpanNames.STORAGE_WRITE                // 'agents.storage.write'
SpanNames.STORAGE_DELETE               // 'agents.storage.delete'

// AgentClient
SpanNames.AGENT_CLIENT_POST_ACTIVITY   // 'agents.agent_client.post_activity'

// Authentication
SpanNames.AUTHENTICATION_GET_ACCESS_TOKEN            // 'agents.authentication.get_access_token'
SpanNames.AUTHENTICATION_ACQUIRE_TOKEN_ON_BEHALF_OF  // 'agents.authentication.acquire_token_on_behalf_of'
SpanNames.AUTHENTICATION_GET_AGENTIC_INSTANCE_TOKEN  // 'agents.authentication.get_agentic_instance_token'
SpanNames.AUTHENTICATION_GET_AGENTIC_USER_TOKEN      // 'agents.authentication.get_agentic_user_token'

// Authorization
SpanNames.AUTHORIZATION_AGENTIC_TOKEN          // 'agents.authorization.agentic_token'
SpanNames.AUTHORIZATION_AZURE_BOT_TOKEN        // 'agents.authorization.azure_bot_token'
SpanNames.AUTHORIZATION_AZURE_BOT_OBO_TOKEN    // 'agents.authorization.azure_bot_obo_token'
SpanNames.AUTHORIZATION_AZURE_BOT_SIGNIN       // 'agents.authorization.azure_bot_signin'
SpanNames.AUTHORIZATION_AZURE_BOT_SIGNOUT      // 'agents.authorization.azure_bot_signout'

// UserTokenClient
SpanNames.USER_TOKEN_CLIENT_GET_USER_TOKEN              // 'agents.user_token_client.get_user_token'
SpanNames.USER_TOKEN_CLIENT_SIGN_OUT                    // 'agents.user_token_client.sign_out'
SpanNames.USER_TOKEN_CLIENT_GET_SIGN_IN_RESOURCE        // 'agents.user_token_client.get_sign_in_resource'
SpanNames.USER_TOKEN_CLIENT_EXCHANGE_TOKEN               // 'agents.user_token_client.exchange_token'
SpanNames.USER_TOKEN_CLIENT_GET_TOKEN_OR_SIGN_IN_RESOURCE // 'agents.user_token_client.get_token_or_sign_in_resource'
SpanNames.USER_TOKEN_CLIENT_GET_TOKEN_STATUS             // 'agents.user_token_client.get_token_status'
SpanNames.USER_TOKEN_CLIENT_GET_AAD_TOKENS               // 'agents.user_token_client.get_aad_tokens'

// Proactive
SpanNames.PROACTIVE_STORE_CONVERSATION       // 'agents.proactive.store_conversation'
SpanNames.PROACTIVE_GET_CONVERSATION         // 'agents.proactive.get_conversation'
SpanNames.PROACTIVE_GET_CONVERSATION_OR_THROW // 'agents.proactive.get_conversation_or_throw'
SpanNames.PROACTIVE_DELETE_CONVERSATION      // 'agents.proactive.delete_conversation'
SpanNames.PROACTIVE_SEND_ACTIVITY            // 'agents.proactive.send_activity'
SpanNames.PROACTIVE_CONTINUE_CONVERSATION    // 'agents.proactive.continue_conversation'
SpanNames.PROACTIVE_CREATE_CONVERSATION      // 'agents.proactive.create_conversation'

// TurnContext
SpanNames.TURN_SEND_ACTIVITIES         // 'agents.turn.send_activities'

// Dialogs
SpanNames.DIALOGS_RUN                  // 'agents.dialogs.run'
SpanNames.DIALOGS_CONTEXT_BEGIN        // 'agents.dialogs.context.begin'
SpanNames.DIALOGS_CONTEXT_CONTINUE     // 'agents.dialogs.context.continue'
SpanNames.DIALOGS_CONTEXT_END          // 'agents.dialogs.context.end'
SpanNames.DIALOGS_CONTEXT_REPLACE      // 'agents.dialogs.context.replace'
SpanNames.DIALOGS_CONTEXT_CANCEL_ALL   // 'agents.dialogs.context.cancel_all'

// Copilot Studio Client
SpanNames.COPILOT_START_CONVERSATION   // 'agents.copilot_client.start_conversation'
SpanNames.COPILOT_SEND_ACTIVITY        // 'agents.copilot_client.send_activity'
SpanNames.COPILOT_POST_REQUEST         // 'agents.copilot_client.post_request'
SpanNames.COPILOT_CREATE_CONNECTION    // 'agents.copilot_client.webchat.create_connection'
SpanNames.COPILOT_WEBCHAT_START_CONVERSATION // 'agents.copilot_client.webchat.start_conversation'
SpanNames.COPILOT_WEBCHAT_POST_ACTIVITY      // 'agents.copilot_client.webchat.post_activity'
SpanNames.COPILOT_WEBCHAT_RECEIVE_ACTIVITY   // 'agents.copilot_client.webchat.receive_activity'
SpanNames.COPILOT_WEBCHAT_END_CONNECTION     // 'agents.copilot_client.webchat.end_connection'
SpanNames.COPILOT_EXECUTE_STREAMING    // 'agents.copilot_client.execute_streaming'
SpanNames.COPILOT_SUBSCRIBE_ASYNC      // 'agents.copilot_client.subscribe_async'

// Named Pipe
SpanNames.NAMED_PIPE_CONNECT           // 'agents.named_pipe.connect'
SpanNames.NAMED_PIPE_DISPATCH          // 'agents.named_pipe.dispatch'
SpanNames.NAMED_PIPE_SEND              // 'agents.named_pipe.send'

// Slack
SpanNames.SLACK_API_CALL               // 'agents.slack.api.call'

Referência de constantes métricas de métrica JavaScript

Todos os nomes das métricas estão disponíveis como constantes:

import { MetricNames } from '@microsoft/agents-telemetry';

// CloudAdapter
MetricNames.ADAPTER_PROCESS_DURATION      // 'agents.adapter.process.duration'

// Activity counters
MetricNames.ACTIVITIES_RECEIVED           // 'agents.activities.received'
MetricNames.ACTIVITIES_SENT               // 'agents.activities.sent'
MetricNames.ACTIVITIES_UPDATED            // 'agents.activities.updated'
MetricNames.ACTIVITIES_DELETED            // 'agents.activities.deleted'

// Connector metrics
MetricNames.CONNECTOR_REQUESTS            // 'agents.connector.request.count'
MetricNames.CONNECTOR_REQUEST_DURATION    // 'agents.connector.request.duration'

// AgentClient metrics
MetricNames.AGENT_CLIENT_REQUESTS         // 'agents.agent_client.request.count'
MetricNames.AGENT_CLIENT_REQUEST_DURATION // 'agents.agent_client.request.duration'

// Turn metrics
MetricNames.TURNS_COUNT                   // 'agents.turn.count'
MetricNames.TURNS_ERRORS                  // 'agents.turn.error.count'
MetricNames.TURN_DURATION                 // 'agents.turn.duration'

// Dialog metrics
MetricNames.DIALOGS_CONTEXT_COUNT         // 'agents.dialogs.context.count'
MetricNames.DIALOGS_CONTEXT_DURATION      // 'agents.dialogs.context.duration'

// Storage metrics
MetricNames.STORAGE_OPERATION_DURATION    // 'agents.storage.operation.duration'

// Authentication metrics
MetricNames.AUTH_TOKEN_REQUEST_COUNT      // 'agents.auth.token.request.count'
MetricNames.AUTH_TOKEN_DURATION           // 'agents.auth.token.duration'

// UserTokenClient metrics
MetricNames.USER_TOKEN_CLIENT_REQUESTS          // 'agents.user_token_client.request.count'
MetricNames.USER_TOKEN_CLIENT_REQUEST_DURATION  // 'agents.user_token_client.request.duration'

// Proactive metrics
MetricNames.PROACTIVE_OPERATION_COUNT     // 'agents.proactive.operation.count'
MetricNames.PROACTIVE_OPERATION_DURATION  // 'agents.proactive.operation.duration'

// Copilot Studio Client metrics
MetricNames.CSC_ACTIVITIES_RECEIVED       // 'agents.copilot_client.activities.received'
MetricNames.CSC_ACTIVITIES_SENT           // 'agents.copilot_client.activities.sent'
MetricNames.CSC_CONVERSATIONS_STARTED     // 'agents.copilot_client.conversations.started'
MetricNames.CSC_WEBCHAT_CONNECTIONS       // 'agents.copilot_client.webchat.connection.count'
MetricNames.CSC_REQUEST_COUNT             // 'agents.copilot_client.request.count'
MetricNames.CSC_REQUEST_ERRORS            // 'agents.copilot_client.request.error.count'
MetricNames.CSC_STREAM_DURATION           // 'agents.copilot_client.stream.duration'
MetricNames.CSC_REQUEST_DURATION          // 'agents.copilot_client.request.duration'
MetricNames.CSC_EXECUTE_STREAMING         // 'agents.copilot_client.execute_streaming.count'
MetricNames.CSC_SUBSCRIBE_ASYNC           // 'agents.copilot_client.subscribe_async.count'
MetricNames.CSC_SUBSCRIBE_EVENT           // 'agents.copilot_client.subscribe_event.count'

// Named Pipe metrics
MetricNames.NAMED_PIPE_CONNECTIONS         // 'agents.named_pipe.connection.count'
MetricNames.NAMED_PIPE_DISPATCHES          // 'agents.named_pipe.dispatch.count'
MetricNames.NAMED_PIPE_DISPATCH_DURATION   // 'agents.named_pipe.dispatch.duration'
MetricNames.NAMED_PIPE_DISPATCH_ERRORS     // 'agents.named_pipe.dispatch.error.count'
MetricNames.NAMED_PIPE_SENDS               // 'agents.named_pipe.send.count'
MetricNames.NAMED_PIPE_SEND_DURATION       // 'agents.named_pipe.send.duration'

// Slack metrics
MetricNames.SLACK_API_REQUESTS             // 'agents.slack.api.request.count'
MetricNames.SLACK_API_REQUEST_DURATION     // 'agents.slack.api.request.duration'

Registros de log JavaScript

O @microsoft/agents-telemetrydebug(namespace) ajudante sempre escreve pelo logger do debug SDK. Quando o pacote opcional @opentelemetry/api-logs está disponível, ele também emite um registro de log OpenTelemetry através do registrador nomeado por namespace.

Field Value
Severity number OpenTelemetry DEBUG, INFO, WARN, ou ERROR
Severity text DEBUG, INFO, WARNou ERROR
Body A mensagem seguida por argumentos extras serializados
log.namespace O namespace do logger foi passado para debug(namespace)
log.level Minúsculas debug, info, warn, ou error

Um Error argumento é serializado como seu nome e mensagem. Outros argumentos que não são de string são serializados em JSON sempre que possível. Os aplicativos devem configurar um provedor de registrador OpenTelemetry e processador/exportador para exportar esses registros. Se @opentelemetry/api-logs estiver ausente, rastreamento e métricas ainda podem operar por @opentelemetry/api, enquanto a emissão logarítmica retorna apenas à saída do debug SDK.

C# telemetry

Esta seção documenta os traços e métricas emitidos pelo SDK de Agentes C#.

System.Diagnostics integration

O SDK C# não depende do OpenTelemetry. Toda a instrumentação é construída sobre System.Diagnostics, a camada de rastreamento distribuído e métricas embutida no runtime .NET:

  • Spans são System.Diagnostics.Activity objetos criados a partir de um .ActivitySource
  • Métricas são Counter<T> e Histogram<T> instrumentos criados a partir de um .Meter

Ambos são publicados sob o nome Microsoft.Agents.Corede origem . Qualquer ouvinte assinado com esse nome recebe a telemetria — a OpenTelemetry é apenas um ouvinte possível.

// The single source used for all SDK traces and metrics
AgentsTelemetry.SourceName    // "Microsoft.Agents.Core"
AgentsTelemetry.SourceVersion // Assembly file version
AgentsTelemetry.ActivitySource // System.Diagnostics.ActivitySource
AgentsTelemetry.Meter          // System.Diagnostics.Metrics.Meter

Esse design significa que o SDK se integra naturalmente a qualquer ferramenta de observabilidade que compreenda System.Diagnostics, não apenas com o SDK OpenTelemetry.

C# setup

Adicione os pacotes NuGet da OpenTelemetry ao seu projeto agente:

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Depois, assine a Microsoft.Agents.Core fonte e mede em Program.cs:

using Microsoft.Agents.Core.Telemetry;
using Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .ConfigureResource(r => r.AddService(
        serviceName: AgentsTelemetry.SourceName,
        serviceVersion: AgentsTelemetry.SourceVersion))
    .WithTracing(tracing => tracing
        .AddSource(AgentsTelemetry.SourceName)
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter())
    .WithMetrics(metrics => metrics
        .AddMeter(AgentsTelemetry.SourceName)
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter());

Como o SDK emite sinais padrãoSystem.Diagnostics, você pode substituir qualquer exportador (Console, Azure Monitor, Jaeger, Prometheus, etc.) sem alterar o código do agente.

Saiba mais no exemplo do TelemetryAgent e seu assistente compartilhado de configuração OpenTelemetry.

C# spans

No SDK C#, o que este documento chama de "estanque" é um System.Diagnostics.Activity criado a partir de AgentsTelemetry.ActivitySource. O termo "span" é usado aqui para consistência com os SDKs JavaScript e Python, cuja observabilidade é construída diretamente sobre o OpenTelemetry. Os objetos subjacentes System.Diagnostics.Activity são totalmente compatíveis com o OpenTelemetry quando um ouvinte, como o SDK .NET do OpenTelemetry, está configurado.

Abrangimentos de CloudAdapter em C#

CloudAdapter As SPANs abrangem processamento de atividades recebidas, manejo de respostas e criação de conectores.

agents.adapter.process

Principal alcance de processamento para cada atividade recebida.

Attribute Tipo Description
activity.type cadeia O tipo de atividade (mensagem, conversaAtualização, etc.)
activity.channel_id cadeia O canal de onde a atividade se originou
activity.delivery_mode cadeia O modo de entrega da atividade
activity.conversation.id cadeia O identificador da conversa
activity.is_agentic_request boolean Se isso é um pedido de agente para agente
agents.adapter.write_response

Span usado pelos manipuladores de resposta para atividades em streaming, respostas A2A e a resposta final invoke ou expectReplies resposta.

Attribute Tipo Description
activities.count inteiro Número de atividades na resposta
activity.conversation.id cadeia O identificador da conversa
agents.adapter.send_activities

Span para enviar uma ou mais atividades pelo adaptador.

Attribute Tipo Description
activities.count inteiro Número de atividades enviadas
activity.conversation.id cadeia O identificador da conversa
agents.adapter.update_activity

Span para atualizar uma atividade existente.

Attribute Tipo Description
activity.id cadeia O ID da atividade sendo atualizada
activity.conversation.id cadeia O identificador da conversa
agents.adapter.delete_activity

Span por excluir uma atividade.

Attribute Tipo Description
activity.type cadeia Sempre "event"; retirado da atividade de continuação sintetizada
activity.conversation.id cadeia O identificador da conversa
agents.adapter.continue_conversation

Span por continuar uma conversa de forma proativa.

Attribute Tipo Description
agent.app_id cadeia O ID da inscrição do agente
activity.conversation.id cadeia O identificador da conversa
activity.is_agentic_request boolean Se isso é um pedido agente
agents.adapter.create_connector_client

Span para criar uma instância cliente conector.

Attribute Tipo Description
service_url cadeia URL do serviço Bot Framework
auth.scopes cadeia Escopos de autenticação separados por vírgulas
activity.is_agentic_request boolean Se isso é para um pedido agente
agents.adapter.create_user_token_client

Span para criar uma instância de cliente de token de usuário.

Attribute Tipo Description
agents.token_service.endpoint cadeia A URL do endpoint do serviço de token

O C# AgentApplication abrange

AgentApplication Os abrangentes cobrem execução de turnos, manipuladores de rotas e eventos do ciclo de vida.

agents.app.run

A execução principal se estende por um turno até AgentApplication.

Attribute Tipo Description
activity.type cadeia O tipo de atividade que está sendo processada
activity.name cadeia O nome da atividade
activity.channel_id cadeia O identificador do canal
activity.conversation.id cadeia O identificador da conversa
activity.id cadeia O identificador da atividade
route.authorized boolean Se o pedido foi autorizado
route.matched boolean Se um manipulador de rotas correspondia à atividade
agents.app.route_handler

Span filho para executar um manipulador de rota pareado.

Attribute Tipo Description
route.is_invoke boolean Se esta é uma rota de atividade de invocação
route.is_agentic boolean Se essa é uma rota agentiva
agents.app.before_turn

Span para execução do manipulador antes do turno. Sem atributos adicionais.

agents.app.after_turn

Span para execução do manipulador após o turno. Sem atributos adicionais.

agents.app.download_files

Span para baixar anexos de arquivos.

Attribute Tipo Description
activity.attachments.count inteiro Número de anexos na atividade
agents.app.typing_indicator

Espaço para enviar um indicador automático de digitação durante uma curva.

Attribute Tipo Description
activity.type cadeia Sempre "typing"
activity.channel_id cadeia O identificador do canal
activity.conversation.id cadeia O identificador da conversa

C# TurnContext abrange

TurnContext emite um intervalo quando envia atividades.

agents.turn.send_activities

Intervalo emitido a TurnContext cada vez que atividades são enviadas.

Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa

Conectores C# Clientes

ConnectorClient Os vãos cobrem operações de conexão de saída.

agents.connector.reply_to_activity
Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa
activity.id cadeia A atividade que está sendo respondida
agents.connector.send_to_conversation
Attribute Tipo Description
activity.conversation.id cadeia O identificador de conversa alvo
activity.id cadeia O identificador de atividade (quando fornecido)
agents.connector.update_activity
Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa
activity.id cadeia A atividade sendo atualizada
agents.connector.delete_activity
Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa
activity.id cadeia A atividade sendo deletada
agents.connector.create_conversation

Sem atributos de nível de span.

agents.connector.get_conversations

Sem atributos de nível de span.

agents.connector.get_conversation_members

Esse vão abrange tanto GetConversationMembersAsync quanto a operação singular GetConversationMemberAsync .

Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa
agents.connector.upload_attachment
Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa
agents.connector.get_attachment_info
Attribute Tipo Description
activity.attachment.id cadeia O identificador do anexo
agents.connector.get_attachment
Attribute Tipo Description
activity.attachment.id cadeia O identificador do anexo
view.id cadeia O identificador de visualização

C# UserTokenClient spans

O cliente token de usuário abrange o registro auth.connection.name, user.id, e activity.channel_id quando o escopo recebe esses valores. IDs de canal ausentes são registrados como "unknown".

agents.user_token_client.get_user_token
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.sign_out
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_sign_in_resource
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.exchange_token
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_token_or_sign_in_resource
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_token_status
Attribute Tipo Description
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal
agents.user_token_client.get_aad_tokens
Attribute Tipo Description
auth.connection.name cadeia O nome da conexão OAuth
user.id cadeia O identificador do usuário
activity.channel_id cadeia O identificador do canal

Espaços de armazenamento em C#

BlobsStorage e CosmosDbPartitionedStorage emitir esses vãos.

agents.storage.read
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo lidas
storage.operation cadeia Sempre "read"
agents.storage.write
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo escritas
storage.operation cadeia Sempre "write"
agents.storage.delete
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo excluídas
storage.operation cadeia Sempre "delete"

Abrangentes de autenticação C#

A autenticação abrange aquisição de tokens de acesso e operações de token agente.

agents.authentication.get_access_token
Attribute Tipo Description
auth.method cadeia O método de autenticação — valor é AuthTypes.ToString() (por exemplo, "ClientSecret", "Certificate", "UserManagedIdentity""CertificateSubjectName", "SystemManagedIdentity", "WorkloadIdentity", , "FederatedCredentials", , ou "IdentityProxyManager")
auth.scopes cadeia escopos de autenticação separados por vírgula; "unknown" quando nulos ou vazios
agents.authentication.acquire_token_on_behalf_of
Attribute Tipo Description
auth.method cadeia Sempre "obo"
auth.scopes cadeia escopos de autenticação separados por vírgula; "unknown" quando nulos ou vazios
agents.authentication.get_agentic_instance_token
Attribute Tipo Description
auth.method cadeia Sempre "agentic_instance"
agentic.instance_id cadeia O ID de instância de aplicação agente
agents.authentication.get_agentic_user_token
Attribute Tipo Description
auth.method cadeia Sempre "agentic_user"
agentic.instance_id cadeia O ID de instância de aplicação agente
agentic.user_id cadeia A ID do usuário agente
auth.scopes cadeia escopos de autenticação separados por vírgula; "unknown" quando nulos ou vazios

Autorização em C# abrange

A autorização abrange a recuperação de tokens do usuário, login e desconexão.

agents.authorization.agentic_token
Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão (omitido se não for fornecido)
auth.scopes cadeia Escopos separados por vírgulas (omitidos se não fornecidos)
agents.authorization.azure_bot_token
Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão (omitido se não for fornecido)
auth.scopes cadeia Escopos separados por vírgulas (omitidos se não fornecidos)
agents.authorization.azure_bot_signin
Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão (omitido se não for fornecido)
auth.scopes cadeia Escopos separados por vírgulas (omitidos se não fornecidos)
activity.channel_id cadeia O identificador do canal
agents.authorization.azure_bot_signout
Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão
activity.channel_id cadeia O identificador do canal

C# Spans proativos

Os períodos proativos abrangem referências de conversas armazenadas e mensagens enviadas fora de um turno iniciado pelo usuário.

agents.proactive.store_conversation

Span para armazenar uma referência de conversa para uso proativo posterior.

Attribute Tipo Description
activity.conversation.id cadeia O identificador de conversa armazenado
agents.proactive.get_conversation

Span para recuperar uma referência de conversa armazenada.

Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa sendo recuperado
proactive.conversation.found boolean Se a conversa foi encontrada
agents.proactive.delete_conversation

Span para deletar uma referência de conversa armazenada.

Attribute Tipo Description
activity.conversation.id cadeia O identificador da conversa sendo excluído
agents.proactive.send_activity

Intervalo para enviar uma atividade proativamente para uma conversa existente. Suporta uma ActivityLink correlação de telemetria com o turno de origem.

Attribute Tipo Description
activity.conversation.id cadeia O identificador de conversa alvo
activity.type cadeia O tipo de atividade enviada
activity.channel_id cadeia O identificador do canal
agents.proactive.continue_conversation

Span para continuar uma conversa armazenada de forma proativa. Suporta uma ActivityLink correlação de telemetria.

Attribute Tipo Description
activity.conversation.id cadeia O identificador de conversa alvo
activity.type cadeia O tipo da atividade de continuação
activity.channel_id cadeia O identificador do canal
agents.proactive.create_conversation

Espaço para criar uma nova conversa proativa.

Attribute Tipo Description
activity.channel_id cadeia O identificador do canal de destino
proactive.members.count inteiro Número de membros na conversa

Manejo de erros em C# em vagens

TelemetryScope.SetError, Wrap, e WrapAsync fornecem o seguinte comportamento de registro de erros quando usados por uma operação instrumentada:

  1. O status do espanto é definido como Error com a mensagem de exceção.
  2. Um evento é adicionado às System.Diagnostics.Activity tags com exception.type, exception.message, e exception.stacktrace seguindo as convenções semânticas exception do OpenTelemetry.

Após a conclusão bem-sucedida, o status da atividade permanece Unset. O SDK não define explicitamente como Ok.

C# metrics

Todos os instrumentos métricos são criados a partir de AgentsTelemetry.Meter (nome "Microsoft.Agents.Core").

Contadores de atividade em C#

Contadores de atividades acompanham atividades recebidas, atividades de saída, atualizações e exclusões.

agents.activities.received

Type: Counter
Unit: activity
Descrição: Atividades totais recebidas pelo adaptador.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
agents.activities.sent

Type: Counter
Unit: activity
Descrição: Total de atividades enviadas.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id ChannelId Valor bruto ChannelId ; representação do exportador pode variar
agents.activities.updated

Type: Counter
Unit: activity
Descrição: Atualizações totais de atividade.

Attribute Tipo Description
activity.channel_id ChannelId Valor bruto ChannelId ; representação do exportador pode variar
agents.activities.deleted

Type: Counter
Unit: activity
Descrição: Eliminações totais de atividade.

Attribute Tipo Description
activity.channel_id ChannelId Valor bruto ChannelId ; representação do exportador pode variar

Métricas de curva em C#

Métricas de curva descrevem a contagem de curvas, erros e duração de ponta a ponta.

agents.turn.count

Type: Counter
Unit: turn
Descrição: Contador destinado a acompanhar as jogadas processadas com sucesso.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
agents.turn.error.count

Type: Counter
Unit: turn
Descrição: Contra-ataque pretendia acompanhar curvas que resultavam em erro.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
agents.turn.duration

Type: Histogram
Unit: ms
Descrição: Duração do processamento de turno de ponta a ponta.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier

Métricas de adaptador C#

Métricas adaptadoras medem a duração do processamento da atividade recebida.

agents.adapter.process.duration

Type: Histogram
Unit: ms
Descrição: Duração do método do processo adaptador.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier

Métricas de conector C#

Métricas de conectores contam as solicitações HTTP de saída e medem sua duração.

agents.connector.request.count

Type: Counter
Unit: request
Descrição: Total de requisições HTTP de saída do conector.

Sem atributos em nível métrico.

agents.connector.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das requisições HTTP de conectores de saída.

Sem atributos em nível métrico.

Métricas UserTokenClient em C#

Métricas de cliente de token de usuário contam as requisições HTTP de saída e medem sua duração.

agents.user_token_client.request.count

Type: Counter
Unit: request
Descrição: Total de requisições HTTP de cliente de token de usuário de saída.

Sem atributos em nível métrico.

agents.user_token_client.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das requisições HTTP do cliente de token de usuário de saída.

Sem atributos em nível métrico.

Métricas de armazenamento em C#

Métricas de armazenamento contam operações de leitura, gravação e exclusão e medem sua duração.

agents.storage.operation.total

Type: Counter
Unit: operation
Descrição: Operações totais de armazenamento realizadas.

Attribute Tipo Description
storage.operation cadeia "read", "write" ou "delete"
agents.storage.operation.duration

Type: Histogram
Unit: ms
Descrição: Duração das operações de armazenamento.

Attribute Tipo Description
storage.operation cadeia "read", "write" ou "delete"

Métricas de autenticação C#

Métricas de autenticação contam as solicitações de tokens e medem sua duração.

agents.auth.token.request.count

Type: Counter
Unit: request
Descrição: Total de solicitações de token feitas ao serviço de autenticação.

Attribute Tipo Description
auth.method cadeia Método de autenticação (ex., "ClientSecret", "Certificate", "obo", "agentic_instance", "agentic_user")
agents.auth.token.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das solicitações de token ao serviço de autenticação.

Attribute Tipo Description
auth.method cadeia Authentication method

Referência às constantes de expansão em C#

Constantes de nomes de varredura são definidas em várias Constants classes no SDK:

Note

As constantes de nome de expansão do SDK são internal, não APIs públicas. A lista a seguir mostra os valores das strings para referência.

// CloudAdapter
"agents.adapter.process"
"agents.adapter.write_response"
"agents.adapter.send_activities"
"agents.adapter.update_activity"
"agents.adapter.delete_activity"
"agents.adapter.continue_conversation"
"agents.adapter.create_connector_client"
"agents.adapter.create_user_token_client"

// AgentApplication
"agents.app.run"
"agents.app.route_handler"
"agents.app.before_turn"
"agents.app.after_turn"
"agents.app.download_files"
"agents.app.typing_indicator"

// TurnContext
"agents.turn.send_activities"

// ConnectorClient
"agents.connector.reply_to_activity"
"agents.connector.send_to_conversation"
"agents.connector.update_activity"
"agents.connector.delete_activity"
"agents.connector.create_conversation"
"agents.connector.get_conversations"
"agents.connector.get_conversation_members"
"agents.connector.upload_attachment"
"agents.connector.get_attachment_info"
"agents.connector.get_attachment"

// UserTokenClient
"agents.user_token_client.get_user_token"
"agents.user_token_client.sign_out"
"agents.user_token_client.get_sign_in_resource"
"agents.user_token_client.exchange_token"
"agents.user_token_client.get_token_or_sign_in_resource"
"agents.user_token_client.get_token_status"
"agents.user_token_client.get_aad_tokens"

// Storage
"agents.storage.read"
"agents.storage.write"
"agents.storage.delete"

// Authentication
"agents.authentication.get_access_token"
"agents.authentication.acquire_token_on_behalf_of"
"agents.authentication.get_agentic_instance_token"
"agents.authentication.get_agentic_user_token"

// Authorization
"agents.authorization.agentic_token"
"agents.authorization.azure_bot_token"
"agents.authorization.azure_bot_signin"
"agents.authorization.azure_bot_signout"

// Proactive
"agents.proactive.store_conversation"
"agents.proactive.get_conversation"
"agents.proactive.delete_conversation"
"agents.proactive.send_activity"
"agents.proactive.continue_conversation"
"agents.proactive.create_conversation"

Referência às constantes de atributo C#

Todas as cadeias de chave de atributos são definidas em Microsoft.Agents.Core.Telemetry.TagNames:

using Microsoft.Agents.Core.Telemetry;

TagNames.ActivityDeliveryMode   // "activity.delivery_mode"
TagNames.ActivityChannelId      // "activity.channel_id"
TagNames.ActivityId             // "activity.id"
TagNames.ActivityName           // "activity.name"
TagNames.ActivityCount          // "activities.count"
TagNames.ActivityType           // "activity.type"
TagNames.AgenticUserId          // "agentic.user_id"
TagNames.AgenticInstanceId      // "agentic.instance_id"
TagNames.AppId                  // "agent.app_id"
TagNames.AttachmentId           // "activity.attachment.id"
TagNames.AttachmentCount        // "activity.attachments.count"
TagNames.AuthHandlerId          // "auth.handler.id"
TagNames.AuthMethod             // "auth.method"
TagNames.AuthScopes             // "auth.scopes"
TagNames.AuthSuccess            // "auth.success"
TagNames.ConversationFound      // "proactive.conversation.found"
TagNames.ConversationId         // "activity.conversation.id"
TagNames.ExchangeConnection     // "auth.connection.name"
TagNames.HttpMethod             // "http.method"
TagNames.HttpStatusCode         // "http.status_code"
TagNames.IsAgentic              // "activity.is_agentic_request"
TagNames.KeyCount               // "storage.keys.count"
TagNames.MembersCount           // "proactive.members.count"
TagNames.Operation              // "operation"
TagNames.RouteAuthorized        // "route.authorized"
TagNames.RouteIsInvoke          // "route.is_invoke"
TagNames.RouteIsAgentic         // "route.is_agentic"
TagNames.RouteMatched           // "route.matched"
TagNames.ServiceUrl             // "service_url"
TagNames.StorageOperation       // "storage.operation"
TagNames.TokenServiceEndpoint   // "agents.token_service.endpoint"
TagNames.UserId                 // "user.id"
TagNames.ViewId                 // "view.id"

Python telemetry

Esta seção documenta os spans e métricas do OpenTelemetry emitidos pelo SDK de Agentes Python (microsoft-agents-hosting-core).

Note

O SDK Python usa strings de chave de atributos diferentes do SDK JavaScript em vários lugares. Diferenças são observadas em cada tabela de ventre e métrica.

Python setup

microsoft-agents-hosting-corerequer Python 3.10 ou posterior, instala opentelemetry-api e opentelemetry-sdk. Instale um exportador para o backend da sua telemetria:

# For exporting to an OTLP collector (Jaeger, Grafana, Azure Monitor, etc.)
pip install opentelemetry-exporter-otlp

Configure os provedores antes que seu agente comece a processar solicitações:

from opentelemetry import metrics, trace
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter

endpoint = "http://localhost:4317/"  # your OTLP collector

resource = Resource.create({
    "service.name": "my-agent",
    "service.version": "1.0.0",
})

# Tracing
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
trace.set_tracer_provider(tracer_provider)

# Metrics
meter_provider = MeterProvider(
    resource=resource,
    metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter(endpoint=endpoint))],
)
metrics.set_meter_provider(meter_provider)

Important

Configure provedores antes de importar módulos SDK como microsoft_agents.hosting.core. O rastreador e o medidor são resolvidos no momento da importação. microsoft_agents.activity não contém telemetria e é seguro importar antes do processo.

O SDK também pode instrumentar o aiohttp servidor, aiohttp cliente e requests bibliotecas por meio de pacotes opcionais de instrumentação OpenTelemetry:

pip install opentelemetry-instrumentation-aiohttp-server
pip install opentelemetry-instrumentation-aiohttp-client
pip install opentelemetry-instrumentation-requests

Saiba mais na configuração de início rápido OpenTelemetry do SDK em Python, que utiliza AioHttpClientInstrumentor e RequestsInstrumentor.

Python spans

Python abrange processamento de requisições de cobertura, execução de turnos, mensagens, armazenamento e operações de autenticação.

Extensões de adaptador Python

O HttpAdapterBase (e suas subclasses nos aiohttp/FastAPI pacotes de hospedagem) emitem spans para cada requisição recebida e atividade de saída.

agents.adapter.process

Principal alcance de processamento. Inserido antes da verificação do método HTTP, então ele dispara para cada chamada para process_request.

Attribute Tipo Description
activity.type cadeia Tipo de atividade (mensagem, invocação, etc.) —definido apenas após análise JSON bem-sucedida
activity.channel_id cadeia Identificador de canal — definido apenas após análise JSON bem-sucedida
activity.delivery_mode cadeia Modo de entrega da atividade
activity.conversation.id cadeia Conversation identifier
activity.is_agentic_request boolean Se isso é um pedido de agente para agente

Note

Os atributos são definidos somente após análise sintática JSON bem-sucedida. Se a análise falhar ou a requisição não for um POST, o tipo de atividade e o canal são padrão para "unknown" métricas in.

agents.adapter.write_response

Emitido para atividades que exigem uma resposta síncrona: invoke atividades e expectReplies modo de entrega.

Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier
agents.adapter.send_activities

Span para enviar uma ou mais atividades pelo adaptador.

Attribute Tipo Description
activities.count inteiro Número de atividades enviadas
activity.conversation.id cadeia Conversation identifier
agents.adapter.update_activity

Span para atualizar uma atividade.

Attribute Tipo Description
activity.id cadeia ID da atividade que está sendo atualizada
activity.conversation.id cadeia Conversation identifier
agents.adapter.delete_activity

Span por excluir uma atividade.

Attribute Tipo Description
activity.id cadeia ID da atividade que está sendo deletada
activity.conversation.id cadeia Conversation identifier
agents.adapter.continue_conversation

Espaço para continuar uma conversa de forma proativa.

Attribute Tipo Description
agent.app_id cadeia O ID da inscrição do agente
activity.conversation.id cadeia Conversation identifier
activity.is_agentic_request boolean Se isso é um pedido agente
agents.adapter.create_connector_client

Span para criar um cliente conector.

Attribute Tipo Description
service_url cadeia URL do serviço Bot Framework
auth.scopes cadeia Escopos de autenticação separados por vírgulas
activity.is_agentic_request boolean Se isso é para um pedido agente
agents.adapter.create_user_token_client

Span para criar um cliente de token de usuário.

Attribute Tipo Description
agents.token_service.endpoint cadeia URL do endpoint do serviço de token
auth.scopes cadeia Escopos de autenticação separados por vírgulas

Agente PythonAplicação Abrange

AgentApplication (o modelo de programação baseado em decorador) emite spans para eventos do ciclo de vida dos turnos.

agents.app.run

A execução principal dura um AgentApplication turno.

Attribute Tipo Description
activity.type cadeia Tipo de atividade em processo
activity.id cadeia Identificador de atividade ("unknown" se não estiver definido)
activity.name cadeia Nome da atividade ("unknown" se não estiver definido)
route.authorized boolean Se a rota foi autorizada; adicionada após a conclusão do roteamento
route.matched boolean Se um manipulador de rota correspondia à atividade; adicionado após a conclusão do roteamento
agents.app.route_handler

Span filho para executar um manipulador de rota pareado.

Attribute Tipo Description
route.is_invoke boolean Se esta é uma rota de atividade de invocação
route.is_agentic boolean Se essa é uma rota agentiva
agents.app.before_turn

Span para execução dos manipuladores antes do turno. Sem atributos adicionais.

agents.app.after_turn

Espaço para execução dos condutores após o turno. Sem atributos adicionais.

agents.app.download_files

Span para baixar anexos de arquivos.

Attribute Tipo Description
activity.attachments.count inteiro Número de anexos (0 quando activity.attachments é nenhum)
agents.app.typing_indicator

Span para enviar um indicador de digitação.

Attribute Tipo Description
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
activity.conversation.id cadeia Identificador de conversa ("unknown" se não for fornecido)

Python proativo abrange

Operações de conversa proativa emitem os seguintes intervalos. As operações de envio e continuação podem incluir um link OpenTelemetry para o contexto do span originado.

agents.proactive.store_conversation
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversa armazenado ("unknown" se vazio)
agents.proactive.get_conversation
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversa solicitado ("unknown" se vazio)
proactive.conversation.found Booleano ou string Se a conversa foi encontrada; "unknown" se o resultado não foi compartilhado com o espaço
agents.proactive.delete_conversation
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversa deletado ("unknown" se vazio)
agents.proactive.send_activity
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversa alvo ("unknown" se vazio)
activity.type cadeia Tipo de atividade ("unknown" se não for fornecido)
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.proactive.continue_conversation
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversa contínua ("unknown" se vazio)
activity.type cadeia Tipo de atividade ("unknown" se não for fornecido)
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.proactive.create_conversation
Attribute Tipo Description
activity.channel_id cadeia Channel identifier
proactive.members.count inteiro ou cadeia de caracteres Número de membros quando disponível

Python TurnContext abrange

TurnContext emite um intervalo quando envia atividades.

agents.turn.send_activities

Emitido a TurnContext cada vez que uma atividade é enviada.

Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier

Conectores de Python Client abrangem

ConnectorClient envolve cada chamada HTTP de saída em um span. O método HTTP e o código de status aparecem apenas em métricas, não no próprio span.

agents.connector.reply_to_activity
Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier
activity.id cadeia A atividade que está sendo respondida
agents.connector.send_to_conversation
Attribute Tipo Description
activity.conversation.id cadeia Identificador de conversação de destino
activity.id cadeia Identificador de atividade, quando fornecido
agents.connector.update_activity
Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier
activity.id cadeia A atividade sendo atualizada
agents.connector.delete_activity
Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier
activity.id cadeia A atividade sendo deletada
agents.connector.create_conversation

Sem atributos de nível de span. Métricas são registradas com operation, http.method, e http.status_code.

agents.connector.get_conversations

Sem atributos de nível de span. Métricas são registradas com operation, http.method, e http.status_code.

agents.connector.get_conversation_members

Sem atributos de nível de span. Métricas são registradas com operation, http.method, e http.status_code.

agents.connector.upload_attachment
Attribute Tipo Description
activity.conversation.id cadeia Conversation identifier
agents.connector.get_attachment_info
Attribute Tipo Description
activity.attachment.id cadeia Attachment identifier
agents.connector.get_attachment
Attribute Tipo Description
activity.attachment.id cadeia Attachment identifier
view.id cadeia View identifier

Armazenamento em Python abrange

Todas as implementações de armazenamento (MemoryStorage, BlobStorage, CosmosDbStorage) emitem esses intervalos.

agents.storage.read
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo lidas
storage.operation cadeia Sempre "read"
agents.storage.write
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo escritas
storage.operation cadeia Sempre "write"
agents.storage.delete
Attribute Tipo Description
storage.keys.count inteiro Número de chaves sendo excluídas
storage.operation cadeia Sempre "delete"

Python UserTokenClient abrange

O método HTTP e o código de status aparecem apenas em métricas, não no próprio span.

agents.user_token_client.get_user_token
Attribute Tipo Description
auth.connection.name cadeia Nome da conexão OAuth
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.user_token_client.sign_out
Attribute Tipo Description
auth.connection.name cadeia Nome da conexão OAuth ("unknown" se Nenhum)
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.user_token_client.get_sign_in_resource

Esse trecho não possui atributos de telemetria fornecidos pelo chamador.

agents.user_token_client.exchange_token
Attribute Tipo Description
auth.connection.name cadeia Nome da conexão OAuth
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.user_token_client.get_token_or_sign_in_resource
Attribute Tipo Description
auth.connection.name cadeia Nome da conexão OAuth
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
agents.user_token_client.get_token_status
Attribute Tipo Description
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)
auth.connection.name cadeia Sempre "unknown"
agents.user_token_client.get_aad_tokens
Attribute Tipo Description
auth.connection.name cadeia Nome da conexão OAuth
user.id cadeia User identifier
activity.channel_id cadeia Identificador de canal ("unknown" se não for fornecido)

A autenticação em Python abrange os padrões

As operações de aquisição de tokens MSAL emitem esses intervalos. Cada intervalo de autenticação também registra métricas de autenticação.

agents.authentication.get_access_token

Span para adquirir um token de acesso.

Attribute Tipo Description
auth.scopes cadeia Escopos de autenticação separados por vírgulas
auth.method cadeia Método de autenticação usado (por exemplo, "secret", "certificate", "managed_identity")
agents.authentication.acquire_token_on_behalf_of

Span para adquirir um token usando o fluxo em nome de Flow.

Attribute Tipo Description
auth.scopes cadeia Escopos de autenticação separados por vírgulas
agents.authentication.get_agentic_instance_token

Span para adquirir um token de instância agente.

Attribute Tipo Description
agentic.instance_id cadeia O ID de instância de aplicação agente
agents.authentication.get_agentic_user_token

Span para adquirir um token de usuário agente.

Attribute Tipo Description
agentic.instance_id cadeia O ID de instância de aplicação agente
agentic.user_id cadeia A ID do usuário agente
auth.scopes cadeia Escopos de autenticação separados por vírgulas

A autorização em Python abrange

Operações de login e token OAuth emitem esses intervalos.

agents.authorization.agentic_token

Span para recuperar um token de autorização agente.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão usado ("unknown" se não for fornecido)
auth.scopes cadeia Escopos de autenticação separados por vírgulas (omitidos se não houver escopos fornecidos)
agents.authorization.azure_bot_token

Span para recuperar um token de autorização Azure Serviço de Bot.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão usado ("unknown" se não for fornecido)
auth.scopes cadeia Escopos de autenticação separados por vírgulas (omitidos se não houver escopos fornecidos)
agents.authorization.azure_bot_signin

Span para o fluxo de Azure Serviço de Bot de login.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão usado ("unknown" se não for fornecido)
auth.scopes cadeia Escopos de autenticação separados por vírgulas (omitidos se não houver escopos fornecidos)
agents.authorization.azure_bot_signout

Span para desconectar um usuário via Azure Serviço de Bot.

Attribute Tipo Description
auth.handler.id cadeia O identificador do manipulador de autorização
auth.connection.name cadeia O nome da conexão ("unknown"—nenhum nome de conexão se aplica à saída de logout)

Python metrics

Métricas Python agregam processamento de atividades, execução de turnos, operações de armazenamento e requisições de saída.

Métricas adaptadoras de Python

Métricas adaptadoras contam atividades e duração do processamento das solicitações de medição.

agents.adapter.process.duration

Type: Histogram
Unit: ms
Descrição: Duração de cada process_request chamada.

Attribute Tipo Description
activity.type cadeia Tipo de atividade ("unknown" se a análise JSON falhou)
activity.channel_id cadeia Channel identifier
agents.activities.received

Type: Counter
Unit: activity

Descrição: Total de atividades recebidas—incrementadas uma vez por process_request chamada, incluindo chamadas não-POST e chamadas com JSON ruim (onde o tipo e o canal são padrão )."unknown"

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
agents.activities.sent

Type: Counter
Unit: activity

Descrição: Total de atividades enviadas.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
agents.activities.updated

Type: Counter
Unit: activity

Descrição: Atualizações totais de atividade.

Attribute Tipo Description
activity.channel_id cadeia Channel identifier
agents.activities.deleted

Type: Counter
Unit: activity

Descrição: Eliminações totais de atividade.

Attribute Tipo Description
activity.channel_id cadeia Channel identifier

Métricas de curva em Python

As métricas de turno acompanham as curvas bem-sucedidas, as curvas fracassadas e a duração de ponta a ponta.

agents.turn.count

Type: Counter
Unit: turn
Descrição: Total de turnos bem-sucedidos (sem exceção).

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
activity.conversation.id cadeia Conversation identifier
success boolean Sempre True para essa métrica
agents.turn.error.count

Type: Counter
Unit: turn
Descrição: Total de turnos que geraram uma exceção.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
activity.conversation.id cadeia Conversation identifier
success boolean Sempre False para essa métrica
agents.turn.duration

Type: Histogram
Unit: ms
Descrição: Duração do turno de ponta a ponta. Registrado tanto em caminhos de sucesso quanto de erro.

Attribute Tipo Description
activity.type cadeia Activity type
activity.channel_id cadeia Channel identifier
activity.conversation.id cadeia Conversation identifier
success boolean Se o turno foi concluído sem erro

Métricas de armazenamento em Python

Métricas de armazenamento contam operações de leitura, gravação e exclusão e medem sua duração.

agents.storage.operation.total

Type: Counter
Unit: operation
Descrição: Operações totais de armazenamento. O SDK C# também emite essa métrica; o SDK JavaScript não.

Attribute Tipo Description
storage.operation cadeia "read", "write" ou "delete"
agents.storage.operation.duration

Type: Histogram
Unit: ms
Descrição: Duração das operações de armazenamento.

Attribute Tipo Description
storage.operation cadeia "read", "write" ou "delete"

Métricas de conector Python

Métricas de conectores contam as solicitações HTTP de saída e medem sua duração.

agents.connector.request.count

Type: Counter
Unit: request
Descrição: Total de requisições HTTP de saída do conector.

Attribute Tipo Description
operation cadeia Nome de expansão da operação (por exemplo) "agents.connector.reply_to_activity"
http.method cadeia Método HTTP — presente apenas quando a resposta HTTP está disponível
http.status_code inteiro Código de status HTTP — presente apenas quando a resposta HTTP está disponível
agents.connector.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das requisições HTTP de conectores de saída.

Attribute Tipo Description
operation cadeia Nome do vão da operação
http.method cadeia Método HTTP — presente apenas quando a resposta HTTP está disponível
http.status_code inteiro Código de status HTTP — presente apenas quando a resposta HTTP está disponível

Métricas Python UserTokenClient

As métricas de cliente token de usuário contam as requisições HTTP e medem sua duração.

agents.user_token_client.request.count

Type: Counter
Unit: request
Descrição: Total de requisições HTTP do cliente de token de usuário.

Attribute Tipo Description
operation cadeia Nome de expansão da operação (por exemplo) "agents.user_token_client.get_user_token"
http.method cadeia Método HTTP — presente apenas quando a resposta HTTP está disponível
http.status_code inteiro Código de status HTTP — presente apenas quando a resposta HTTP está disponível
agents.user_token_client.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das requisições HTTP do cliente de token de usuário.

Attribute Tipo Description
operation cadeia Nome do vão da operação
http.method cadeia Método HTTP — presente apenas quando a resposta HTTP está disponível
http.status_code inteiro Código de status HTTP — presente apenas quando a resposta HTTP está disponível

Métricas de autenticação em Python

Métricas de autenticação contam as solicitações de tokens e medem sua duração.

agents.auth.token.request.count

Type: Counter
Unit: request
Descrição: Solicitações totais de tokens de autenticação feitas pelo SDK.

Attribute Tipo Description
auth.method cadeia Método de autenticação usado (por exemplo, "secret", "certificate", "obo", "agentic_instance", "agentic_user")
auth.success boolean Se a solicitação do token foi bem-sucedida
agents.auth.token.request.duration

Type: Histogram
Unit: ms
Descrição: Duração das solicitações de token de autenticação.

Attribute Tipo Description
auth.method cadeia Método de autenticação utilizado
auth.success boolean Se a solicitação do token foi bem-sucedida

Filter Python abrange

Para suprimir intervalos específicos na produção, use um sampler OpenTelemetry. Um sampler recebe o nome do span antes que o span seja gravado e pode retornar DROP para evitar gravar e exportar esse span.

from opentelemetry.sdk.trace.sampling import (
    Decision,
    ParentBased,
    Sampler,
    SamplingResult,
    TraceIdRatioBased,
)

SUPPRESSED_SPANS = frozenset(
    {
        "agents.storage.read",
        "agents.storage.write",
        "agents.storage.delete",
    }
)

class SpanFilterSampler(Sampler):
    def __init__(self, delegate: Sampler) -> None:
        self._delegate = delegate

    def should_sample(
        self,
        parent_context,
        trace_id,
        name,
        kind=None,
        attributes=None,
        links=None,
        trace_state=None,
    ):
        if name in SUPPRESSED_SPANS:
            return SamplingResult(Decision.DROP)

        return self._delegate.should_sample(
            parent_context=parent_context,
            trace_id=trace_id,
            name=name,
            kind=kind,
            attributes=attributes,
            links=links,
            trace_state=trace_state,
        )

    def get_description(self):
        return f"SpanFilterSampler({self._delegate.get_description()})"

sampler = SpanFilterSampler(
    ParentBased(root=TraceIdRatioBased(0.1))
)

No exemplo da configuração em Python, substitua TracerProvider(resource=resource) por TracerProvider(resource=resource, sampler=sampler). Mantenha o mesmo recurso e processador de span. Não registre um segundo provedor.

Importar constantes do SDK antes da configuração do provedor pode inicializar o rastreador do SDK muito cedo, então use nomes literais de span no código bootstrap do provedor.

Tratamento de erros em Python em spans

Todos os spans de SDK lidam automaticamente com erros. Quando uma exceção se propaga a partir de uma operação rastreada:

  1. O status de expansão está definido como ERROR.
  2. A exceção é registrada no vão via span.record_exception().
  3. A exceção é re-levantada — ela nunca é engolida pela camada de telemetria.

Na saída limpa, o status do vão é definido para OK.

Referência de constantes de abrangência em Python

Constantes de nomes de varredura são definidas em vários módulos em microsoft_agents.hosting.core:

from microsoft_agents.hosting.core.telemetry.adapter import constants as adapter_constants
from microsoft_agents.hosting.core.app.telemetry import constants as app_constants
from microsoft_agents.hosting.core.app.proactive.telemetry import constants as proactive_constants
from microsoft_agents.hosting.core.connector.telemetry import constants as connector_constants
from microsoft_agents.hosting.core.storage.telemetry import constants as storage_constants
from microsoft_agents.hosting.core.telemetry.turn_context import constants as turn_context_constants
from microsoft_agents.hosting.core.authorization.telemetry import constants as auth_constants
from microsoft_agents.hosting.core.app.oauth.telemetry import constants as oauth_constants

# Adapter
adapter_constants.SPAN_PROCESS                    # 'agents.adapter.process'
adapter_constants.SPAN_SEND_ACTIVITIES            # 'agents.adapter.send_activities'
adapter_constants.SPAN_UPDATE_ACTIVITY            # 'agents.adapter.update_activity'
adapter_constants.SPAN_DELETE_ACTIVITY            # 'agents.adapter.delete_activity'
adapter_constants.SPAN_CONTINUE_CONVERSATION      # 'agents.adapter.continue_conversation'
adapter_constants.SPAN_CREATE_CONNECTOR_CLIENT    # 'agents.adapter.create_connector_client'
adapter_constants.SPAN_CREATE_USER_TOKEN_CLIENT   # 'agents.adapter.create_user_token_client'
adapter_constants.SPAN_WRITE_RESPONSE             # 'agents.adapter.write_response'

# AgentApplication
app_constants.SPAN_ON_TURN                        # 'agents.app.run'
app_constants.SPAN_ROUTE_HANDLER                  # 'agents.app.route_handler'
app_constants.SPAN_BEFORE_TURN                    # 'agents.app.before_turn'
app_constants.SPAN_AFTER_TURN                     # 'agents.app.after_turn'
app_constants.SPAN_DOWNLOAD_FILES                 # 'agents.app.download_files'
app_constants.SPAN_SEND_TYPING                     # 'agents.app.typing_indicator'

# Proactive
proactive_constants.SPAN_STORE_CONVERSATION       # 'agents.proactive.store_conversation'
proactive_constants.SPAN_GET_CONVERSATION         # 'agents.proactive.get_conversation'
proactive_constants.SPAN_DELETE_CONVERSATION      # 'agents.proactive.delete_conversation'
proactive_constants.SPAN_SEND_ACTIVITY            # 'agents.proactive.send_activity'
proactive_constants.SPAN_CONTINUE_CONVERSATION    # 'agents.proactive.continue_conversation'
proactive_constants.SPAN_CREATE_CONVERSATION      # 'agents.proactive.create_conversation'

# TurnContext
turn_context_constants.SPAN_TURN_SEND_ACTIVITIES  # 'agents.turn.send_activities'

# ConnectorClient
connector_constants.SPAN_REPLY_TO_ACTIVITY        # 'agents.connector.reply_to_activity'
connector_constants.SPAN_SEND_TO_CONVERSATION     # 'agents.connector.send_to_conversation'
connector_constants.SPAN_UPDATE_ACTIVITY          # 'agents.connector.update_activity'
connector_constants.SPAN_DELETE_ACTIVITY          # 'agents.connector.delete_activity'
connector_constants.SPAN_CREATE_CONVERSATION      # 'agents.connector.create_conversation'
connector_constants.SPAN_GET_CONVERSATIONS        # 'agents.connector.get_conversations'
connector_constants.SPAN_GET_CONVERSATION_MEMBERS # 'agents.connector.get_conversation_members'
connector_constants.SPAN_UPLOAD_ATTACHMENT        # 'agents.connector.upload_attachment'
connector_constants.SPAN_GET_ATTACHMENT           # 'agents.connector.get_attachment'
connector_constants.SPAN_GET_ATTACHMENT_INFO      # 'agents.connector.get_attachment_info'

# Storage
storage_constants.SPAN_STORAGE_READ               # 'agents.storage.read'
storage_constants.SPAN_STORAGE_WRITE              # 'agents.storage.write'
storage_constants.SPAN_STORAGE_DELETE             # 'agents.storage.delete'

# Authentication
auth_constants.SPAN_GET_ACCESS_TOKEN              # 'agents.authentication.get_access_token'
auth_constants.SPAN_ACQUIRE_TOKEN_ON_BEHALF_OF    # 'agents.authentication.acquire_token_on_behalf_of'
auth_constants.SPAN_GET_AGENTIC_INSTANCE_TOKEN    # 'agents.authentication.get_agentic_instance_token'
auth_constants.SPAN_GET_AGENTIC_USER_TOKEN        # 'agents.authentication.get_agentic_user_token'

# Authorization
oauth_constants.AGENTIC_TOKEN                     # 'agents.authorization.agentic_token'
oauth_constants.AZURE_BOT_TOKEN                   # 'agents.authorization.azure_bot_token'
oauth_constants.AZURE_BOT_SIGN_IN                 # 'agents.authorization.azure_bot_signin'
oauth_constants.AZURE_BOT_SIGN_OUT                # 'agents.authorization.azure_bot_signout'

# UserTokenClient
connector_constants.SPAN_GET_USER_TOKEN                  # 'agents.user_token_client.get_user_token'
connector_constants.SPAN_SIGN_OUT                        # 'agents.user_token_client.sign_out'
connector_constants.SPAN_GET_SIGN_IN_RESOURCE             # 'agents.user_token_client.get_sign_in_resource'
connector_constants.SPAN_EXCHANGE_TOKEN                  # 'agents.user_token_client.exchange_token'
connector_constants.SPAN_GET_TOKEN_OR_SIGN_IN_RESOURCE   # 'agents.user_token_client.get_token_or_sign_in_resource'
connector_constants.SPAN_GET_TOKEN_STATUS                # 'agents.user_token_client.get_token_status'
connector_constants.SPAN_GET_AAD_TOKENS                  # 'agents.user_token_client.get_aad_tokens'

Referência de constantes métricas em Python

Constantes de nomes métricos identificam contadores e histogramas nos módulos correspondentes:

from microsoft_agents.hosting.core.telemetry.adapter import constants as adapter_constants
from microsoft_agents.hosting.core.app.telemetry import constants as app_constants
from microsoft_agents.hosting.core.connector.telemetry import constants as connector_constants
from microsoft_agents.hosting.core.storage.telemetry import constants as storage_constants
from microsoft_agents.hosting.core.authorization.telemetry import constants as auth_constants

# Adapter
adapter_constants.METRIC_ADAPTER_PROCESS_DURATION  # 'agents.adapter.process.duration'
adapter_constants.METRIC_ACTIVITIES_RECEIVED        # 'agents.activities.received'
adapter_constants.METRIC_ACTIVITIES_SENT            # 'agents.activities.sent'
adapter_constants.METRIC_ACTIVITIES_UPDATED         # 'agents.activities.updated'
adapter_constants.METRIC_ACTIVITIES_DELETED         # 'agents.activities.deleted'

# Turn
app_constants.METRIC_TURN_COUNT                     # 'agents.turn.count'
app_constants.METRIC_TURN_ERROR_COUNT               # 'agents.turn.error.count'
app_constants.METRIC_TURN_DURATION                  # 'agents.turn.duration'

# Storage
storage_constants.METRIC_STORAGE_OPERATION_TOTAL    # 'agents.storage.operation.total'
storage_constants.METRIC_STORAGE_OPERATION_DURATION # 'agents.storage.operation.duration'

# Connector
connector_constants.METRIC_CONNECTOR_REQUEST_COUNT          # 'agents.connector.request.count'
connector_constants.METRIC_CONNECTOR_REQUEST_DURATION       # 'agents.connector.request.duration'

# UserTokenClient
connector_constants.METRIC_USER_TOKEN_CLIENT_REQUEST_COUNT      # 'agents.user_token_client.request.count'
connector_constants.METRIC_USER_TOKEN_CLIENT_REQUEST_DURATION   # 'agents.user_token_client.request.duration'

# Authentication
auth_constants.METRIC_AUTH_TOKEN_REQUEST_COUNT      # 'agents.auth.token.request.count'
auth_constants.METRIC_AUTH_TOKEN_REQUEST_DURATION   # 'agents.auth.token.request.duration'

Atributos de intervalo comuns

Esses atributos aparecem em múltiplos intervalos e seguem as convenções semânticas da OpenTelemetry quando aplicável. Nomes e tipos de atributos podem variar de acordo com o SDK. As variantes de C# e Python são indicadas abaixo.

Attribute Tipo Description
activity.type cadeia Tipo de atividade do Bot Framework (mensagem, conversaAtualização, invocação, etc.)
activity.id cadeia Identificador único para a atividade
activity.name cadeia Nome da atividade (C# e Python)
activity.channel_id cadeia Identificador de canal (msteams, webchat, directline, etc.)
activity.conversation_id cadeia Identificador único para a conversa; C# e Python usamactivity.conversation.id
activity.is_agentic boolean Se esta é uma solicitação agentical (agente-para-agente); C# e Python usamactivity.is_agentic_request
activity.delivery_mode cadeia O modo de entrega da atividade
auth.scope cadeia Escopo de autenticação para requisições de token (apenas JavaScript)
auth.scopes string[] ou string Escopos de autenticação; JavaScript grava um array, enquanto C# e Python registram uma string separada por vírgulas
auth.method cadeia Método de autenticação utilizado; C# get_access_token usa AuthTypes valores de enum, enquanto outras operações de autenticação em C# usam "obo", "agentic_instance", ou "agentic_user"
auth.connection.name cadeia O nome da conexão OAuth
auth.handler.id cadeia O identificador do manipulador de autorização
error.type cadeia Nome da classe de exceção ou erro quando ocorre um erro (apenas JavaScript; C# e Python usam um exception evento com exception.type)
http.method cadeia Método HTTP para requisições de saída (não emitidas por C#)
http.status_code cadeia de caracteres ou inteiro código de status de resposta HTTP; não emitido por C#. JavaScript grava uma string, e Python registra um inteiro.
user.id cadeia O identificador do usuário

Referência do tipo de vão

O OpenTelemetry é usado SpanKind para categorizar intervalos. Os SDK documentados neste artigo são usados INTERNAL em JavaScript, C# e Python. Os outros tipos na tabela a seguir descrevem categorias de OpenTelemetry, não tipos emitidos por esses spans de SDK.

Variante Value Usage
INTERNAL 0 Operações internas dentro do SDK
SERVER 1 Gerenciando solicitações recebidas
CLIENT 2 Fazendo chamadas de saída
PRODUCER 3 Produzir mensagens para um corretor
CONSUMER 4 Consumindo mensagens de um corretor