@microsoft/agents-a365-observability package

Κλάσεις

Agent365ExporterOptions

Μέγιστος αριθμός διαχέσεων ανά δέσμη εξαγωγής.
BaggageBuilder

Ανά αίτηση εργαλείου δόμησης αποσκευών για τη μετάδοση περιβάλλοντος OpenTelemetry.

Αυτή η κλάση παρέχει ένα ευφράδειο API για τον ορισμό τιμών αποσκευών που θα μεταδοθούν στο περιβάλλον OpenTelemetry.

Παράδειγμα

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

Διαχείριση περιβάλλοντος για εμβέλεια αποσκευών.

Αυτή η κλάση διαχειρίζεται τον κύκλο ζωής των τιμών αποσκευών, ρυθμίζοντας τις κατά την είσοδο και την επαναφορά του προηγούμενου περιβάλλοντος κατά την έξοδο.
Builder

Builder για τη ρύθμιση παραμέτρων του Παράγοντα 365 με ανίχνευση OpenTelemetry
ExecuteToolScope

Παρέχει εμβέλεια ανίχνευσης OpenTelemetry για λειτουργίες εκτέλεσης εργαλείων AI.
InferenceScope

Παρέχει εμβέλεια ανίχνευσης OpenTelemetry για λειτουργίες δημιουργίας συμπερασματολογικών στοιχείων AI.
InvokeAgentScope

Παρέχει εμβέλεια ανίχνευσης OpenTelemetry για λειτουργίες κλήσης παράγοντα AI.
ObservabilityConfiguration

Ρύθμιση παραμέτρων για το πακέτο παρατηρησιμότητας. Μεταβιβάζονται οι ρυθμίσεις χρόνου εκτέλεσης και οι ρυθμίσεις που αφορούν την παρατηρησιμότητα.
ObservabilityManager

Κύριο σημείο εισόδου του Agent 365 για την παροχή ανίχνευσης OpenTelemetry για πράκτορες και εργαλεία AI
OpenTelemetryConstants

Σταθερές OpenTelemetry για τον Παράγοντα 365
OpenTelemetryScope

Βασική κλάση για εμβέλειες ανίχνευσης OpenTelemetry
OutputScope

Παρέχει εμβέλεια ανίχνευσης OpenTelemetry για ανίχνευση μηνύματος εξόδου με σύνδεση γονικού εύρους.
PerRequestSpanProcessorConfiguration

Ρύθμιση παραμέτρων για PerRequestSpanProcessor. Κληρονομεί τις ρυθμίσεις χρόνου εκτέλεσης (clusterCategory, isNodeEnvDevelopment) και προσθέτει προστατευτικά επεξεργαστή ανά αίτηση.

Αυτό διαχωρίζεται από την ObservabilityConfiguration, επειδή το PerRequestSpanProcessor χρησιμοποιείται μόνο σε συγκεκριμένα σενάρια και αυτές οι ρυθμίσεις δεν πρέπει να εκτίθενται στη συνήθη ObservabilityConfiguration.

Διασυνδέσεις

AgentDetails

Λεπτομέρειες σχετικά με έναν πράκτορα AI
BlobPart

Ενσωματωμένα δυαδικά δεδομένα (με κωδικοποίηση base64).
BuilderOptions

Επιλογές ρύθμισης παραμέτρων για το Εργαλείο δόμησης παρατηρήσεων του Παράγοντα 365
CallerDetails

Λεπτομέρειες κλήσης για δημιουργία εμβέλειας. Υποστηρίζει ανθρώπους καλούντες, υπεύθυνους κλήσης αντιπροσώπων ή και τα δύο (A2A με έναν άνθρωπο στην αλυσίδα).

Σημείωση μετεγκατάστασης: Στην v1 το όνομα CallerDetails αναφέρεται στην ταυτότητα υπεύθυνου κλήσης (τώρα UserDetails). Στην έκδοση v2, επανατοποθετήθηκε ως περιτύλιξη που ομαδοποιεί πληροφορίες τόσο για ανθρώπους όσο και για τους καλούντες παράγοντα.

