@microsoft/agents-a365-observability package

Klasser

Agent365ExporterOptions

Maximalt antal intervall per exportbatch.
BaggageBuilder

Bagagebyggare per begäran för OpenTelemetry-kontextspridning.

Den här klassen tillhandahåller ett fluent-API för att ange bagagevärden som ska spridas i OpenTelemetry-kontexten.

Exempel

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

Kontextansvarig för bagageomfång.

Den här klassen hanterar livscykeln för bagagevärden, ställer in dem vid inmatning och återställer den tidigare kontexten vid avslut.
Builder

Builder för att konfigurera Agent 365 med OpenTelemetry-spårning
ExecuteToolScope

Tillhandahåller OpenTelemetry-spårningsomfång för AI-verktygskörningsåtgärder.
InferenceScope

Tillhandahåller OpenTelemetry-spårningsomfång för generativa AI-slutsatsdragningsåtgärder.
InvokeAgentScope

Tillhandahåller OpenTelemetry-spårningsomfång för AI-agentanropsåtgärder.
ObservabilityConfiguration

Konfiguration för observerbarhetspaket. Ärver körningsinställningar och lägger till observerbarhetsspecifika inställningar.
ObservabilityManager

Huvudinmatningspunkt för Agent 365 som tillhandahåller OpenTelemetry-spårning för AI-agenter och -verktyg
OpenTelemetryConstants

OpenTelemetry-konstanter för Agent 365
OpenTelemetryScope

Basklass för OpenTelemetry-spårningsomfång
OutputScope

Tillhandahåller OpenTelemetry-spårningsomfång för spårning av utdatameddelanden med överordnad span-länkning.
PerRequestSpanProcessorConfiguration

Konfiguration för PerRequestSpanProcessor. Ärver körningsinställningar (clusterCategory, isNodeEnvDevelopment) och lägger till skyddsräcken för processor per begäran.

Detta är separerat från ObservabilityConfiguration eftersom PerRequestSpanProcessor endast används i specifika scenarier och dessa inställningar bör inte exponeras i den vanliga ObservabilityConfiguration.

Gränssnitt

AgentDetails

Information om en AI-agent
BlobPart

Infogade binära data (base64-kodade).
BuilderOptions

Konfigurationsalternativ för Agent 365 Observability Builder
CallerDetails

Information om uppringaren för att skapa omfång. Stöder mänskliga uppringare, agentuppringare eller båda (A2A med en människa i kedjan).

Migreringsanteckning: I v1 refererade namnet CallerDetails till den mänskliga uppringarens identitet (nu UserDetails). I v2 återanvändes den som en omslutning som grupperar både mänsklig information och agentuppringarinformation.

Se UserDetails – mänsklig uppringaridentitet (tidigare CallerDetails) Se avsnittet CHANGELOG.md – icke-bakåtkompatibla ändringar för migreringsvägledning
Channel

Representerar kanal för ett anrop
ChatMessage

Ett indatameddelande som skickas till en modell (OTEL gen-ai-semantiska konventioner).
FilePart

Referens till en föruppladdad fil.
GenericPart

Utökningsbar del för anpassade/framtida typer.
GenericServerToolCall

Utökningsbart serververktyg anropar information med en typdiskriminering.
GenericServerToolCallResponse

Utökningsbart serververktyg anropar svar med en typdiskriminering.
ILogger

Anpassat loggningsgränssnitt för Agent 365-observerbarhet Implementera det här gränssnittet för att stödja loggning av serverdelar
InferenceDetails

Information om ett slutsatsdragningsanrop
InferenceResponse

Information om hur du registrerar svaret från ett slutsatsdragningsanrop
InputMessages
InvokeAgentScopeDetails

Information om hur du anropar agentomfånget.
OutputMessage

Ett utdatameddelande som skapas av en modell (OTEL gen-ai semantiska konventioner).
OutputMessages
OutputResponse

Representerar ett svar som innehåller utdatameddelanden från en agent. Används med OutputScope för spårning av utdatameddelanden. Accepterar vanliga strängar, strukturerade OTEL OutputMessage-objekt eller en rå diktat (behandlas som ett verktygsanropsresultat per OTEL-specifikation).
ParentSpanRef

Referens till ett överordnat spann för explicit överordnad-underordnad länkning över asynkrona gränser. Används när automatisk kontextspridning misslyckas (t.ex. WebSocket-återanrop, externa händelsehanterare).
ReasoningPart

Modell resonemang / chain-of-thought innehåll.
Request

Representerar en begäran med telemetrikontext. Används för alla omfångstyper för kanal- och konversationsspårning.
ServerToolCallPart

