Compartilhar via

@microsoft/agents-a365-observability package

Classes

Agent365ExporterOptions

Número máximo de intervalos por lote de exportação.
BaggageBuilder

Construtor de bagagem por solicitação para propagação de contexto OpenTelemetry.

Essa classe fornece uma API fluente para definir valores de bagagem que serão propagados no contexto OpenTelemetry.

Exemplo

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context
BaggageScope

Gerenciador de contexto para escopo de bagagem.

Essa classe gerencia o ciclo de vida dos valores de bagagem, definindo-os no enter e restaurando o contexto anterior na saída.
Builder

Construtor para configurar o Agente 365 com rastreamento OpenTelemetry
ExecuteToolScope

Fornece o escopo de rastreamento opentelemetry para operações de execução de ferramentas de IA.
InferenceScope

Fornece o escopo de rastreamento opentelemetry para operações de inferência de IA generativas.
InvokeAgentScope

Fornece o escopo de rastreamento opentelemetry para operações de invocação de agente de IA.
ObservabilityConfiguration

Configuração do pacote de observabilidade. Herda configurações de runtime e adiciona configurações específicas de observabilidade.
ObservabilityManager

Ponto de entrada principal para o Agente 365 fornecendo o rastreamento OpenTelemetry para agentes e ferramentas de IA
OpenTelemetryConstants

Constantes OpenTelemetry para o Agente 365
OpenTelemetryScope

Classe base para escopos de rastreamento opentelemetry
OutputScope

Fornece o escopo de rastreamento opentelemetry para rastreamento de mensagens de saída com vinculação de intervalo pai.
PerRequestSpanProcessorConfiguration

Configuração para PerRequestSpanProcessor. Herda as configurações de runtime (clusterCategory, isNodeEnvDevelopment) e adiciona guardrails de processador por solicitação.

Isso é separado de ObservabilityConfiguration porque PerRequestSpanProcessor é usado apenas em cenários específicos e essas configurações não devem ser expostas na ObservabilityConfiguration comum.

Interfaces

AgentDetails

Detalhes sobre um agente de IA
BlobPart

Dados binários embutidos (codificados em base64).
BuilderOptions

Opções de configuração para o Construtor de Observabilidade do Agent 365
CallerDetails

Detalhes do chamador para criação de escopo. Dá suporte a chamadores humanos, chamadores de agente ou ambos (A2A com um humano na cadeia).

Observação de migração: Na v1, o nome CallerDetails se referia à identidade do chamador humano (agora UserDetails). Na v2, ele foi reaproveitado como um wrapper que agrupa informações de chamadas humanas e de agente.

Consulte UserDetails — identidade do chamador humano (anteriormente CallerDetails) Consulte CHANGELOG.md — seção de alterações interruptivas para obter diretrizes de migração
Channel

Representa o canal para uma invocação
ChatMessage

Uma mensagem de entrada enviada a um modelo (convenções semânticas OTEL gen-ai).
FilePart

Referência a um arquivo pré-carregado.
GenericPart

Parte extensível para tipos personalizados/futuros.
GenericServerToolCall

Detalhes da chamada da ferramenta de servidor extensível com um tipo discriminatório.
GenericServerToolCallResponse

Resposta de chamada de ferramenta de servidor extensível com um tipo discriminatório.
ILogger

Interface do agente personalizado para a observabilidade do Agent 365 Implemente essa interface para dar suporte a back-ends de log
InferenceDetails

Detalhes de uma chamada de inferência
InferenceResponse

Detalhes para gravar a resposta de uma chamada de inferência
InputMessages
InvokeAgentScopeDetails

Detalhes para invocar o escopo do agente.
OutputMessage

Uma mensagem de saída produzida por um modelo (convenções semânticas OTEL gen-ai).
OutputMessages
OutputResponse

Representa uma resposta que contém mensagens de saída de um agente. Usado com OutputScope para rastreamento de mensagem de saída. Aceita cadeias de caracteres simples, objetos OTEL OutputMessage estruturados ou um ditado bruto (tratado como um resultado de chamada de ferramenta por especificação OTEL).
ParentSpanRef

Referência a um intervalo pai para vinculação pai-filho explícita entre limites assíncronos. Usado quando a propagação automática de contexto falha (por exemplo, retornos de chamada webSocket, manipuladores de eventos externos).
ReasoningPart

Raciocínio de modelo/conteúdo de cadeia de pensamento.
Request

