@microsoft/agents-a365-observability package

Classes

Agent365ExporterOptions

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

Construtor de bagagens por pedido para propagação de contexto OpenTelemetry.

Esta classe fornece uma API fluente para definir valores de bagage 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

Gestor de contexto para o âmbito da bagagem.

Esta classe gere o ciclo de vida dos valores de bagagem, colocando-os em enter e restaurando o contexto anterior na saída.
Builder

Builder para configurar o Agent 365 com rastreamento OpenTelemetry
ExecuteToolScope

Fornece o âmbito de rastreamento OpenTelemetry para operações de execução de ferramentas de IA.
InferenceScope

Fornece o âmbito de rastreamento OpenTelemetry para operações de inferência de IA generativa.
InvokeAgentScope

Fornece o âmbito de rastreamento OpenTelemetry para operações de invocação de agentes de IA.
ObservabilityConfiguration

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

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

Constantes OpenTelemetry para Agent 365
OpenTelemetryScope

Classe base para escopos de rastreio OpenTelemetry
OutputScope

Fornece o âmbito de rastreamento OpenTelemetry para rastreamento de mensagens de saída com ligação de span pai.
PerRequestSpanProcessorConfiguration

Configuração para PerRequestSpanProcessor. Herda as definições de runtime (clusterCategory, isNodeEnvDevelopment) e adiciona guardas de proteção ao processador por pedido.

Isto está separado do ObservabilityConfiguration porque o PerRequestSpanProcessor é usado apenas em cenários específicos e estas definições não devem ser expostas no comum ObservabilityConfiguration.

Interfaces

AgentDetails

Detalhes sobre um agente de IA
BlobPart

Dados binários inline (codificados base64).
BuilderOptions

Opções de configuração para o Agent 365 Observability Builder
CallerDetails

Detalhes do chamador para a criação do telescópio. Suporta chamadas humanas, chamadas agentes, ou ambas (A2A com um humano na cadeia).

Nota sobre migração: Na v1, o nome CallerDetails referia-se à identidade humana do chamador (agora UserDetails). Na v2, foi reaproveitado como um wrapper que agrupa informações tanto de humanos como de agentes que chamam.

Ver UserDetails — identidade humana do chamador (anteriormente CallerDetails) Ver CHANGELOG.md — secção de alterações de quebra para orientações de migração
Channel

Representa o canal para uma invocação
ChatMessage

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

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

Peça extensível para tipos personalizados / futuros.
GenericServerToolCall

Detalhes extensíveis de chamadas de ferramenta de servidor com um discriminador de tipo.
GenericServerToolCallResponse

Resposta extensível de chamada de ferramenta de servidor com discriminador de tipo.
ILogger

Interface de logger personalizada para observabilidade do Agente 365 Implemente esta interface para suportar backends de registo
InferenceDetails

Detalhes para uma chamada de inferência
InferenceResponse

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

Detalhes para invocar o âmbito do agente.
OutputMessage

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

Representa uma resposta contendo mensagens de saída de um agente. Usado com o OutputScope para rastreio de mensagens de saída. Aceita strings simples, objetos estruturados OTEL OutputMessage ou um dictado bruto (tratado como resultado de chamada de ferramenta segundo a especificação OTEL).
ParentSpanRef

Referência a um span pai para ligação explícita entre pai e filho através de fronteiras assíncronas. Usado quando a propagação automática do contexto falha (por exemplo, callbacks WebSocket, manipuladores externos de eventos).
ReasoningPart

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

Representa um pedido com contexto de telemetria. Usado em todos os tipos de âmbito para acompanhamento de canais e conversas.
ServerToolCallPart

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

Resposta à ferramenta do lado do servidor.
ServiceEndpoint

Representa um ponto final para a invocação do agente
SpanDetails

Detalhe a configuração do span para criação do escopo. Os Grupos OpenTelemetry abrangem as opções num único objeto, de modo que a assinatura do método scope se mantém estável à medida que novas opções são adicionadas.
TextPart

Conteúdo em texto simples.
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 externa de URI.
UserDetails

Detalhes sobre o utilizador humano que chama.

Aliases de Tipo

EnhancedAgentDetails
HeadersCarrier

Tipo de portadora para cabeçalhos HTTP usados na propagação do contexto de traços. Compatível com Node.js IncomingHttpHeaders e mapas de string simples.
InputMessagesParam

Aceitou a entrada para recordInputMessages. Suporta uma única cadeia, um array de cadeias (compat invertido) ou o wrapper versionado.
MessagePart

União de todos os tipos de partes de mensagens conforme as convenções semânticas gen-ai do OTEL.

Nota: A GenericPart funciona como um termo genérico para compatibilidade futura com tipos de peças personalizadas ou futuras. Como é typestring (não literal), exaustivoswitch/case em part.type não produzirá erros em tempo de compilação para casos não tratados.
ObservabilityConfigurationOptions

Opções de configuração de observabilidade - estende as opções de tempo de execução. Todos os overrides são funções chamadas em cada acesso à propriedade.

