@microsoft/agents-a365-observability package

Klasser

Agent365ExporterOptions

Maksimalt antall spenn per eksportgruppe.
BaggageBuilder

Per forespørsel baggage builder for OpenTelemetry kontekst overføring.

Denne klassen gir en flytende API for å angi bagasjeverdier som skal overføres i OpenTelemetry-konteksten.

Eksempel

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

Kontekstbehandling for bagasjeomfang.

Denne klassen administrerer livssyklusen til bagasjeverdier, setter dem på enter og gjenoppretter den forrige konteksten ved avslutning.
Builder

Builder for konfigurasjon av Agent 365 med OpenTelemetry-sporing
ExecuteToolScope

Gir OpenTelemetry sporingsomfang for operasjoner for kjøring av kunstig intelligens-verktøy.
InferenceScope

Gir OpenTelemetry sporingsomfang for generative AI-slutningsoperasjoner.
InvokeAgentScope

Gir OpenTelemetry sporingsomfang for aktiveringsoperasjoner for AI-agent.
ObservabilityConfiguration

Konfigurasjon for observabilitetspakke. Arver kjøretidsinnstillinger og legger til observabilitetsspesifikke innstillinger.
ObservabilityManager

Hovedinngangspunkt for Agent 365 som gir OpenTelemetry-sporing for AI-agenter og -verktøy
OpenTelemetryConstants

OpenTelemetry-konstanter for Agent 365
OpenTelemetryScope

Basisklasse for OpenTelemetry-sporingsomfang
OutputScope

Gir OpenTelemetry sporingsomfang for utdatameldingssporing med overordnet span-kobling.
PerRequestSpanProcessorConfiguration

Konfigurasjon for PerRequestSpanProcessor. Arver kjøretidsinnstillinger (clusterCategory, isNodeEnvDevelopment) og legger til prosessorrekkverk per forespørsel.

Dette er atskilt fra ObservabilityConfiguration fordi PerRequestSpanProcessor bare brukes i bestemte scenarioer, og disse innstillingene bør ikke vises i common ObservabilityConfiguration.

Grensesnitt

AgentDetails

Detaljer om en AI-agent
BlobPart

Innebygde binærdata (base64-kodet).
BuilderOptions

Konfigurasjonsalternativer for Agent 365 Observability Builder
CallerDetails

Anroperdetaljer for oppretting av omfang. Støtter menneskelige innringere, agentoppringere eller begge deler (A2A med et menneske i kjeden).

Overføringsnotat: I v1 refererte navnet CallerDetails til den menneskelige innringeridentiteten (nå UserDetails). I v2 ble det repurposed som en wrapper som grupperer både menneskelig og agent innringer informasjon.

Se UserDetails – identitet for den menneskelige innringeren (tidligere CallerDetails) Se CHANGELOG.md – inndelingen om brudd på endringer for overføringsveiledning
Channel

Representerer kanal for en aktivering
ChatMessage

En inndatamelding sendt til en modell (OTEL gen-ai semantiske konvensjoner).
FilePart

Referanse til en forhåndsopplastet fil.
GenericPart

Utvidbar del for egendefinerte / fremtidige typer.
GenericServerToolCall

Detaljer om utvidbart serververktøy med en typediskriminator.
GenericServerToolCallResponse

Extensible server tool call response with a type discriminator.
ILogger

Egendefinert loggergrensesnitt for Agent 365 observabilitet Implementer dette grensesnittet for å støtte logging av serverdel
InferenceDetails

Detaljer for en slutningssamtale
InferenceResponse

Detaljer for registrering av svaret fra et slutningsanrop
InputMessages
InvokeAgentScopeDetails

Detaljer for aktivering av agentomfang.
OutputMessage

En utdatamelding produsert av en modell (OTEL gen-ai semantiske konvensjoner).
OutputMessages
OutputResponse

Representerer et svar som inneholder utdatameldinger fra en agent. Brukes med OutputScope for sporing av utdatameldinger. Godtar vanlige strenger, strukturerte OTEL OutputMessage-objekter eller en rå diktering (behandlet som et verktøykalleresultat per OTEL-spesifikasjon).
ParentSpanRef

Referanse til et overordnet spenn for eksplisitt overordnet-underordnet kobling på tvers av aynkrone grenser. Brukes når automatisk kontekstoverføring mislykkes (for eksempel WebSocket-tilbakeringinger, eksterne hendelsesbehandlinger).
ReasoningPart

Modell resonnement / kjede-of-thought innhold.
Request

Representerer en forespørsel med telemetrikontekst. Brukes på tvers av alle omfangstyper for kanal- og samtalesporing.
ServerToolCallPart

Aktivering av verktøy på serversiden.
ServerToolCallResponsePart

Verktøysvar på serversiden.
ServiceEndpoint