Representa uma solicitação com contexto de telemetria. Usado em todos os tipos de escopo para acompanhamento de canal e conversa.
ServerToolCallPart

Invocação de ferramenta do lado do servidor.
ServerToolCallResponsePart

Resposta da ferramenta do lado do servidor.
ServiceEndpoint

Representa um ponto de extremidade para invocação de agente
SpanDetails

Abra os detalhes de configuração para a criação do escopo. Agrupa opções de extensão OpenTelemetry em um único objeto para que a assinatura do método de escopo permaneça estável à medida que novas opções são adicionadas.
TextPart

Conteúdo de texto sem formatação.
ToolCallDetails

Detalhes de uma chamada de ferramenta feita por um agente
ToolCallRequestPart

Uma chamada de ferramenta solicitada pelo modelo.
ToolCallResponsePart

Resultado de uma chamada de ferramenta.
UriPart

Referência de URI externo.
UserDetails

Detalhes sobre o chamador de usuário humano.

Aliases de tipo

EnhancedAgentDetails
HeadersCarrier

Tipo de operadora para cabeçalhos HTTP usados na propagação de contexto de rastreamento. Compatível com Node.js IncomingHttpHeaders e mapas de cadeia de caracteres simples.
InputMessagesParam

Entrada aceita para recordInputMessages. Dá suporte a uma única cadeia de caracteres, uma matriz de cadeias de caracteres (compatibilidade com versões anteriores) ou o wrapper com versão.
MessagePart

União de todos os tipos de parte de mensagem por convenções semânticas OTEL gen-ai.

Observação: GenericPart atua como um catch-all para compatibilidade futura com tipos de parte personalizados ou futuros. type Como ele é (não um string literal), o esgotamento part.typeswitch/case não produzirá erros de tempo de compilação para casos sem tratamento.
ObservabilityConfigurationOptions

Opções de configuração de observabilidade – estende as opções de runtime. Todas as substituições são funções chamadas em cada acesso à propriedade.

Herdado de RuntimeConfigurationOptions:

  • clusterCategory
  • isNodeEnvDevelopment

Observação: isDevelopmentEnvironment é um getter derivado na classe de configuração (com base em clusterCategory), não uma opção substituível.
OutputMessagesParam

Entrada aceita para recordOutputMessages. Dá suporte a uma única cadeia de caracteres, uma matriz de cadeias de caracteres (compatibilidade com versões anteriores) ou o wrapper com versão.
ParentContext

Um contexto pai para a criação de intervalo. Aceita um:
PerRequestSpanProcessorConfigurationOptions

Opções de configuração para PerRequestSpanProcessor – estende as opções de runtime. Todas as substituições são funções chamadas em cada acesso à propriedade.

Herdado de RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Entrada aceita para OutputResponse.messages. Dá suporte a cadeias de caracteres simples, OutputMessages estruturadas ou um ditado bruto (tratado como um resultado de chamada de ferramenta por especificação OTEL e serializado diretamente por JSON.stringify).

Enumerações

ExporterEventNames

Nomes de eventos usados pelo Agent365Exporter para registro em log e monitoramento. Esses são tipos de evento de baixa cardinalidade para garantir o monitoramento e a agregação eficientes.
FinishReason

Motivo pelo qual um modelo parou de gerar por convenções semânticas OTEL gen-ai.
InferenceOperationType

Representa uma operação diferente para tipos de inferência de modelo
InvocationRole

Representa funções diferentes que podem invocar um agente
MessageRole

Função de um participante de mensagem por convenções semânticas OTEL gen-ai.
Modality

Modalidade de mídia para blob, arquivo e partes de URI.

Funções

createContextWithParentSpanRef(Context, ParentSpanRef)

Cria um novo contexto com uma referência de intervalo pai explícita. Isso permite que os intervalos filho sejam paiizados corretamente mesmo quando o contexto assíncrono é interrompido.
extractContextFromHeaders(HeadersCarrier, Context)

Extrai o contexto de rastreamento de cabeçalhos HTTP de entrada usando o propagador W3C registrado globalmente. Retorna um OTel ParentContext que pode ser passado para classes de escopo como um ParentContext.

Exemplo

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
formatError(unknown)

Formatar objeto de erro para registro em log com rastreamento de mensagens e pilhas
getExportToken(Context)