Ανατρέξτε στην ενότητα UserDetails — ταυτότητα υπεύθυνου κλήσης (προηγουμένως CallerDetails) Ανατρέξτε στην ενότητα CHANGELOG.md — κατάργηση αλλαγών για οδηγίες μετεγκατάστασης
Channel

Αντιπροσωπεύει το κανάλι για κλήση
ChatMessage

Ένα μήνυμα εισόδου που αποστέλλεται σε ένα μοντέλο (σημασιολογικές συμβάσεις gen-ai του OTEL).
FilePart

Αναφορά σε ένα αρχείο που έχει αποσταλεί εκ των προτέρων.
GenericPart

Επεκτάσιμο τμήμα για προσαρμοσμένους / μελλοντικούς τύπους.
GenericServerToolCall

Λεπτομέρειες κλήσης εργαλείου διακομιστή με διάκριση τύπων.
GenericServerToolCallResponse

Επεκτάσιμη απόκριση κλήσης εργαλείου διακομιστή με διάκριση τύπου.
ILogger

Προσαρμοσμένη διασύνδεση καταγραφής για την παρατηρησιμότητα agent 365 Εφαρμόστε αυτή τη διασύνδεση για την υποστήριξη παρασκηνίων καταγραφής
InferenceDetails

Λεπτομέρειες για μια κλήση συμπεραίωσης
InferenceResponse

Λεπτομέρειες για την εγγραφή της απόκρισης από μια κλήση συμπερασημάτων
InputMessages
InvokeAgentScopeDetails

Λεπτομέρειες για την κλήση εμβέλειας παράγοντα.
OutputMessage

Ένα μήνυμα εξόδου που παράγεται από ένα μοντέλο (σημασιολογικές συμβάσεις gen-ai του OTEL).
OutputMessages
OutputResponse

Αντιπροσωπεύει μια απόκριση που περιέχει μηνύματα εξόδου από έναν παράγοντα. Χρησιμοποιείται με την OutputScope για την ανίχνευση μηνυμάτων εξόδου. Δέχεται απλές συμβολοσειρές, δομημένα αντικείμενα OTEL OutputMessage ή ανεπεξέργαστο dict (αντιμετωπίζονται ως αποτέλεσμα κλήσης εργαλείου ανά προδιαγραφή OTEL).
ParentSpanRef

Αναφορά σε γονικό εύρος για ρητή σύνδεση γονικού-θυγατρικού στοιχείου σε ασύγχρονα όρια. Χρησιμοποιείται όταν αποτυγχάνει η αυτόματη μετάδοση περιβάλλοντος (π.χ. επιστροφές κλήσης WebSocket, εξωτερικά χειρισμούς συμβάντων).
ReasoningPart

Λογική μοντέλου / περιεχόμενο αλυσίδας σκέψης.
Request

Αντιπροσωπεύει μια αίτηση με περιβάλλον τηλεμετρίας. Χρησιμοποιείται σε όλους τους τύπους εμβέλειας για παρακολούθηση καναλιού και συνομιλίας.
ServerToolCallPart

Κλήση εργαλείου από την πλευρά του διακομιστή.
ServerToolCallResponsePart

Απόκριση εργαλείου από την πλευρά του διακομιστή.
ServiceEndpoint

Αντιπροσωπεύει ένα τελικό σημείο για κλήση παράγοντα
SpanDetails

Λεπτομέρειες ρύθμισης παραμέτρων για τη δημιουργία εμβέλειας. Οι επιλογές εύρους Ομάδων OpenTelemetry εκτείνονται σε ένα μοναδικό αντικείμενο, ώστε η υπογραφή της μεθόδου εμβέλειας να παραμένει σταθερή καθώς προστίθενται νέες επιλογές.
TextPart