Representerer et endepunkt for agentaktivering
SpanDetails

Spenn over konfigurasjonsdetaljer for oppretting av omfang. Grupper OpenTelemetry spenner over alternativer til ett enkelt objekt, slik at signaturen for omfangsmetoden forblir stabil etter hvert som nye alternativer legges til.
TextPart

Innhold i ren tekst.
ToolCallDetails

Detaljer om et verktøyanrop utført av en agent
ToolCallRequestPart

Et verktøyanrop forespurt av modellen.
ToolCallResponsePart

Resultatet av et verktøyanrop.
UriPart

Ekstern URI-referanse.
UserDetails

Detaljer om den menneskelige brukeroppringeren.

Typealiaser

EnhancedAgentDetails
HeadersCarrier

Transportørtype for HTTP-overskrifter som brukes i overføring av sporingskontekst. Kompatibel med Node.js InnkommendeHttpHeaders og vanlige strengkart.
InputMessagesParam

Godtatte inndata for recordInputMessages. Støtter én enkelt streng, en matrise med strenger (bakoverkombinering) eller versjonsinnpakningen.
MessagePart

Union av alle meldingsdeltyper per OTEL gen-ai semantiske konvensjoner.

Obs! GenericPart fungerer som en catch-all for videresendingskompatibilitet med egendefinerte eller fremtidige deltyper. Fordi den type er string (ikke litteral), vil ikke uttømmendeswitch/casepart.type på produsere kompileringstidsfeil for ubehandlede tilfeller.
ObservabilityConfigurationOptions

Konfigurasjonsalternativer for observerbarhet – utvider kjøretidsalternativer. Alle overstyringer er funksjoner som kalles på hver egenskapstilgang.

Arvet fra RuntimeConfigurationOptions:

  • clusterCategory
  • isNodeEnvDevelopment

Obs! isDevelopmentEnvironment er en avledet getter på konfigurasjonsklassen (basert på klyngekategori), ikke et overordnet alternativ.
OutputMessagesParam

Godtatte inndata for recordOutputMessages. Støtter én enkelt streng, en matrise med strenger (bakoverkombinering) eller versjonsinnpakningen.
ParentContext

En overordnet kontekst for oppretting av tidsrom. Godtar enten:
PerRequestSpanProcessorConfigurationOptions

Konfigurasjonsalternativer for PerRequestSpanProcessor – utvider kjøretidsalternativer. Alle overstyringer er funksjoner som kalles på hver egenskapstilgang.

Arvet fra RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Godtatte inndata for OutputResponse.messages. Støtter vanlige strenger, strukturerte OutputMessages eller en rå diktering (behandlet som et verktøyanropsresultat per OTEL-spesifikasjon og serialisert direkte via JSON.stringify).

Nummereringer

ExporterEventNames

Hendelsesnavn som brukes av Agent365Exporter for logging og overvåking. Dette er hendelsestyper med lav kardinalitet for å sikre effektiv overvåking og aggregasjon.
FinishReason

Årsaken til at en modell sluttet å generere per OTEL gen-ai semantiske konvensjoner.
InferenceOperationType

Representerer ulike operasjoner for typer for modellslutning
InvocationRole

Representerer ulike roller som kan aktivere en agent
MessageRole

Rollen til en meldingsdeltaker per OTEL gen-ai semantiske konvensjoner.
Modality

Mediemodalitet for blob-, fil- og URI-deler.

Funksjoner

createContextWithParentSpanRef(Context, ParentSpanRef)

Oppretter en ny kontekst med en eksplisitt overordnet span-referanse. Dette gjør at underordnede intervaller kan være riktig overordnet selv når asynkron kontekst er brutt.
extractContextFromHeaders(HeadersCarrier, Context)

Trekker ut sporingskontekst fra innkommende HTTP-overskrifter ved hjelp av den globalt registrerte W3C-propagatoren. Returnerer en OTel ParentContext som kan sendes til omfangsklasser som parentcontext.

Eksempel

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

Formater feilobjekt for logging med melding og stakksporing
getExportToken(Context)

Hent eksporttokenet per forespørsel fra en gitt OTel-kontekst (eller den aktive).
getLogger()

Få den gjeldende loggerforekomsten
injectContextToHeaders(Record<string, string>, Context)

Setter inn gjeldende sporingskontekst (traceparent/tracestate overskrifter) i det angitte overskriftsobjektet ved hjelp av den globalt registrerte W3C-propagatoren.

Eksempel

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

Kontroller om eksport per forespørsel er aktivert. Prioritet: interne overstyrer > miljøvariabelen for konfigurasjonsleverandør > . Når den er aktivert, brukes PerRequestSpanProcessor i stedet for BatchSpanProcessor. Tokenet sendes via OTel Context (async local storage) ved eksporttidspunktet.
normalizeInputMessages(InputMessagesParam)