Recupere o token de exportação por solicitação de um determinado Contexto OTel (ou o ativo).
getLogger()

Obter a instância atual do agente
injectContextToHeaders(Record<string, string>, Context)

Injeta o contexto de rastreamento atual (traceparent/tracestate cabeçalhos) no objeto de cabeçalhos fornecido usando o propagador W3C registrado globalmente.

Exemplo

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });
isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Verifique se a exportação por solicitação está habilitada. Precedência: substitui interna variável > de ambiente do provedor > de configuração. Quando habilitado, o PerRequestSpanProcessor é usado em vez de BatchSpanProcessor. O token é passado por meio do Contexto OTel (armazenamento local assíncrono) no momento da exportação.
normalizeInputMessages(InputMessagesParam)

Normaliza um InputMessagesParam wrapper com versão InputMessages .

  • string / string[] → convertido ChatMessage[] e encapsulado
  • InputMessages → retornado as-is
normalizeOutputMessages(OutputMessagesParam)

Normaliza um OutputMessagesParam wrapper com versão OutputMessages .

  • string / string[] → convertido OutputMessage[] e encapsulado
  • OutputMessages → retornado as-is
resetLogger()

Redefinir para o agente de console padrão (principalmente para teste)
runWithExportToken<T>(string, () => T)

Execute uma função em um contexto que carrega o token de exportação por solicitação. Isso mantém o token somente no CONTEXTO OTel (ALS), nunca em nenhum registro.

O token pode ser atualizado posteriormente antes updateExportToken() que o rastreamento seja liberado , útil quando o retorno de chamada é de execução prolongada e o token original pode expirar antes da exportação.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Extrai o contexto de rastreamento de cabeçalhos HTTP de entrada e executa o retorno de chamada dentro desse contexto. Todos os intervalos criados dentro do retorno de chamada serão pai do rastreamento extraído.

Exemplo

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});
runWithParentSpanRef<T>(ParentSpanRef, () => T)

Executa uma função de retorno de chamada em um contexto que tem uma referência de intervalo pai explícita. Isso é útil para criar intervalos filho em retornos de chamada assíncronos em que a propagação de contexto é interrompida.
safeSerializeToJson(string | Record<string, unknown>, string)

Garante que o valor seja sempre uma cadeia de caracteres parseável JSON.

  • Os objetos são serializados por meio de JSON.stringify.
  • Cadeias de caracteres que já são objetos/matrizes JSON válidos são passadas.
  • Todas as outras cadeias de caracteres (incluindo primitivos JSON nus) são encapsuladas: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Serializa um wrapper de mensagem com versão para JSON.

A saída é o objeto wrapper completo: {"version":"0.1.0","messages":[...]}.

A tentativa/captura garante que a gravação de telemetria não seja gerada mesmo quando partes de mensagem contêm valores não serializáveis JSON (por exemplo, BigInt, refs circulares).
setLogger(ILogger)

Definir uma implementação de agente personalizado para o SDK de observabilidade

Exemplo com Winston:

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});
truncateValue(string)

Trunque um valor de cadeia de caracteres para MAX_ATTRIBUTE_LENGTH caracteres. Se o valor exceder o limite, ele será cortado e um sufixo de truncamento será acrescentado, com o comprimento total limitado exatamente MAX_ATTRIBUTE_LENGTH.
updateExportToken(string)

Atualize o token de exportação no Contexto OTel ativo. Chame isso para atualizar o token antes de encerrar o intervalo raiz quando o token original pode ter expirado durante uma solicitação de execução longa.

Deve ser chamado dentro do mesmo contexto assíncrono criado por runWithExportToken.

Variáveis

A365_MESSAGE_SCHEMA_VERSION
MAX_ATTRIBUTE_LENGTH

Comprimento máximo para valores de atributo de intervalo. Valores que excedem esse limite serão truncados com um sufixo.
defaultObservabilityConfigurationProvider

Provedor padrão compartilhado para ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Provedor padrão compartilhado para PerRequestSpanProcessorConfiguration.
logger

Instância do agente padrão para compatibilidade com versões anteriores. Delega ao agente global que pode ser substituído por meio de setLogger().

Detalhes da função

createContextWithParentSpanRef(Context, ParentSpanRef)

Cria um novo contexto com uma referência de intervalo pai explícita. Isso permite que os intervalos filho sejam paiizados corretamente mesmo quando o contexto assíncrono é interrompido.