Herdado do RuntimeConfigurationOptions:

  • clusterCategoria
  • isNodeEnvDevelopment

Nota: isDevelopmentEnvironment é um getter derivado na classe de configuração (baseado no clusterCategory), não é uma opção sobrescrita.
OutputMessagesParam

Aceitou a entrada para recordOutputMessages. Suporta uma única cadeia, um array de cadeias (compat invertido) ou o wrapper versionado.
ParentContext

Um contexto parental para criação de spans. Aceita um:
PerRequestSpanProcessorConfigurationOptions

Opções de configuração para PerRequestSpanProcessor - estende as opções de runtime. Todos os overrides são funções chamadas em cada acesso à propriedade.

Herdado do RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Aceitou a entrada para OutputResponse.messages. Suporta strings simples, OutputMessages estruturados ou um dict bruto (tratado como resultado de chamada de ferramenta segundo a especificação OTEL e serializado diretamente via JSON.stringify).

Enumerações

ExporterEventNames

Nomes de eventos usados pelo Agent365Exporter para registo e monitorização. Estes são tipos de eventos de baixa cardinalidade para garantir monitorização e agregação eficientes.
FinishReason

Razão pela qual um modelo deixou de gerar as convenções semânticas gen-ai do OTEL.
InferenceOperationType

Representa diferentes operações para tipos de inferência de modelos
InvocationRole

Representa diferentes papéis que podem invocar um agente
MessageRole

Papel de um participante de mensagem segundo as convenções semânticas gen-ai do OTEL.
Modality

Modalidade de media para partes de blob, ficheiro e URI.

Funções

createContextWithParentSpanRef(Context, ParentSpanRef)

Cria um novo Contexto com uma referência explícita ao pai span. Isto permite que os spans filhos sejam corretamente parentados mesmo quando o contexto assíncrono está quebrado.
extractContextFromHeaders(HeadersCarrier, Context)

Extrai o contexto traçado dos cabeçalhos HTTP recebidos usando o propagador W3C globalmente registado. Devolve um OTel ParentContext que pode ser passado para as classes de âmbito como um ParentContext.

Exemplo

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

Objeto de erro de formatar para registo com mensagem e rastreio de pilha
getExportToken(Context)

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

Obtenha a instância atual do logger
injectContextToHeaders(Record<string, string>, Context)

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

Exemplo

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

Verifica se a exportação por pedido está ativada. Precedência: overrides > internos variável de ambiente de configuração do provedor > de configuração. Quando ativado, o PerRequestSpanProcessor é usado em vez de BatchSpanProcessor. O token é passado via OTel Context (armazenamento local assíncrono) no momento da exportação.
normalizeInputMessages(InputMessagesParam)

Normaliza an InputMessagesParam para um wrapper versionado InputMessages .

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

Normaliza an OutputMessagesParam para um wrapper versionado OutputMessages .

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

Reiniciar para o logger padrão da consola (principalmente para testes)
runWithExportToken<T>(string, () => T)

Executa uma função dentro de um Contexto que transporta o token de exportação por pedido. Isto mantém o token apenas no Contexto OTel (ALS), nunca em qualquer registo.

O token pode ser atualizado mais tarde antes updateExportToken() do rastreio ser limpo — útil quando o callback é de longa duração e o token original pode expirar antes da exportação.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Extrai o contexto do traço dos cabeçalhos HTTP recebidos e executa o callback dentro desse contexto. Quaisquer spans criados dentro do callback serão parentados para o rastreio extraído.

Exemplo

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

Executa uma função de callback dentro de um contexto que tem uma referência explícita ao pai span. Isto é útil para criar spans filhos em callbacks assíncronos onde a propagação do contexto está quebrada.
safeSerializeToJson(string | Record<string, unknown>, string)

Garante que o valor é sempre uma string JSON parseável.

  • Os objetos são serializados via JSON.stringify.
  • Strings que já são objetos/arrays JSON válidos são passados.
  • Todas as outras strings (incluindo primitivas JSON nuas) são enroladas: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Serializa um wrapper de mensagem versionada para JSON.

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

O try/catch garante que a gravação de telemetria não seja lançada mesmo quando partes da mensagem contêm valores não serializáveis em JSON (por exemplo, BigInt, referências circulares).
setLogger(ILogger)

Defina uma implementação personalizada do logger 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 });
  }
});
updateExportToken(string)

Atualize o token de exportação no Contexto OTel ativo. Chame isto para atualizar o token antes de terminar o root span quando o token original pode ter expirado durante um pedido de longa duração.

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

Variáveis

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

Fornecedor partilhado por defeito para o ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Fornecedor predefinido partilhado para PerRequestSpanProcessorConfiguration.
logger

Instância padrão do logger para compatibilidade retroativa. Delega para o logger global que pode ser substituído via setLogger().

Detalhes de Função

createContextWithParentSpanRef(Context, ParentSpanRef)

Cria um novo Contexto com uma referência explícita ao pai span. Isto permite que os spans filhos sejam corretamente parentados mesmo quando o contexto assíncrono está quebrado.

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

Parâmetros

base

Context