Περιεχόμενο απλού κειμένου.
ToolCallDetails

Λεπτομέρειες μιας κλήσης εργαλείου που πραγματοποιήθηκε από έναν πράκτορα
ToolCallRequestPart

Μια κλήση εργαλείου που ζητήθηκε από το μοντέλο.
ToolCallResponsePart

Αποτέλεσμα μιας κλήσης εργαλείου.
UriPart

Εξωτερική αναφορά URI.
UserDetails

Λεπτομέρειες σχετικά με τον καλούντα χρήστη.

Ψευδώνυμα τύπου

EnhancedAgentDetails
HeadersCarrier

Τύπος φορέα για κεφαλίδες HTTP που χρησιμοποιούνται στη μετάδοση περιβάλλοντος ανίχνευσης. Συμβατό με Node.js IncomingHttpHeaders και απλούς χάρτες συμβολοσειρών.
InputMessagesParam

Αποδοχή εισόδου για recordInputMessages. Υποστηρίζει μία συμβολοσειρά, έναν πίνακα συμβολοσειρών (προς τα πίσω compat) ή το περιτύλιγμα έκδοσης.
MessagePart

Ένωση όλων των τύπων τμημάτων μηνυμάτων ανά σημασιολογικό συμβάσεις gen-ai του OTEL.

Σημείωση: Το GenericPart λειτουργεί ως catch-all για συμβατότητα προς τα εμπρός με προσαρμοσμένους ή μελλοντικούς τύπους ανταλλακτικών. Επειδή είναι type (δεν είναι string λεκτική σταθερά), η εξαντλητικήswitch/caseενεργοποίηση part.type δεν θα παράγει σφάλματα χρόνου μεταγλώττισης για περιπτώσεις χωρίςχειρίωση.
ObservabilityConfigurationOptions

Επιλογές ρύθμισης παραμέτρων παρατηρησιμότητας - επεκτείνει τις επιλογές χρόνου εκτέλεσης. Όλες οι παρακάμψεις είναι συναρτήσεις που καλούνται σε κάθε πρόσβαση ιδιότητας.

Μεταβίβαση από το RuntimeConfigurationOptions:

  • clusterCategory
  • isNodeEnvDevelopment

Σημείωση: isDevelopmentEnvironment το είναι μια παραγόμενη παράμετρος getter στην κλάση ρύθμισης παραμέτρων (με βάση το clusterCategory) και όχι μια επιλογή με δυνατότητα παράκαμψης.
OutputMessagesParam

Αποδοχή εισόδου για recordOutputMessages. Υποστηρίζει μία συμβολοσειρά, έναν πίνακα συμβολοσειρών (προς τα πίσω compat) ή το περιτύλιγμα έκδοσης.
ParentContext

Ένα γονικό περιβάλλον για δημιουργία εύρους. Αποδέχεται οποιοδήποτε από τα εξής:
PerRequestSpanProcessorConfigurationOptions

Επιλογές ρύθμισης παραμέτρων για PerRequestSpanProcessor - επεκτείνει τις επιλογές χρόνου εκτέλεσης. Όλες οι παρακάμψεις είναι συναρτήσεις που καλούνται σε κάθε πρόσβαση ιδιότητας.

Μεταβίβαση από το RuntimeConfigurationOptions:

  • clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam

Αποδοχή εισόδου για OutputResponse.messages. Υποστηρίζει απλές συμβολοσειρές, δομημένα OutputMessages ή ένα ανεπεξέργαστο διάταγμα (που αντιμετωπίζεται ως αποτέλεσμα κλήσης εργαλείου ανά προδιαγραφή OTEL και σειριοποιείται απευθείας μέσω JSON.stringify).

Απαριθμήσεις

ExporterEventNames