function createContextWithParentSpanRef(base: Context, parent: ParentSpanRef): Context

Parâmetros

base

Context

O contexto base a ser estendido (normalmente context.active())

parent
ParentSpanRef

A referência de intervalo pai que contém traceId e spanId

Retornos

Context

Um novo contexto com o conjunto de intervalo pai

extractContextFromHeaders(HeadersCarrier, Context)

Extrai o contexto de rastreamento de cabeçalhos HTTP de entrada usando o propagador W3C registrado globalmente. Retorna um OTel ParentContext que pode ser passado para classes de escopo como um ParentContext.

Exemplo

const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });

function extractContextFromHeaders(headers: HeadersCarrier, baseCtx?: Context): Context

Parâmetros

headers
HeadersCarrier

Os cabeçalhos de solicitação HTTP de entrada que contêm traceparent/tracestate.

baseCtx

Context

Contexto base opcional a ser estendido. O padrão é o contexto ativo.

Retornos

Context

Um contexto OTel que contém as informações de rastreamento extraídas.

formatError(unknown)

Formatar objeto de erro para registro em log com rastreamento de mensagens e pilhas

function formatError(error: unknown): string

Parâmetros

error

unknown

Retornos

string

getExportToken(Context)

Recupere o token de exportação por solicitação de um determinado Contexto OTel (ou o ativo).

function getExportToken(ctx?: Context): string | undefined

Parâmetros

ctx

Context

Retornos

string | undefined

getLogger()

Obter a instância atual do agente

function getLogger(): ILogger

Retornos

ILogger

injectContextToHeaders(Record<string, string>, Context)

Injeta o contexto de rastreamento atual (traceparent/tracestate cabeçalhos) no objeto de cabeçalhos fornecido usando o propagador W3C registrado globalmente.

Exemplo

const headers: Record<string, string> = {};
injectContextToHeaders(headers);
await fetch('http://service-b/process', { headers });

function injectContextToHeaders(headers: Record<string, string>, ctx?: Context): Record<string, string>

Parâmetros

headers

Record<string, string>

Objeto mutável em que os cabeçalhos de contexto de rastreamento serão gravados.

ctx

Context

Contexto OTel opcional do qual injetar. O padrão é o contexto ativo.

Retornos

Record<string, string>

O mesmo headers objeto, para a conveniência de encadeamento.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Verifique se a exportação por solicitação está habilitada. Precedência: substitui interna variável > de ambiente do provedor > de configuração. Quando habilitado, o PerRequestSpanProcessor é usado em vez de BatchSpanProcessor. O token é passado por meio do Contexto OTel (armazenamento local assíncrono) no momento da exportação.

function isPerRequestExportEnabled(configProvider?: IConfigurationProvider<PerRequestSpanProcessorConfiguration>): boolean

Parâmetros

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Provedor de configuração opcional. O padrão é DefaultPerRequestSpanProcessorConfigurationProvider se não for especificado.

Retornos

boolean

normalizeInputMessages(InputMessagesParam)

Normaliza um InputMessagesParam wrapper com versão InputMessages .

  • string / string[] → convertido ChatMessage[] e encapsulado
  • InputMessages → retornado as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages

Parâmetros

param
InputMessagesParam

Retornos

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Normaliza um OutputMessagesParam wrapper com versão OutputMessages .

  • string / string[] → convertido OutputMessage[] e encapsulado
  • OutputMessages → retornado as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

Parâmetros

param
OutputMessagesParam

Retornos

OutputMessages

resetLogger()

Redefinir para o agente de console padrão (principalmente para teste)

function resetLogger()

runWithExportToken<T>(string, () => T)

Execute uma função em um contexto que carrega o token de exportação por solicitação. Isso mantém o token somente no CONTEXTO OTel (ALS), nunca em nenhum registro.

O token pode ser atualizado posteriormente antes updateExportToken() que o rastreamento seja liberado , útil quando o retorno de chamada é de execução prolongada e o token original pode expirar antes da exportação.

function runWithExportToken<T>(token: string, fn: () => T): T

Parâmetros

token

string

fn

() => T

Retornos

T

runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Extrai o contexto de rastreamento de cabeçalhos HTTP de entrada e executa o retorno de chamada dentro desse contexto. Todos os intervalos criados dentro do retorno de chamada serão pai do rastreamento extraído.

Exemplo

runWithExtractedTraceContext(req.headers, () => {
  const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  scope.dispose();
});

