Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.
JavaScript
- Setup
-
Traces (spans)
- CloudAdapter spans
- AgentApplication spans
- TurnContext spans
- ConnectorClient spans
- AgentClient spans
- Proactive spans
- Storage spans
- Authentication spans
- Authorization spans
- UserTokenClient spans
- Dialog spans
- O cliente do Copilot Studio abrange
- Vãos de tubos nomeados
- Slack spans
- Tratamento de erros em vãos
- Filtros abrangem com um sampler baseado em pais
- Metrics
- Referência de constantes de expansão
- Referência de constantes métricas
- Log records
C#
Python
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: Incluiroute.is_invokeeroute.is_agenticatributos -
agents.app.download_files: Inclui oagents.attachments.countatributo -
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:
- O status do espanto é definido para
ERRORcom a mensagem de erro - A exceção é registrada no vão via
recordException() - O gancho final específico da definição do vão é perfeito e pode inspecionar o erro
- 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.Activityobjetos criados a partir de um .ActivitySource - Métricas são
Counter<T>eHistogram<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:
- O status do espanto é definido como
Errorcom a mensagem de exceção. - Um evento é adicionado às
System.Diagnostics.Activitytags comexception.type,exception.message, eexception.stacktraceseguindo as convenções semânticasexceptiondo 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:
- O status de expansão está definido como
ERROR. - A exceção é registrada no vão via
span.record_exception(). - 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 |