Anrop av verktyg på serversidan.
ServerToolCallResponsePart

Svar på serversidans verktyg.
ServiceEndpoint

Representerar en slutpunkt för agentanrop
SpanDetails

Spänn över konfigurationsinformation för att skapa omfång. Grupperar alternativ för OpenTelemetry-span i ett enda objekt så att omfångsmetodens signatur förblir stabil när nya alternativ läggs till.
TextPart

Oformaterad text.
ToolCallDetails

Information om ett verktygsanrop som görs av en agent
ToolCallRequestPart

Ett verktygsanrop som begärs av modellen.
ToolCallResponsePart

Resultatet av ett verktygsanrop.
UriPart

Extern URI-referens.
UserDetails

Information om den mänskliga användarens uppringare.

Typalias

EnhancedAgentDetails
HeadersCarrier

Transportörstyp för HTTP-huvuden som används i spårningskontextspridning. Kompatibel med Node.js IncomingHttpHeaders och vanliga strängkartor.
InputMessagesParam

Accepterade indata för recordInputMessages. Har stöd för en enskild sträng, en matris med strängar (bakåtkompatibel) eller den versionshanterade omslutningen.
MessagePart

Union av alla typer av meddelandedel per OTEL gen-ai-semantiska konventioner.

Obs! GenericPart fungerar som en catch-all för framåtkompatibilitet med anpassade eller framtida deltyper. Eftersom dess type är string (inte en literal), kommer fullständigswitch/casepå part.type inte att generera kompileringstidsfel för ohanterade fall.
ObservabilityConfigurationOptions

Konfigurationsalternativ för observerbarhet – utökar körningsalternativen. Alla åsidosättningar är funktioner som anropas för varje egenskapsåtkomst.

Ärvd från RuntimeConfigurationOptions:

  • clusterCategory
  • isNodeEnvDevelopment

isDevelopmentEnvironment Obs! är en härledd getter för konfigurationsklassen (baserat på clusterCategory), inte ett åsidosättbart alternativ.
OutputMessagesParam

Accepterade indata för recordOutputMessages. Har stöd för en enskild sträng, en matris med strängar (bakåtkompatibel) eller den versionshanterade omslutningen.
ParentContext

En överordnad kontext för att skapa ett intervall. Accepterar antingen:
PerRequestSpanProcessorConfigurationOptions

Konfigurationsalternativ för PerRequestSpanProcessor – utökar körningsalternativen. Alla åsidosättningar är funktioner som anropas för varje egenskapsåtkomst.

Ärvd från RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Accepterade indata för OutputResponse.messages. Stöder vanliga strängar, strukturerade OutputMessages eller en rå diktering (behandlas som ett verktygsanropsresultat per OTEL-specifikation och serialiseras direkt via JSON.stringify).

Uppräkningar

ExporterEventNames

Händelsenamn som används av Agent365Exporter för loggning och övervakning. Det här är händelsetyper med låg kardinalitet för att säkerställa effektiv övervakning och aggregering.
FinishReason

Orsak till att en modell slutade generera per OTEL gen-ai-semantiska konventioner.
InferenceOperationType

Representerar olika åtgärder för typer för modellinferens
InvocationRole

Representerar olika roller som kan anropa en agent
MessageRole

Rollen för en meddelandedeltagare per OTEL gen-ai-semantiska konventioner.
Modality

Mediemodalitet för blob-, fil- och URI-delar.

Funktioner

createContextWithParentSpanRef(Context, ParentSpanRef)

Skapar en ny kontext med en explicit överordnad span-referens. Detta gör att underordnade intervall kan vara korrekt överordnad även när asynkron kontext är bruten.
extractContextFromHeaders(HeadersCarrier, Context)

Extraherar spårningskontext från inkommande HTTP-huvuden med hjälp av den globalt registrerade W3C-spridningen. Returnerar en OTel ParentContext som kan skickas till omfångsklasser som parentcontext.

Exempel

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

Formatera felobjekt för loggning med meddelande- och stackspårning
getExportToken(Context)

Hämta exporttoken per begäran från en viss OTel-kontext (eller den aktiva).
getLogger()

Hämta den aktuella loggningsinstansen
injectContextToHeaders(Record<string, string>, Context)

Matar in den aktuella spårningskontexten (traceparent/tracestate rubriker) i det angivna rubrikobjektet med hjälp av den globalt registrerade W3C-spridningen.

Exempel

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

Kontrollera om export per begäran är aktiverat. Prioritet: intern åsidosätter miljövariabeln för konfigurationsprovidern >> . När den är aktiverad används PerRequestSpanProcessor i stället för BatchSpanProcessor. Token skickas via OTel Context (asynkron lokal lagring) vid exporttillfället.
normalizeInputMessages(InputMessagesParam)