Ονόματα συμβάντων που χρησιμοποιούνται από το Agent365Exporter για καταγραφή και παρακολούθηση. Πρόκειται για τύπους συμβάντων χαμηλής πληθικότητας για την εξασφάλιση αποτελεσματικής παρακολούθησης και συνάθροισης.
FinishReason

Αιτία που ένα μοντέλο σταμάτησε να δημιουργεί σύμφωνα με σημασιολογικές συμβάσεις gen-ai του OTEL.
InferenceOperationType

Αντιπροσωπεύει διαφορετική λειτουργία για τύπους για την συμπεραίωση μοντέλου
InvocationRole

Αντιπροσωπεύει διαφορετικούς ρόλους που μπορούν να καλούν έναν παράγοντα
MessageRole

Ο ρόλος ενός συμμετέχοντος μηνύματος ανά συμβάματα σημασιολογίας gen-ai του OTEL.
Modality

Συντελεστής πολυμέσων για τμήματα αντικειμένων blob, αρχείου και URI.

Συναρτήσεις

createContextWithParentSpanRef(Context, ParentSpanRef)

Δημιουργεί ένα νέο περιβάλλον με μια ρητή αναφορά γονικού εύρους. Αυτό επιτρέπει στα θυγατρικά τμήματα να έχουν σωστή γονική μέριμνα, ακόμα και όταν το ασύγχρονο περιβάλλον έχει διακοπεί.
extractContextFromHeaders(HeadersCarrier, Context)

Εξάγει περιβάλλον ανίχνευσης από εισερχόμενες κεφαλίδες HTTP χρησιμοποιώντας τον καθολικά καταχωρημένο πολλαπλασιαστή W3C. Επιστρέφει ένα OTel ParentContext που μπορεί να διαβιβαστεί σε κλάσεις εμβέλειας ως ParentContext.

Παράδειγμα

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

Μορφοποίηση αντικειμένου σφάλματος για καταγραφή με ανίχνευση μηνύματος και στοίβας
getExportToken(Context)

Ανακτήστε το διακριτικό εξαγωγής ανά αίτηση από ένα δεδομένο περιβάλλον OTel (ή το ενεργό).
getLogger()

Λήψη της τρέχουσας παρουσίας του αρχείου καταγραφής
injectContextToHeaders(Record<string, string>, Context)

Εγχέει το τρέχον περιβάλλον ανίχνευσης (traceparent/tracestate κεφαλίδες) στο αντικείμενο κεφαλίδων που παρέχεται, χρησιμοποιώντας τον καθολικά καταχωρημένο πολλαπλασιαστή W3C.

Παράδειγμα

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

Ελέγξτε εάν είναι ενεργοποιημένη η εξαγωγή ανά αίτηση. Προτεραιότητα: το εσωτερικό παρακάμπτει τη μεταβλητή περιβάλλοντος υπηρεσίας παροχής > ρύθμισης > παραμέτρων. Όταν ενεργοποιηθεί, χρησιμοποιείται το PerRequestSpanProcessor αντί για batchSpanProcessor. Το διακριτικό διαβιβάζεται μέσω του OTel Context (ασύγχρονος τοπικός χώρος αποθήκευσης) κατά τον χρόνο εξαγωγής.
normalizeInputMessages(InputMessagesParam)

Κανονικοποιεί ένα InputMessagesParam περιτύλιγμα σε έκδοση InputMessages .

  • string / string[] → που έχουν μετατραπεί σε ChatMessage[] και αναδιπλωθεί
  • InputMessages → as-is που επιστράφηκαν
normalizeOutputMessages(OutputMessagesParam)

Κανονικοποιεί ένα OutputMessagesParam περιτύλιγμα σε έκδοση OutputMessages .

  • string / string[] → που έχουν μετατραπεί σε OutputMessage[] και αναδιπλωθεί
  • OutputMessages → as-is που επιστράφηκαν
resetLogger()

