@microsoft/agents-a365-observability package
Klassen
| Agent365ExporterOptions |
Maximum aantal spanten per exportbatch. |
| BaggageBuilder |
Per aanvraag bagagebouwer voor doorgifte van openTelemetry-context. Deze klasse biedt een fluent-API voor het instellen van bagagewaarden die worden doorgegeven in de OpenTelemetry-context. Voorbeeld
|
| BaggageScope |
Contextmanager voor bagagebereik. Deze klasse beheert de levenscyclus van bagagewaarden, stelt deze in bij het invoeren en herstellen van de vorige context bij het afsluiten. |
| Builder |
Opbouwfunctie voor het configureren van Agent 365 met OpenTelemetry-tracering |
| ExecuteToolScope |
Biedt openTelemetry-traceringsbereik voor uitvoeringsbewerkingen van AI-hulpprogramma's. |
| InferenceScope |
Biedt openTelemetry-traceringsbereik voor generatieve AI-deductiebewerkingen. |
| InvokeAgentScope |
Biedt openTelemetry-traceringsbereik voor aanroepbewerkingen voor AI-agents. |
| ObservabilityConfiguration |
Configuratie voor waarneembaarheidspakket. Neemt runtime-instellingen over en voegt waarneembaarheidsspecifieke instellingen toe. |
| ObservabilityManager |
Hoofdinvoerpunt voor Agent 365 die OpenTelemetry-tracering biedt voor AI-agents en -hulpprogramma's |
| OpenTelemetryConstants |
OpenTelemetry-constanten voor Agent 365 |
| OpenTelemetryScope |
Basisklasse voor OpenTelemetry-traceringsbereiken |
| OutputScope |
Biedt openTelemetry-traceringsbereik voor tracering van uitvoerberichten met bovenliggende spankoppeling. |
| PerRequestSpanProcessorConfiguration |
Configuratie voor PerRequestSpanProcessor. Neemt runtime-instellingen (clusterCategory, isNodeEnvDevelopment) over en voegt processorbeveiligingen per aanvraag toe. Dit is gescheiden van ObservabilityConfiguration omdat PerRequestSpanProcessor alleen wordt gebruikt in specifieke scenario's en deze instellingen mogen niet worden weergegeven in de algemene ObservabilityConfiguration. |
Interfaces
| AgentDetails |
Details over een AI-agent |
| BlobPart |
Inline binaire gegevens (base64-gecodeerd). |
| BuilderOptions |
Configuratieopties voor Agent 365 Observability Builder |
| CallerDetails |
Details van beller voor het maken van een bereik. Ondersteunt menselijke bellers, agentoproepers of beide (A2A met een mens in de keten).
Opmerking over migratie: In v1 verwijst de naam Zie UserDetails — identiteit voor menselijke aanroeper (eerder |
| Channel |
Vertegenwoordigt het kanaal voor een aanroep |
| ChatMessage |
Een invoerbericht dat wordt verzonden naar een model (semantische conventies van OTEL gen-ai). |
| FilePart |
Verwijzing naar een vooraf geüpload bestand. |
| GenericPart |
Uitbreidbaar onderdeel voor aangepaste/toekomstige typen. |
| GenericServerToolCall |
Uitbreidbare serverhulpprogramma roept details aan met een typediscriminator. |
| GenericServerToolCallResponse |
Uitbreidbaar serverhulpprogramma roept antwoord aan met een typediscriminator. |
| ILogger |
Aangepaste logboekinterface voor agent 365 waarneembaarheid Implementeer deze interface ter ondersteuning van back-ends voor logboekregistratie |
| InferenceDetails |
Details voor een deductieaanroep |
| InferenceResponse |
Details voor het opnemen van het antwoord van een deductieaanroep |
| InputMessages | |
| InvokeAgentScopeDetails |
Details voor het aanroepen van agentbereik. |
| OutputMessage |
Een uitvoerbericht dat wordt geproduceerd door een model (semantische conventies van OTEL gen-ai). |
| OutputMessages | |
| OutputResponse |
Vertegenwoordigt een antwoord met uitvoerberichten van een agent. Wordt gebruikt met OutputScope voor tracering van uitvoerberichten. Accepteert gewone tekenreeksen, gestructureerde OTEL OutputMessage-objecten of een onbewerkte dict (behandeld als een resultaat van een hulpprogramma-aanroep per OTEL-specificatie). |
| ParentSpanRef |
Verwijzing naar een bovenliggend bereik voor expliciete bovenliggende en onderliggende koppelingen tussen asynchrone grenzen. Wordt gebruikt wanneer automatische doorgifte van context mislukt (bijvoorbeeld WebSocket-callbacks, externe gebeurtenis-handlers). |
| ReasoningPart |
Modelredenering/ keten-van-gedachte-inhoud. |
| Request |
Vertegenwoordigt een aanvraag met telemetriecontext. Wordt gebruikt voor alle bereiktypen voor kanaal- en gesprekstracering. |
| ServerToolCallPart |
Aanroepen van hulpprogramma aan de serverzijde. |
| ServerToolCallResponsePart |
Reactie op het hulpprogramma aan de serverzijde. |
| ServiceEndpoint |
Vertegenwoordigt een eindpunt voor agentaanroep |
| SpanDetails |
Bespan de configuratiedetails voor het maken van een bereik. Groepen OpenTelemetry span options into a single object so the scope method signature blijft stabiel terwijl er nieuwe opties worden toegevoegd. |
| TextPart |
Tekst zonder opmaak. |
| ToolCallDetails |
Details van een aanroep van een hulpprogramma door een agent |
| ToolCallRequestPart |
Een door het model aangevraagde hulpprogramma-aanroep. |
| ToolCallResponsePart |
Resultaat van een aanroep van een hulpprogramma. |
| UriPart |
Externe URI-verwijzing. |
| UserDetails |
Details over de beller van de menselijke gebruiker. |
Type-aliassen
| EnhancedAgentDetails | |
| HeadersCarrier |
Type provider voor HTTP-headers die worden gebruikt bij traceringscontextdoorgifte. Compatibel met Node.js IncomingHttpHeaders en tekenreekstoewijzingen zonder opmaak. |
| InputMessagesParam |
Geaccepteerde invoer voor |
| MessagePart |
Samenvoeging van alle typen berichtenonderdelen per semantische conventies van OTEL gen-ai. Opmerking: GenericPart fungeert als een catch-all voor doorstuurcompatibiliteit met aangepaste of toekomstige onderdelentypen. Omdat het |
| ObservabilityConfigurationOptions |
Configuratieopties voor waarneembaarheid: breidt runtime-opties uit. Alle onderdrukkingen zijn functies die worden aangeroepen voor elke toegang tot eigenschappen. Overgenomen van RuntimeConfigurationOptions:
Opmerking: |
| OutputMessagesParam |
Geaccepteerde invoer voor |
| ParentContext |
Een bovenliggende context voor het maken van spanen. Accepteert ofwel:
|
| PerRequestSpanProcessorConfigurationOptions |
Configuratieopties voor PerRequestSpanProcessor - breidt runtime-opties uit. Alle onderdrukkingen zijn functies die worden aangeroepen voor elke toegang tot eigenschappen. Overgenomen van RuntimeConfigurationOptions:
|
| ResponseMessagesParam |
Geaccepteerde invoer voor |
Enums
| ExporterEventNames |
Gebeurtenisnamen die worden gebruikt door Agent365Exporter voor logboekregistratie en bewaking. Dit zijn gebeurtenistypen met lage kardinaliteit om efficiënte bewaking en aggregatie te garanderen. |
| FinishReason |
Reden waarom een model is gestopt met het genereren van semantische conventies per OTEL gen-ai. |
| InferenceOperationType |
Vertegenwoordigt verschillende bewerkingen voor typen voor modeldeductie |
| InvocationRole |
Vertegenwoordigt verschillende rollen die een agent kunnen aanroepen |
| MessageRole |
Rol van een deelnemer aan een bericht per semantische conventies van OTEL gen-ai. |
| Modality |
Mediamodale media voor blob-, bestands- en URI-onderdelen. |
Functies
| create |
Hiermee maakt u een nieuwe context met een expliciete bovenliggende spanreferentie. Hierdoor kunnen onderliggende spanen correct worden parented, zelfs wanneer de asynchrone context wordt verbroken. |
| extract |
Extraheert traceringscontext uit binnenkomende HTTP-headers met behulp van de wereldwijd geregistreerde W3C-doorgifte. Hiermee wordt een OTel ParentContext geretourneerd die als ParentContext kan worden doorgegeven aan bereikklassen. Voorbeeld
|
| format |
Foutobject opmaken voor logboekregistratie met bericht- en stacktracering |
| get |
Haal het exporttoken per aanvraag op uit een bepaalde OTel-context (of de actieve). |
| get |
Het huidige logboekregistratieexemplaren ophalen |
| inject |
Injecteert de huidige traceringscontext ( Voorbeeld
|
| is |
Controleer of export per aanvraag is ingeschakeld. Prioriteit: interne overschrijft omgevingsvariabele > van de configuratieprovider > . Als deze optie is ingeschakeld, wordt de PerRequestSpanProcessor gebruikt in plaats van BatchSpanProcessor. Het token wordt doorgegeven via OTel Context (asynchrone lokale opslag) tijdens de export. |
| normalize |
Normaliseert een
|
| normalize |
Normaliseert een
|
| reset |
Opnieuw instellen op de standaardconsolelogger (voornamelijk voor testen) |
| run |
Voer een functie uit binnen een context die het exporttoken per aanvraag bevat. Hierdoor blijft het token alleen in OTel Context (ALS), nooit in een register. Het token kan later |
| run |
Extraheert traceringscontext uit binnenkomende HTTP-headers en voert de callback uit binnen die context. Alle spanten die in de callback zijn gemaakt, worden bovenliggend aan de geëxtraheerde tracering. Voorbeeld
|
| run |
Voert een callback-functie uit binnen een context met een expliciete bovenliggende spanreferentie. Dit is handig voor het maken van onderliggende spanten in asynchrone callbacks waarbij contextdoorgifte wordt verbroken. |
| safe |
Zorgt ervoor dat de waarde altijd een JSON-parseerbare tekenreeks is.
|
| serialize |
Serialiseert een versie van een bericht-wrapper naar JSON. De uitvoer is het volledige wrapperobject: De try/catch zorgt ervoor dat telemetrie-opname niet genereert, zelfs wanneer berichtonderdelen niet-JSON-serialiseerbare waarden bevatten (bijvoorbeeld BigInt, kringverwijzingen). |
| set |
Een aangepaste logboekregistratie-implementatie instellen voor de waarneembaarheids-SDK Voorbeeld met Winston:
|
| update |
Werk het exporttoken bij in de actieve OTel-context. Roep dit aan om het token te vernieuwen voordat het hoofdbereik wordt beëindigd wanneer het oorspronkelijke token mogelijk is verlopen tijdens een langlopende aanvraag. Moet worden aangeroepen binnen dezelfde asynchrone context die is gemaakt door |
Variabelen
| A365_MESSAGE_SCHEMA_VERSION | |
| default |
Gedeelde standaardprovider voor ObservabilityConfiguration. |
| default |
Gedeelde standaardprovider voor PerRequestSpanProcessorConfiguration. |
| logger | Standaardloggerexemplaren voor achterwaartse compatibiliteit. Gemachtigden voor de globale logboekregistratie die kan worden vervangen via setLogger(). |
Functiedetails
createContextWithParentSpanRef(Context, ParentSpanRef)
Hiermee maakt u een nieuwe context met een expliciete bovenliggende spanreferentie. Hierdoor kunnen onderliggende spanen correct worden parented, zelfs wanneer de asynchrone context wordt verbroken.
function createContextWithParentSpanRef(base: Context, parent: ParentSpanRef): Context
Parameters
- base
-
Context
De basiscontext die moet worden uitgebreid (meestal context.active())
- parent
- ParentSpanRef
De bovenliggende naslaginformatie met traceId en spanId
Retouren
Context
Een nieuwe context met de bovenliggende spanset
extractContextFromHeaders(HeadersCarrier, Context)
Extraheert traceringscontext uit binnenkomende HTTP-headers met behulp van de wereldwijd geregistreerde W3C-doorgifte. Hiermee wordt een OTel ParentContext geretourneerd die als ParentContext kan worden doorgegeven aan bereikklassen.
Voorbeeld
const parentCtx = extractContextFromHeaders(req.headers);
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, undefined, { parentContext: parentCtx });
function extractContextFromHeaders(headers: HeadersCarrier, baseCtx?: Context): Context
Parameters
- headers
- HeadersCarrier
De binnenkomende HTTP-aanvraagheaders met traceparent/tracestate.
- baseCtx
-
Context
Optionele basiscontext om uit te breiden. De standaardinstelling is de actieve context.
Retouren
Context
Een OTel-context met de geëxtraheerde traceringsgegevens.
formatError(unknown)
Foutobject opmaken voor logboekregistratie met bericht- en stacktracering
function formatError(error: unknown): string
Parameters
- error
-
unknown
Retouren
string
getExportToken(Context)
Haal het exporttoken per aanvraag op uit een bepaalde OTel-context (of de actieve).
function getExportToken(ctx?: Context): string | undefined
Parameters
- ctx
-
Context
Retouren
string | undefined
getLogger()
injectContextToHeaders(Record<string, string>, Context)
Injecteert de huidige traceringscontext (traceparent/tracestate headers) in het opgegeven headers-object met behulp van de wereldwijd geregistreerde W3C-doorgifte.
Voorbeeld
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>
Parameters
- headers
-
Record<string, string>
Veranderlijk object waar traceringscontextheaders worden geschreven.
- ctx
-
Context
Optionele OTel-context waaruit moet worden geïnjecteerd. De standaardinstelling is de actieve context.
Retouren
Record<string, string>
Hetzelfde headers object, voor het koppelen van gemak.
isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)
Controleer of export per aanvraag is ingeschakeld. Prioriteit: interne overschrijft omgevingsvariabele > van de configuratieprovider > . Als deze optie is ingeschakeld, wordt de PerRequestSpanProcessor gebruikt in plaats van BatchSpanProcessor. Het token wordt doorgegeven via OTel Context (asynchrone lokale opslag) tijdens de export.
function isPerRequestExportEnabled(configProvider?: IConfigurationProvider<PerRequestSpanProcessorConfiguration>): boolean
Parameters
- configProvider
-
IConfigurationProvider<PerRequestSpanProcessorConfiguration>
Optionele configuratieprovider. Standaard ingesteld op defaultPerRequestSpanProcessorConfigurationProvider als deze niet is opgegeven.
Retouren
boolean
normalizeInputMessages(InputMessagesParam)
Normaliseert een InputMessagesParam naar een geversiede InputMessages wrapper.
-
string/string[]→ geconverteerd naarChatMessage[]en verpakt -
InputMessages→ geretourneerde as-is
function normalizeInputMessages(param: InputMessagesParam): InputMessages
Parameters
- param
- InputMessagesParam
Retouren
normalizeOutputMessages(OutputMessagesParam)
Normaliseert een OutputMessagesParam naar een geversiede OutputMessages wrapper.
-
string/string[]→ geconverteerd naarOutputMessage[]en verpakt -
OutputMessages→ geretourneerde as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages
Parameters
- param
- OutputMessagesParam
Retouren
resetLogger()
Opnieuw instellen op de standaardconsolelogger (voornamelijk voor testen)
function resetLogger()
runWithExportToken<T>(string, () => T)
Voer een functie uit binnen een context die het exporttoken per aanvraag bevat. Hierdoor blijft het token alleen in OTel Context (ALS), nooit in een register.
Het token kan later updateExportToken() worden bijgewerkt voordat de tracering wordt leeggemaakt, handig wanneer de callback lang actief is en het oorspronkelijke token kan verlopen voordat de export wordt uitgevoerd.
function runWithExportToken<T>(token: string, fn: () => T): T
Parameters
- token
-
string
- fn
-
() => T
Retouren
T
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)
Extraheert traceringscontext uit binnenkomende HTTP-headers en voert de callback uit binnen die context. Alle spanten die in de callback zijn gemaakt, worden bovenliggend aan de geëxtraheerde tracering.
Voorbeeld
runWithExtractedTraceContext(req.headers, () => {
const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
scope.dispose();
});
function runWithExtractedTraceContext<T>(headers: HeadersCarrier, callback: () => T): T
Parameters
- headers
- HeadersCarrier
De binnenkomende HTTP-aanvraagheaders met traceparent/tracestate.
- callback
-
() => T
De functie die moet worden uitgevoerd binnen de geëxtraheerde context.
Retouren
T
Het resultaat van de callback.
runWithParentSpanRef<T>(ParentSpanRef, () => T)
Voert een callback-functie uit binnen een context met een expliciete bovenliggende spanreferentie. Dit is handig voor het maken van onderliggende spanten in asynchrone callbacks waarbij contextdoorgifte wordt verbroken.
function runWithParentSpanRef<T>(parent: ParentSpanRef, callback: () => T): T
Parameters
- parent
- ParentSpanRef
De naslaginformatie over bovenliggende span
- callback
-
() => T
De functie die moet worden uitgevoerd met de bovenliggende context
Retouren
T
Het resultaat van de callback
safeSerializeToJson(string | Record<string, unknown>, string)
Zorgt ervoor dat de waarde altijd een JSON-parseerbare tekenreeks is.
- Objecten worden geserialiseerd via JSON.stringify.
- Tekenreeksen die al geldige JSON-objecten/matrices zijn, worden doorgegeven.
- Alle andere tekenreeksen (inclusief bare JSON-primitieven) worden verpakt:
{ [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string
Parameters
- value
-
string | Record<string, unknown>
De waarde die moet worden geserialiseerd.
- key
-
string
De sleutel die moet worden gebruikt bij het verpakken van een gewone tekenreeks.
Retouren
string
serializeMessages(InputMessages | OutputMessages)
Serialiseert een versie van een bericht-wrapper naar JSON.
De uitvoer is het volledige wrapperobject: {"version":"0.1.0","messages":[...]}.
De try/catch zorgt ervoor dat telemetrie-opname niet genereert, zelfs wanneer berichtonderdelen niet-JSON-serialiseerbare waarden bevatten (bijvoorbeeld BigInt, kringverwijzingen).
function serializeMessages(wrapper: InputMessages | OutputMessages): string
Parameters
- wrapper
Retouren
string
setLogger(ILogger)
Een aangepaste logboekregistratie-implementatie instellen voor de waarneembaarheids-SDK
Voorbeeld met 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)
Parameters
- customLogger
- ILogger
De implementatie van de aangepaste logboekregistratie
updateExportToken(string)
Werk het exporttoken bij in de actieve OTel-context. Roep dit aan om het token te vernieuwen voordat het hoofdbereik wordt beëindigd wanneer het oorspronkelijke token mogelijk is verlopen tijdens een langlopende aanvraag.
Moet worden aangeroepen binnen dezelfde asynchrone context die is gemaakt door runWithExportToken.
function updateExportToken(token: string): boolean
Parameters
- token
-
string
Het nieuwe token dat moet worden gebruikt voor export.
Retouren
boolean
waar als het token is bijgewerkt, onwaar als er geen tokenhouder is gevonden.
Variabele details
A365_MESSAGE_SCHEMA_VERSION
A365_MESSAGE_SCHEMA_VERSION: "0.1.0"
Type
string
defaultObservabilityConfigurationProvider
Gedeelde standaardprovider voor ObservabilityConfiguration.
defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>
Type
defaultPerRequestSpanProcessorConfigurationProvider
Gedeelde standaardprovider voor PerRequestSpanProcessorConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>
Type
logger
Standaardloggerexemplaren voor achterwaartse compatibiliteit. Gemachtigden voor de globale logboekregistratie die kan worden vervangen via setLogger().
logger: ILogger