Normaliserer en InputMessagesParam til en versjonsinnpakning InputMessages .

  • string / string[] → konvertert til ChatMessage[] og pakket inn
  • InputMessages → returnerte as-is
normalizeOutputMessages(OutputMessagesParam)

Normaliserer en OutputMessagesParam til en versjonsinnpakning OutputMessages .

  • string / string[] → konvertert til OutputMessage[] og pakket inn
  • OutputMessages → returnerte as-is
resetLogger()

Tilbakestill til standard konsolllogger (hovedsakelig for testing)
runWithExportToken<T>(string, () => T)

Kjør en funksjon i en kontekst som bærer eksporttokenet per forespørsel. Dette beholder tokenet bare i OTel Context (ALS), aldri i noe register.

Tokenet kan oppdateres senere via updateExportToken() før sporingen tømmes – nyttig når tilbakeringingen er langvarig, og det opprinnelige tokenet kan utløpe før eksport.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Trekker ut sporingskontekst fra innkommende HTTP-overskrifter og kjører tilbakeringingen i denne konteksten. Eventuelle spenn som opprettes i tilbakeringingen, blir overordnet den utpakkede sporingen.

Eksempel

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

Kjører en tilbakeringingsfunksjon i en kontekst som har en eksplisitt overordnet span-referanse. Dette er nyttig for å opprette underordnede spenn i async-tilbakeringinger der kontekstoverføring er brutt.
safeSerializeToJson(string | Record<string, unknown>, string)

Sikrer at verdien alltid er en JSON-lignende streng.

  • Objekter serialiseres via JSON.stringify.
  • Strenger som allerede er gyldige JSON-objekter/matriser, sendes gjennom.
  • Alle andre strenger (inkludert nakne JSON-primitiver) er pakket inn: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Serialiserer en versjon av meldingsbryting til JSON.

Utdataene er det fullstendige wrapper-objektet: {"version":"0.1.0","messages":[...]}.

Prøve-/fangsten sikrer at telemetriopptak ikke kastes selv når meldingsdeler inneholder verdier som ikke er JSON-serialiserbare (f.eks. BigInt, sirkelrefs).
setLogger(ILogger)

Angi en egendefinert loggerimplementering for SDK for observerbarhet

Eksempel med 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)

Oppdater eksporttokenet i den aktive OTel-konteksten. Kall dette for å oppdatere tokenet før du avslutter rotintervallet når det opprinnelige tokenet kan ha utløpt under en langvarig forespørsel.

Må kalles i samme asynkron kontekst som opprettes av runWithExportToken.

Variabler

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

Delt standardleverandør for ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Delt standardleverandør for PerRequestSpanProcessorConfiguration.
logger

Standard loggerforekomst for bakoverkompatibilitet. Representanter til den globale loggeren som kan erstattes via setLogger().

Funksjonsdetaljer

createContextWithParentSpanRef(Context, ParentSpanRef)

Oppretter en ny kontekst med en eksplisitt overordnet span-referanse. Dette gjør at underordnede intervaller kan være riktig overordnet selv når asynkron kontekst er brutt.

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

Parametere

base

Context

Basiskonteksten som skal utvides (vanligvis context.active())

parent
ParentSpanRef

Den overordnede span-referansen som inneholder traceId og spanId

Returnerer

Context

En ny kontekst med det overordnede spansettet

extractContextFromHeaders(HeadersCarrier, Context)

Trekker ut sporingskontekst fra innkommende HTTP-overskrifter ved hjelp av den globalt registrerte W3C-propagatoren. Returnerer en OTel ParentContext som kan sendes til omfangsklasser som parentcontext.

Eksempel

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

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

Parametere

headers
HeadersCarrier

De innkommende HTTP-forespørselshodene som inneholder traceparent/tracestate.

baseCtx

Context

Valgfri basiskontekst som skal utvides. Standarder for den aktive konteksten.

Returnerer

Context

En OTel-kontekst som inneholder den utpakkede sporingsinformasjonen.

formatError(unknown)

Formater feilobjekt for logging med melding og stakksporing

function formatError(error: unknown): string

Parametere

error

unknown

Returnerer

string

getExportToken(Context)

Hent eksporttokenet per forespørsel fra en gitt OTel-kontekst (eller den aktive).

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

Parametere

ctx

Context

Returnerer

string | undefined

getLogger()

Få den gjeldende loggerforekomsten

function getLogger(): ILogger

Returnerer

ILogger

injectContextToHeaders(Record<string, string>, Context)

Setter inn gjeldende sporingskontekst (traceparent/tracestate overskrifter) i det angitte overskriftsobjektet ved hjelp av den globalt registrerte W3C-propagatoren.

Eksempel

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>

Parametere

headers

Record<string, string>

Mutable object where trace context headers will be written.

ctx

Context