Επαναφορά στον προεπιλεγμένο υπολογιστή καταγραφής κονσόλας (κυρίως για δοκιμή)
runWithExportToken<T>(string, () => T)

Εκτελέστε μια συνάρτηση μέσα σε ένα περιβάλλον που μεταφέρει το διακριτικό εξαγωγής ανά αίτηση. Με αυτόν τον τρόπο, το διακριτικό διατηρείται μόνο στο OTel Context (ALS) και ποτέ σε κανένα μητρώο.

Το διακριτικό μπορεί να ενημερωθεί αργότερα μέσω updateExportToken() της διαδικασίας εκκαθάρισης της ανίχνευσης — χρήσιμο όταν η επιστροφή κλήσης είναι μεγάλης διάρκειας και το αρχικό διακριτικό ενδέχεται να λήξει πριν την εξαγωγή.
runWithExtractedTraceContext<T>(HeadersCarrier, () => T)

Εξάγει περιβάλλον ανίχνευσης από εισερχόμενες κεφαλίδες HTTP και εκτελεί την επιστροφή κλήσης σε αυτό το περιβάλλον. Τυχόν τμήματα που θα δημιουργηθούν μέσα στην επιστροφή κλήσης θα μεταφερθούν στην ανίχνευση που έχει εξαχθεί.

Παράδειγμα

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

Εκτελεί μια συνάρτηση επιστροφής κλήσης μέσα σε ένα περιβάλλον που έχει ρητή γονική αναφορά εύρους. Αυτό είναι χρήσιμο για τη δημιουργία θυγατρικών περιστροφών σε ασύγχρονες επιστροφές κλήσης όπου η μετάδοση περιβάλλοντος έχει διακοπεί.
safeSerializeToJson(string | Record<string, unknown>, string)

Εξασφαλίζει ότι η τιμή είναι πάντα μια συμβολοσειρά με δυνατότητα ανάλυσης JSON.

  • Τα αντικείμενα σειριοποιούνται μέσω JSON.stringify.
  • Μεταβιβάζονται συμβολοσειρές που είναι ήδη έγκυρα αντικείμενα/πίνακες JSON.
  • Όλες οι άλλες συμβολοσειρές (συμπεριλαμβανομένων των γυμνών στοιχειών JSON) αναδιπλώνονται: { [key]: value }.
serializeMessages(InputMessages | OutputMessages)

Σειριοποιεί ένα πρόγραμμα περιτύλιξης μηνύματος σε JSON.

Το αποτέλεσμα είναι το πλήρες αντικείμενο περιτύλιξης: {"version":"0.1.0","messages":[...]}.

Το try/catch εξασφαλίζει ότι η εγγραφή τηλεμετρίας δεν πετάει ακόμη και όταν τα τμήματα του μηνύματος περιέχουν τιμές χωρίς δυνατότητα σειρών JSON (π.χ. BigInt, κυκλικοί διαιτητές).
setLogger(ILogger)

Ορισμός προσαρμοσμένης υλοποίησης καταγραφής για το SDK παρατηρησιμότητας

Παράδειγμα με τον 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)

Ενημερώστε το διακριτικό εξαγωγής στο ενεργό περιβάλλον OTel. Καλέστε το για να ανανεώσετε το διακριτικό πριν από τη λήξη του εύρους ρίζας, όταν το αρχικό διακριτικό ενδέχεται να έχει λήξει κατά τη διάρκεια μιας αίτησης μεγάλης διάρκειας.

Πρέπει να καλείται εντός του ίδιου περιβάλλοντος ασύγχρονης που δημιουργήθηκε από το runWithExportToken.

Μεταβλητές

A365_MESSAGE_SCHEMA_VERSION
defaultObservabilityConfigurationProvider

Κοινόχρηστη προεπιλεγμένη υπηρεσία παροχής για ObservabilityConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider

Κοινόχρηστη προεπιλεγμένη υπηρεσία παροχής για PerRequestSpanProcessorConfiguration.
logger