Normaliserar en InputMessagesParam till en versionsomslutning InputMessages .

  • string / string[] → konverteras till ChatMessage[] och omsluts
  • InputMessages → returnerade as-is
normalizeOutputMessages(OutputMessagesParam)

Normaliserar en OutputMessagesParam till en versionsomslutning OutputMessages .

  • string / string[] → konverteras till OutputMessage[] och omsluts
  • OutputMessages → returnerade as-is
resetLogger()

Återställ till standardkonsolloggaren (främst för testning)
runWithExportToken<T>(string, () => T)

Kör en funktion i en kontext som bär exporttoken per begäran. Detta behåller endast token i OTel Context (ALS), aldrig i något register.

Token kan uppdateras senare innan updateExportToken() spårningen töms – användbart när återanropet är tidskrävande och den ursprungliga token kan upphöra att gälla före export.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Extraherar spårningskontext från inkommande HTTP-huvuden och kör återanropet i den kontexten. Alla intervall som skapas i återanropet överordnas till den extraherade spårningen.

Exempel

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

Kör en motringningsfunktion i en kontext som har en explicit överordnad span-referens. Detta är användbart för att skapa underordnade intervall i asynkrona återanrop där kontextspridningen bryts.
safeSerializeToJson(string | Record<string, unknown>, string)

Säkerställer att värdet alltid är en JSON-parsningsbar sträng.

  • Objekt serialiseras via JSON.stringify.
  • Strängar som redan är giltiga JSON-objekt/matriser skickas igenom.
  • Alla andra strängar (inklusive bare JSON-primitiver) är omslutna: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Serialiserar ett versionshanterat meddelandeomslutning till JSON.

Utdata är det fullständiga omslutningsobjektet: {"version":"0.1.0","messages":[...]}.

Try/catch säkerställer att telemetriinspelningen inte genererar även när meddelandedelar innehåller värden som inte är JSON-serialiserbara (t.ex. BigInt, cirkulära refs).
setLogger(ILogger)

Ange en anpassad loggningsimplementering för observerbarhets-SDK:t

Exempel 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)

Uppdatera exporttoken i den aktiva OTel-kontexten. Anropa detta för att uppdatera token innan du avslutar rotintervallet när den ursprungliga token kan ha upphört att gälla under en tidskrävande begäran.

Måste anropas inom samma asynkrona kontext som skapas av runWithExportToken.

Variabler

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

Delad standardprovider för ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Delad standardprovider för PerRequestSpanProcessorConfiguration.
logger

Standardloggerinstans för bakåtkompatibilitet. Delegerar till den globala loggaren som kan ersättas via setLogger().

Funktionsinformation

createContextWithParentSpanRef(Context, ParentSpanRef)

Skapar en ny kontext med en explicit överordnad span-referens. Detta gör att underordnade intervall kan vara korrekt överordnad även när asynkron kontext är bruten.

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

Parametrar

base

Context

Baskontexten som ska utökas (vanligtvis context.active())

parent
ParentSpanRef

Referensen för överordnat span som innehåller traceId och spanId

Returer

Context

En ny kontext med den överordnade intervalluppsättningen

extractContextFromHeaders(HeadersCarrier, Context)

Extraherar spårningskontext från inkommande HTTP-huvuden med hjälp av den globalt registrerade W3C-spridningen. Returnerar en OTel ParentContext som kan skickas till omfångsklasser som parentcontext.

Exempel

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

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

Parametrar

headers
HeadersCarrier

De inkommande HTTP-begäranderubrikerna som innehåller traceparent/tracestate.

baseCtx

Context

Valfri baskontext för att utöka. Standardvärdet är den aktiva kontexten.

Returer

Context

En OTel-kontext som innehåller den extraherade spårningsinformationen.

formatError(unknown)

Formatera felobjekt för loggning med meddelande- och stackspårning

function formatError(error: unknown): string

Parametrar

error

unknown

Returer

string

getExportToken(Context)

Hämta exporttoken per begäran från en viss OTel-kontext (eller den aktiva).

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

Parametrar

ctx

Context

Returer

string | undefined

getLogger()

Hämta den aktuella loggningsinstansen

function getLogger(): ILogger

Returer

ILogger

injectContextToHeaders(Record<string, string>, Context)

Matar in den aktuella spårningskontexten (traceparent/tracestate rubriker) i det angivna rubrikobjektet med hjälp av den globalt registrerade W3C-spridningen.

Exempel

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>

Parametrar

headers

Record<string, string>