Valgfri OTel-kontekst å sette inn fra. Standarder for den aktive konteksten.

Returnerer

Record<string, string>

Det samme headers objektet, for kjedevennlighet.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Kontroller om eksport per forespørsel er aktivert. Prioritet: interne overstyrer > miljøvariabelen for konfigurasjonsleverandør > . Når den er aktivert, brukes PerRequestSpanProcessor i stedet for BatchSpanProcessor. Tokenet sendes via OTel Context (async local storage) ved eksporttidspunktet.

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

Parametere

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Valgfri konfigurasjonsleverandør. Standarder som standardPerRequestSpanProcessorConfigurationProvider hvis det ikke er angitt.

Returnerer

boolean

normalizeInputMessages(InputMessagesParam)

Normaliserer en InputMessagesParam til en versjonsinnpakning InputMessages .

  • string / string[] → konvertert til ChatMessage[] og pakket inn
  • InputMessages → returnerte as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages

Parametere

param
InputMessagesParam

Returnerer

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Normaliserer en OutputMessagesParam til en versjonsinnpakning OutputMessages .

  • string / string[] → konvertert til OutputMessage[] og pakket inn
  • OutputMessages → returnerte as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

Parametere

param
OutputMessagesParam

Returnerer

OutputMessages

resetLogger()

Tilbakestill til standard konsolllogger (hovedsakelig for testing)

function resetLogger()

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

Kjør en funksjon i en kontekst som bærer eksporttokenet per forespørsel. Dette beholder tokenet bare i OTel Context (ALS), aldri i noe register.

Tokenet kan oppdateres senere via updateExportToken() før sporingen tømmes – nyttig når tilbakeringingen er langvarig, og det opprinnelige tokenet kan utløpe før eksport.

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

Parametere

token

string

fn

() => T

Returnerer

T

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

Trekker ut sporingskontekst fra innkommende HTTP-overskrifter og kjører tilbakeringingen i denne konteksten. Eventuelle spenn som opprettes i tilbakeringingen, blir overordnet den utpakkede sporingen.

Eksempel

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

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

Parametere

headers
HeadersCarrier

De innkommende HTTP-forespørselshodene som inneholder traceparent/tracestate.

callback

() => T

Funksjonen som skal kjøres i den utpakkede konteksten.

Returnerer

T

Resultatet av tilbakeringingen.

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

Kjører en tilbakeringingsfunksjon i en kontekst som har en eksplisitt overordnet span-referanse. Dette er nyttig for å opprette underordnede spenn i async-tilbakeringinger der kontekstoverføring er brutt.

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

Parametere

parent
ParentSpanRef

Referanse for overordnet span

callback

() => T

Funksjonen som skal utføres med den overordnede konteksten

Returnerer

T

Resultatet av tilbakeringingen

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

Sikrer at verdien alltid er en JSON-lignende streng.

  • Objekter serialiseres via JSON.stringify.
  • Strenger som allerede er gyldige JSON-objekter/matriser, sendes gjennom.
  • Alle andre strenger (inkludert nakne JSON-primitiver) er pakket inn: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Parametere

value

string | Record<string, unknown>

Verdien som skal serialiseres.

key

string

Nøkkelen som skal brukes når du pakker inn en vanlig streng.

Returnerer

string

serializeMessages(InputMessages | OutputMessages)

Serialiserer en versjon av meldingsbryting til JSON.

Utdataene er det fullstendige wrapper-objektet: {"version":"0.1.0","messages":[...]}.

Prøve-/fangsten sikrer at telemetriopptak ikke kastes selv når meldingsdeler inneholder verdier som ikke er JSON-serialiserbare (f.eks. BigInt, sirkelrefs).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Parametere

wrapper

InputMessages | OutputMessages

Returnerer

string

setLogger(ILogger)

Angi en egendefinert loggerimplementering for SDK for observerbarhet

Eksempel med 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)

Parametere

customLogger
ILogger

Den egendefinerte loggerimplementeringen

updateExportToken(string)

Oppdater eksporttokenet i den aktive OTel-konteksten. Kall dette for å oppdatere tokenet før du avslutter rotintervallet når det opprinnelige tokenet kan ha utløpt under en langvarig forespørsel.

Må kalles i samme asynkron kontekst som opprettes av runWithExportToken.

function updateExportToken(token: string): boolean

Parametere

token

string

Det ferske tokenet som skal brukes til eksport.

Returnerer

boolean

sann hvis tokenet ble oppdatert, usann hvis ingen tokenholder ble funnet.

Variable detaljer

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Type

string

defaultObservabilityConfigurationProvider

Delt standardleverandør for ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Type

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Delt standardleverandør for PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Type

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Standard loggerforekomst for bakoverkompatibilitet. Representanter til den globale loggeren som kan erstattes via setLogger().

logger: ILogger

Type

ILogger