Προεπιλεγμένη παρουσία καταγραφής για συμβατότητα με προηγούμενες εκδόσεις. Αναθέσεις στον καθολικό λογαριθμό που μπορεί να αντικατασταθεί μέσω setLogger().

Λεπτομέρειες συνάρτησης

createContextWithParentSpanRef(Context, ParentSpanRef)

Δημιουργεί ένα νέο περιβάλλον με μια ρητή αναφορά γονικού εύρους. Αυτό επιτρέπει στα θυγατρικά τμήματα να έχουν σωστή γονική μέριμνα, ακόμα και όταν το ασύγχρονο περιβάλλον έχει διακοπεί.

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

Παράμετροι

base

Context

Το βασικό περιβάλλον για επέκταση (συνήθως context.active())

parent
ParentSpanRef

Η αναφορά γονικού εύρους που περιέχει traceId και spanId

Επιστροφές

Context

Ένα νέο περιβάλλον με καθορισμένο το γονικό εύρος

extractContextFromHeaders(HeadersCarrier, Context)

Εξάγει περιβάλλον ανίχνευσης από εισερχόμενες κεφαλίδες HTTP χρησιμοποιώντας τον καθολικά καταχωρημένο πολλαπλασιαστή W3C. Επιστρέφει ένα OTel ParentContext που μπορεί να διαβιβαστεί σε κλάσεις εμβέλειας ως ParentContext.

Παράδειγμα

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

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

Παράμετροι

headers
HeadersCarrier

Οι κεφαλίδες εισερχόμενης αίτησης HTTP που περιέχουν traceparent/tracestate.

baseCtx

Context

Προαιρετικό βασικό περιβάλλον για επέκταση. Η προεπιλογή είναι το ενεργό περιβάλλον.

Επιστροφές

Context

Ένα περιβάλλον OTel που περιέχει τις πληροφορίες ανίχνευσης που έχουν εξαχθεί.

formatError(unknown)

Μορφοποίηση αντικειμένου σφάλματος για καταγραφή με ανίχνευση μηνύματος και στοίβας

function formatError(error: unknown): string

Παράμετροι

error

unknown

Επιστροφές

string

getExportToken(Context)

Ανακτήστε το διακριτικό εξαγωγής ανά αίτηση από ένα δεδομένο περιβάλλον OTel (ή το ενεργό).

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

Παράμετροι

ctx

Context

Επιστροφές

string | undefined

getLogger()

Λήψη της τρέχουσας παρουσίας του αρχείου καταγραφής

function getLogger(): ILogger

Επιστροφές

ILogger

injectContextToHeaders(Record<string, string>, Context)

Εγχέει το τρέχον περιβάλλον ανίχνευσης (traceparent/tracestate κεφαλίδες) στο αντικείμενο κεφαλίδων που παρέχεται, χρησιμοποιώντας τον καθολικά καταχωρημένο πολλαπλασιαστή W3C.

Παράδειγμα

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>

Παράμετροι

headers

Record<string, string>

Αντικείμενο με δυνατότητα μετάλλαξης όπου θα εγγραφούν κεφαλίδες περιβάλλοντος ανίχνευσης.

ctx

Context

Προαιρετικό OTel Context για την έγχυση από. Η προεπιλογή είναι το ενεργό περιβάλλον.

Επιστροφές

Record<string, string>

Το ίδιο headers αντικείμενο, για λόγους ευκολίας σύνδεσης σε αλυσίδα.

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

Ελέγξτε εάν είναι ενεργοποιημένη η εξαγωγή ανά αίτηση. Προτεραιότητα: το εσωτερικό παρακάμπτει τη μεταβλητή περιβάλλοντος υπηρεσίας παροχής > ρύθμισης > παραμέτρων. Όταν ενεργοποιηθεί, χρησιμοποιείται το PerRequestSpanProcessor αντί για batchSpanProcessor. Το διακριτικό διαβιβάζεται μέσω του OTel Context (ασύγχρονος τοπικός χώρος αποθήκευσης) κατά τον χρόνο εξαγωγής.

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