Föränderligt objekt där spårningskontextrubriker skrivs.

ctx

Context

Valfri OTel-kontext att mata in från. Standardvärdet är den aktiva kontexten.

Returer

Record<string, string>

Samma headers objekt, för att länka bekvämlighet.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Kontrollera om export per begäran är aktiverat. Prioritet: intern åsidosätter miljövariabeln för konfigurationsprovidern >> . När den är aktiverad används PerRequestSpanProcessor i stället för BatchSpanProcessor. Token skickas via OTel Context (asynkron lokal lagring) vid exporttillfället.

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

Parametrar

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Valfri konfigurationsprovider. Standardvärdet är defaultPerRequestSpanProcessorConfigurationProvider om det inte anges.

Returer

boolean

normalizeInputMessages(InputMessagesParam)

Normaliserar en InputMessagesParam till en versionsomslutning InputMessages .

  • string / string[] → konverteras till ChatMessage[] och omsluts
  • InputMessages → returnerade as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages

Parametrar

param
InputMessagesParam

Returer

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Normaliserar en OutputMessagesParam till en versionsomslutning OutputMessages .

  • string / string[] → konverteras till OutputMessage[] och omsluts
  • OutputMessages → returnerade as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

Parametrar

param
OutputMessagesParam

Returer

OutputMessages

resetLogger()

Återställ till standardkonsolloggaren (främst för testning)

function resetLogger()

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

Kör en funktion i en kontext som bär exporttoken per begäran. Detta behåller endast token i OTel Context (ALS), aldrig i något register.

Token kan uppdateras senare innan updateExportToken() spårningen töms – användbart när återanropet är tidskrävande och den ursprungliga token kan upphöra att gälla före export.

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

Parametrar

token

string

fn

() => T

Returer

T

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

Extraherar spårningskontext från inkommande HTTP-huvuden och kör återanropet i den kontexten. Alla intervall som skapas i återanropet överordnas till den extraherade spårningen.

Exempel

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

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

Parametrar

headers
HeadersCarrier

De inkommande HTTP-begäranderubrikerna som innehåller traceparent/tracestate.

callback

() => T

Funktionen som ska köras i den extraherade kontexten.

Returer

T

Resultatet av återanropet.

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

Kör en motringningsfunktion i en kontext som har en explicit överordnad span-referens. Detta är användbart för att skapa underordnade intervall i asynkrona återanrop där kontextspridningen bryts.

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

Parametrar

parent
ParentSpanRef

Referens för överordnat intervall

callback

() => T

Funktionen som ska köras med den överordnade kontexten

Returer

T

Resultatet av återanropet

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

Säkerställer att värdet alltid är en JSON-parsningsbar sträng.

  • Objekt serialiseras via JSON.stringify.
  • Strängar som redan är giltiga JSON-objekt/matriser skickas igenom.
  • Alla andra strängar (inklusive bare JSON-primitiver) är omslutna: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Parametrar

value

string | Record<string, unknown>

Värdet som ska serialiseras.

key

string

Nyckeln som ska användas när du omsluter en vanlig sträng.

Returer

string

serializeMessages(InputMessages | OutputMessages)

Serialiserar ett versionshanterat meddelandeomslutning till JSON.

Utdata är det fullständiga omslutningsobjektet: {"version":"0.1.0","messages":[...]}.

Try/catch säkerställer att telemetriinspelningen inte genererar även när meddelandedelar innehåller värden som inte är JSON-serialiserbara (t.ex. BigInt, cirkulära refs).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Parametrar

wrapper

InputMessages | OutputMessages

Returer

string

setLogger(ILogger)

Ange en anpassad loggningsimplementering för observerbarhets-SDK:t

Exempel 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)

Parametrar

customLogger
ILogger

Implementeringen av anpassad loggning

updateExportToken(string)

Uppdatera exporttoken i den aktiva OTel-kontexten. Anropa detta för att uppdatera token innan du avslutar rotintervallet när den ursprungliga token kan ha upphört att gälla under en tidskrävande begäran.

Måste anropas inom samma asynkrona kontext som skapas av runWithExportToken.

function updateExportToken(token: string): boolean

Parametrar

token

string

Den nya token som ska användas för export.

Returer

boolean

sant om token uppdaterades korrekt, falskt om ingen tokenhållare hittades.

Variabelinformation

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Typ

string

defaultObservabilityConfigurationProvider

Delad standardprovider för ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Typ

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Delad standardprovider för PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Typ

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Standardloggerinstans för bakåtkompatibilitet. Delegerar till den globala loggaren som kan ersättas via setLogger().

logger: ILogger

Typ

ILogger