O contexto base a estender (tipicamente context.active())

parent
ParentSpanRef

A referência do span pai que contém traceId e spanId

Devoluções

Context

Um novo Contexto com o conjunto de span pai

extractContextFromHeaders(HeadersCarrier, Context)

Extrai o contexto traçado dos cabeçalhos HTTP recebidos usando o propagador W3C globalmente registado. Devolve um OTel ParentContext que pode ser passado para as classes de âmbito 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 pedidos HTTP recebidos que contêm traceparent/tracestate.

baseCtx

Context

Contexto base opcional para alargar. Por defeito, é o contexto ativo.

Devoluções

Context

Um Contexto OTel contendo a informação de traço extraída.

formatError(unknown)

Objeto de erro de formatar para registo com mensagem e rastreio de pilha

function formatError(error: unknown): string

Parâmetros

error

unknown

Devoluções

string

getExportToken(Context)

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

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

Parâmetros

ctx

Context

Devoluções

string | undefined

getLogger()

Obtenha a instância atual do logger

function getLogger(): ILogger

Devoluções

ILogger

injectContextToHeaders(Record<string, string>, Context)

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

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 onde serão escritos os cabeçalhos do contexto dos traços.

ctx

Context

Contexto OT opcional para injetar. Por defeito, é o contexto ativo.

Devoluções

Record<string, string>

O mesmo headers objeto, para a conveniência da corrente.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Verifica se a exportação por pedido está ativada. Precedência: overrides > internos variável de ambiente de configuração do provedor > de configuração. Quando ativado, o PerRequestSpanProcessor é usado em vez de BatchSpanProcessor. O token é passado via OTel Context (armazenamento local assíncrono) no momento da exportação.

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

Parâmetros

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Fornecedor de configuração opcional. Por defeito é defaultPerRequestSpanProcessorConfigurationProvider se não especificado.

Devoluções

boolean

normalizeInputMessages(InputMessagesParam)

Normaliza an InputMessagesParam para um wrapper versionado InputMessages .

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

Parâmetros

param
InputMessagesParam

Devoluções

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Normaliza an OutputMessagesParam para um wrapper versionado OutputMessages .

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

Parâmetros

param
OutputMessagesParam

Devoluções

OutputMessages

resetLogger()

Reiniciar para o logger padrão da consola (principalmente para testes)

function resetLogger()

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

Executa uma função dentro de um Contexto que transporta o token de exportação por pedido. Isto mantém o token apenas no Contexto OTel (ALS), nunca em qualquer registo.

O token pode ser atualizado mais tarde antes updateExportToken() do rastreio ser limpo — útil quando o callback é de longa duração e o token original pode expirar antes da exportação.

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

Parâmetros

token

string

fn

() => T

Devoluções

T

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

Extrai o contexto do traço dos cabeçalhos HTTP recebidos e executa o callback dentro desse contexto. Quaisquer spans criados dentro do callback serão parentados para o rastreio 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 pedidos HTTP recebidos que contêm traceparent/tracestate.

callback

() => T

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

Devoluções

T

O resultado do callback.

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

Executa uma função de callback dentro de um contexto que tem uma referência explícita ao pai span. Isto é útil para criar spans filhos em callbacks assíncronos onde a propagação do contexto está quebrada.

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

Parâmetros

parent
ParentSpanRef

A referência do span pai

callback

() => T

A função a executar com o contexto pai

Devoluções

T

O resultado do callback

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

Garante que o valor é sempre uma string JSON parseável.

  • Os objetos são serializados via JSON.stringify.
  • Strings que já são objetos/arrays JSON válidos são passados.
  • Todas as outras strings (incluindo primitivas JSON nuas) são enroladas: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Parâmetros

value

string | Record<string, unknown>

O valor de serializar.

key

string

A chave a usar ao enrolar uma corda simples.

Devoluções

string

serializeMessages(InputMessages | OutputMessages)

Serializa um wrapper de mensagem versionada para JSON.

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

O try/catch garante que a gravação de telemetria não seja lançada mesmo quando partes da mensagem contêm valores não serializáveis em JSON (por exemplo, BigInt, referências circulares).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Parâmetros

wrapper

InputMessages | OutputMessages

Devoluções

string

setLogger(ILogger)

Defina uma implementação personalizada do logger 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 logger personalizado

updateExportToken(string)

Atualize o token de exportação no Contexto OTel ativo. Chame isto para atualizar o token antes de terminar o root span quando o token original pode ter expirado durante um pedido de longa duração.

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

function updateExportToken(token: string): boolean

Parâmetros

token

string

O token fresco para usar na exportação.

Devoluções

boolean

Verdade se o token foi atualizado com sucesso, falso se não foi encontrado nenhum titular do token.

Detalhes das variáveis

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Tipo

string

defaultObservabilityConfigurationProvider

Fornecedor partilhado por defeito para o ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Tipo

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Fornecedor predefinido partilhado para PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Tipo

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Instância padrão do logger para compatibilidade retroativa. Delega para o logger global que pode ser substituído via setLogger().

logger: ILogger

Tipo

ILogger