Παράμετροι

configProvider

IConfigurationProvider<PerRequestSpanProcessorConfiguration>

Προαιρετική υπηρεσία παροχής ρύθμισης παραμέτρων. Η προεπιλεγμένη τιμή είναι defaultPerRequestSpanProcessorConfigurationProvider εάν δεν έχει καθοριστεί.

Επιστροφές

boolean

normalizeInputMessages(InputMessagesParam)

Κανονικοποιεί ένα InputMessagesParam περιτύλιγμα σε έκδοση InputMessages .

  • string / string[] → που έχουν μετατραπεί σε ChatMessage[] και αναδιπλωθεί
  • InputMessages → as-is που επιστράφηκαν
function normalizeInputMessages(param: InputMessagesParam): InputMessages

Παράμετροι

param
InputMessagesParam

Επιστροφές

InputMessages

normalizeOutputMessages(OutputMessagesParam)

Κανονικοποιεί ένα OutputMessagesParam περιτύλιγμα σε έκδοση OutputMessages .

  • string / string[] → που έχουν μετατραπεί σε OutputMessage[] και αναδιπλωθεί
  • OutputMessages → as-is που επιστράφηκαν
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

Παράμετροι

param
OutputMessagesParam

Επιστροφές

OutputMessages

resetLogger()

Επαναφορά στον προεπιλεγμένο υπολογιστή καταγραφής κονσόλας (κυρίως για δοκιμή)

function resetLogger()

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

Εκτελέστε μια συνάρτηση μέσα σε ένα περιβάλλον που μεταφέρει το διακριτικό εξαγωγής ανά αίτηση. Με αυτόν τον τρόπο, το διακριτικό διατηρείται μόνο στο OTel Context (ALS) και ποτέ σε κανένα μητρώο.

Το διακριτικό μπορεί να ενημερωθεί αργότερα μέσω updateExportToken() της διαδικασίας εκκαθάρισης της ανίχνευσης — χρήσιμο όταν η επιστροφή κλήσης είναι μεγάλης διάρκειας και το αρχικό διακριτικό ενδέχεται να λήξει πριν την εξαγωγή.

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

Παράμετροι

token

string

fn

() => T

Επιστροφές

T

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

Εξάγει περιβάλλον ανίχνευσης από εισερχόμενες κεφαλίδες HTTP και εκτελεί την επιστροφή κλήσης σε αυτό το περιβάλλον. Τυχόν τμήματα που θα δημιουργηθούν μέσα στην επιστροφή κλήσης θα μεταφερθούν στην ανίχνευση που έχει εξαχθεί.

Παράδειγμα

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

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

Παράμετροι

headers
HeadersCarrier

Οι κεφαλίδες εισερχόμενης αίτησης HTTP που περιέχουν traceparent/tracestate.

callback

() => T

Η συνάρτηση που θα εκτελεστεί στο περιβάλλον που έχει εξαχθεί.

Επιστροφές

T

Το αποτέλεσμα της επιστροφής κλήσης.

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

Εκτελεί μια συνάρτηση επιστροφής κλήσης μέσα σε ένα περιβάλλον που έχει ρητή γονική αναφορά εύρους. Αυτό είναι χρήσιμο για τη δημιουργία θυγατρικών περιστροφών σε ασύγχρονες επιστροφές κλήσης όπου η μετάδοση περιβάλλοντος έχει διακοπεί.

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

Παράμετροι

parent
ParentSpanRef

Η αναφορά γονικού εύρους

callback

() => T

Η συνάρτηση που θα εκτελεστεί με το γονικό περιβάλλον

Επιστροφές

T

Το αποτέλεσμα της επιστροφής κλήσης

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