function runWithExtractedTraceContext<T>(headers: HeadersCarrier, callback: () => T): T

Parâmetros

headers
HeadersCarrier

Os cabeçalhos de solicitação HTTP de entrada que contêm traceparent/tracestate.

callback

() => T

A função a ser executada dentro do contexto extraído.

Retornos

T

O resultado do retorno de chamada.

runWithParentSpanRef<T>(ParentSpanRef, () => T)

Executa uma função de retorno de chamada em um contexto que tem uma referência de intervalo pai explícita. Isso é útil para criar intervalos filho em retornos de chamada assíncronos em que a propagação de contexto é interrompida.

function runWithParentSpanRef<T>(parent: ParentSpanRef, callback: () => T): T

Parâmetros

parent
ParentSpanRef

A referência de intervalo pai

callback

() => T

A função a ser executada com o contexto pai

Retornos

T

O resultado do retorno de chamada

safeSerializeToJson(string | Record<string, unknown>, string)

Garante que o valor seja sempre uma cadeia de caracteres parseável JSON.

  • Os objetos são serializados por meio de JSON.stringify.
  • Cadeias de caracteres que já são objetos/matrizes JSON válidos são passadas.
  • Todas as outras cadeias de caracteres (incluindo primitivos JSON nus) são encapsuladas: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Parâmetros

value

string | Record<string, unknown>

O valor a ser serializado.

key

string

A chave a ser usada ao encapsular uma cadeia de caracteres simples.

Retornos

string

serializeMessages(InputMessages | OutputMessages)

Serializa um wrapper de mensagem com versão para JSON.

A saída é o objeto wrapper completo: {"version":"0.1.0","messages":[...]}.

A tentativa/captura garante que a gravação de telemetria não seja gerada mesmo quando partes de mensagem contêm valores não serializáveis JSON (por exemplo, BigInt, refs circulares).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Parâmetros

wrapper

InputMessages | OutputMessages

Retornos

string

setLogger(ILogger)

Definir uma implementação de agente personalizado para o SDK de observabilidade

Exemplo com Winston:

import * as winston from 'winston';
import { setLogger } from '@microsoft/agents-a365-observability';

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

setLogger({
  info: (msg, ...args) => winstonLogger.info(msg, ...args),
  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
  error: (msg, ...args) => winstonLogger.error(msg, ...args),
  event: (eventType, isSuccess, durationMs, message, details) => {
    // eventType is ExporterEventNames enum value
    winstonLogger.log({ level: isSuccess ? 'info' : 'error', eventType, isSuccess, durationMs, message, ...details });
  }
});

function setLogger(customLogger: ILogger)

Parâmetros

customLogger
ILogger

A implementação do agente personalizado

truncateValue(string)

Trunque um valor de cadeia de caracteres para MAX_ATTRIBUTE_LENGTH caracteres. Se o valor exceder o limite, ele será cortado e um sufixo de truncamento será acrescentado, com o comprimento total limitado exatamente MAX_ATTRIBUTE_LENGTH.

function truncateValue(value: string): string

Parâmetros

value

string

A cadeia de caracteres a ser truncada

Retornos

string

A cadeia de caracteres original se estiver dentro dos limites, caso contrário, a cadeia de caracteres truncada

updateExportToken(string)

Atualize o token de exportação no Contexto OTel ativo. Chame isso para atualizar o token antes de encerrar o intervalo raiz quando o token original pode ter expirado durante uma solicitação de execução longa.

Deve ser chamado dentro do mesmo contexto assíncrono criado por runWithExportToken.

function updateExportToken(token: string): boolean

Parâmetros

token

string

O token novo a ser usado para exportação.

Retornos

boolean

true se o token foi atualizado com êxito, false se nenhum detentor de token foi encontrado.

Detalhes da variável

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Tipo

string

MAX_ATTRIBUTE_LENGTH

Comprimento máximo para valores de atributo de intervalo. Valores que excedem esse limite serão truncados com um sufixo.

MAX_ATTRIBUTE_LENGTH: 8192

Tipo

8192

defaultObservabilityConfigurationProvider

Provedor padrão compartilhado para ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Tipo

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Provedor padrão compartilhado para PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Tipo

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Instância do agente padrão para compatibilidade com versões anteriores. Delega ao agente global que pode ser substituído por meio de setLogger().

logger: ILogger

Tipo

ILogger