Εξασφαλίζει ότι η τιμή είναι πάντα μια συμβολοσειρά με δυνατότητα ανάλυσης JSON.

  • Τα αντικείμενα σειριοποιούνται μέσω JSON.stringify.
  • Μεταβιβάζονται συμβολοσειρές που είναι ήδη έγκυρα αντικείμενα/πίνακες JSON.
  • Όλες οι άλλες συμβολοσειρές (συμπεριλαμβανομένων των γυμνών στοιχειών JSON) αναδιπλώνονται: { [key]: value }.
function safeSerializeToJson(value: string | Record<string, unknown>, key: string): string

Παράμετροι

value

string | Record<string, unknown>

Η τιμή προς σειριοποίηση.

key

string

Το κλειδί που θα χρησιμοποιηθεί κατά την περιτύλιξη μιας απλής συμβολοσειράς.

Επιστροφές

string

serializeMessages(InputMessages | OutputMessages)

Σειριοποιεί ένα πρόγραμμα περιτύλιξης μηνύματος σε JSON.

Το αποτέλεσμα είναι το πλήρες αντικείμενο περιτύλιξης: {"version":"0.1.0","messages":[...]}.

Το try/catch εξασφαλίζει ότι η εγγραφή τηλεμετρίας δεν πετάει ακόμη και όταν τα τμήματα του μηνύματος περιέχουν τιμές χωρίς δυνατότητα σειρών JSON (π.χ. BigInt, κυκλικοί διαιτητές).

function serializeMessages(wrapper: InputMessages | OutputMessages): string

Παράμετροι

wrapper

InputMessages | OutputMessages

Επιστροφές

string

setLogger(ILogger)

Ορισμός προσαρμοσμένης υλοποίησης καταγραφής για το SDK παρατηρησιμότητας

Παράδειγμα με τον 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)

Παράμετροι

customLogger
ILogger

Η υλοποίηση προσαρμοσμένου προγράμματος καταγραφής

updateExportToken(string)

Ενημερώστε το διακριτικό εξαγωγής στο ενεργό περιβάλλον OTel. Καλέστε το για να ανανεώσετε το διακριτικό πριν από τη λήξη του εύρους ρίζας, όταν το αρχικό διακριτικό ενδέχεται να έχει λήξει κατά τη διάρκεια μιας αίτησης μεγάλης διάρκειας.

Πρέπει να καλείται εντός του ίδιου περιβάλλοντος ασύγχρονης που δημιουργήθηκε από το runWithExportToken.

function updateExportToken(token: string): boolean

Παράμετροι

token

string

Το νέο διακριτικό που θα χρησιμοποιηθεί για εξαγωγή.

Επιστροφές

boolean

true εάν το διακριτικό ενημερώθηκε με επιτυχία, false εάν δεν βρέθηκε κάτοχος διακριτικού.

Λεπτομέρειες μεταβλητής

A365_MESSAGE_SCHEMA_VERSION 

A365_MESSAGE_SCHEMA_VERSION: "0.1.0"

Τύπος

string

defaultObservabilityConfigurationProvider

Κοινόχρηστη προεπιλεγμένη υπηρεσία παροχής για ObservabilityConfiguration.

defaultObservabilityConfigurationProvider: DefaultConfigurationProvider<ObservabilityConfiguration>

Τύπος

DefaultConfigurationProvider<ObservabilityConfiguration>

defaultPerRequestSpanProcessorConfigurationProvider

Κοινόχρηστη προεπιλεγμένη υπηρεσία παροχής για PerRequestSpanProcessorConfiguration.

defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

Τύπος

DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>

logger

Προεπιλεγμένη παρουσία καταγραφής για συμβατότητα με προηγούμενες εκδόσεις. Αναθέσεις στον καθολικό λογαριθμό που μπορεί να αντικατασταθεί μέσω setLogger().

logger: ILogger

Τύπος

ILogger