@microsoft/agents-a365-observability package
מחלקות
| Agent365ExporterOptions |
המספר המרבי של טווחים לכל אצוות ייצוא. |
| BaggageBuilder |
בונה כבודה לבקשה להפצת הקשר OpenTelemetry. מחלקה זו מספקת API Fluent להגדרת ערכי כבודה אשר יופצו בהקשר OpenTelemetry. דוגמה
|
| BaggageScope |
מנהל הקשר לאחסון כבודה. כיתה זו מנהלת את מחזור החיים של ערכי כבודה, ומקשרת אותם להזנה ושחזור של ההקשר הקודם ביציאה. |
| Builder |
בונה לקביעת התצורה של סוכן 365 עם מעקב OpenTelemetry |
| ExecuteToolScope |
מספק טווח מעקב של OpenTelemetry עבור פעולות של ביצוע כלי בינה מלאכותית. |
| InferenceScope |
מספק טווח מעקב של OpenTelemetry עבור פעולות של מסתעפי בינה מלאכותית. |
| InvokeAgentScope |
מספק טווח מעקב של OpenTelemetry עבור פעולות בקשה של סוכן בינה מלאכותית. |
| ObservabilityConfiguration |
קביעת תצורה עבור חבילת יכולת התבוננות. קבלת הגדרות זמן ריצה בירושה והוספת הגדרות ספציפיות למצופה. |
| ObservabilityManager |
נקודת הכניסה הראשית עבור סוכן 365 המספק מעקב OpenTelemetry עבור סוכני בינה מלאכותית וכלים |
| OpenTelemetryConstants |
קבועי OpenTelemetry עבור סוכן 365 |
| OpenTelemetryScope |
מחלקת בסיס עבור טווחי מעקב של OpenTelemetry |
| OutputScope |
מתן טווח מעקב של OpenTelemetry עבור מעקב אחר הודעת פלט עם קישור טווח אב. |
| PerRequestSpanProcessorConfiguration |
קביעת תצורה עבור PerRequestSpanProcessor. מקבל בירושה הגדרות זמן ריצה (clusterCategory, isNodeEnvDevelopment) ומוסיף מעקות של מעבד לפי בקשה. פעולה זו מופרדת מ- ObservabilityConfiguration מכיוון ש- PerRequestSpanProcessor נמצא בשימוש בתרחישים ספציפיים בלבד, והגדרות אלה אינן אמורות להיות חשופות בתצורה הנפוצה של ObservabilityConfiguration. |
ממשקים
| AgentDetails |
פרטים על סוכן בינה מלאכותית |
| BlobPart |
נתונים בינאריים מוטבעים (בקידוד base64). |
| BuilderOptions |
אפשרויות תצורה עבור בונה התבוננות סוכן 365 |
| CallerDetails |
פרטי מתקשר עבור יצירת טווח. תומך במתקשרים אנושיים, סוכן מתקשרים או שניהם (A2A עם אדם בשרשרת).
הערת העברה: ב- v1 השם שנקרא ראה UserDetails – זהות מתקשר אנושית (בעבר |
| Channel |
מייצג ערוץ עבור בקשה |
| ChatMessage |
הודעת קלט שנשלחת למודל (מוסכמות סמנטיות של OTEL gen-ai). |
| FilePart |
הפניה לקובץ שהועלה מראש. |
| GenericPart |
חלק ניתן להרחבה עבור סוגים מותאמים אישית/עתידיים. |
| GenericServerToolCall |
פרטי קריאה לכלי שרת מורחבים עם מפריד סוגים. |
| GenericServerToolCallResponse |
תגובת קריאה לכלי שרת מורחב עם מפריד סוגים. |
| ILogger |
ממשק רישום מותאם אישית עבור יכולת התבוננות של סוכן 365 יישם ממשק זה כדי לתמוך בקצה העורפי של הרישום |
| InferenceDetails |
פרטים עבור שיחת מסקנה |
| InferenceResponse |
פרטים להקלטת התגובה מתוך שיחת מסקנה |
| InputMessages | |
| InvokeAgentScopeDetails |
פרטים עבור הפעלת טווח סוכן. |
| OutputMessage |
הודעת פלט שיוצר מודל (מוסכמות סמנטיות OTEL gen-ai). |
| OutputMessages | |
| OutputResponse |
מייצג תגובה המכילה הודעות פלט מסוכן. משמש עם OutputScope עבור מעקב אחר הודעת פלט. קבלת מחרוזות רגילות, אובייקטי OTEL OutputMessage מובנים או דיקט גולמי (נחשבים כתוצאת קריאה לכלי לכל מפרט OTEL). |
| ParentSpanRef |
הפניה לטווח אב לקבלת קישור אב-צאצא מפורש בין גבולות אסינכרוניים. משמש כאשר הפצת הקשר אוטומטית נכשלת (לדוגמה, התקשרויות חזרה של WebSocket, מטפלים באירועים חיצוניים). |
| ReasoningPart |
התחשבות במודלים/ תוכן של שרשרת מחשבה. |
| Request |
מייצג בקשה עם הקשר מדידת שימוש. משמש בכל סוגי הטווחים עבור מעקב אחר ערוצים ושיחות. |
| ServerToolCallPart |
בקשת כלי בצד השרת. |
| ServerToolCallResponsePart |
תגובת כלי בצד השרת. |
| ServiceEndpoint |
מייצג נקודת קצה עבור בקשת סוכן |
| SpanDetails |
Span configuration details for scope creation. קבוצות אפשרויות טווח OpenTelemetry לאובייקט יחיד כך שחתימה של פעולת השירות של הטווח נשארת יציבה בעת הוספת אפשרויות חדשות. |
| TextPart |
תוכן טקסט רגיל. |
| ToolCallDetails |
פרטים של שיחת כלי שבוצעה על-ידי סוכן |
| ToolCallRequestPart |
קריאה לכלי המבוקשת על-ידי המודל. |
| ToolCallResponsePart |
תוצאה של שיחת כלי. |
| UriPart |
הפניה ל- URI חיצוני. |
| UserDetails |
פרטים על מתקשר המשתמש האנושי. |
כינויי סוג
| EnhancedAgentDetails | |
| HeadersCarrier |
סוג ספק שירות עבור כותרות HTTP המשמשות להפצת הקשר מעקב. תואם למפות Node.js נכנסותHttpHeaders ומפות מחרוזות רגילות. |
| InputMessagesParam |
קלט מקובל עבור |
| MessagePart |
איחוד של כל סוגי חלקי ההודעות לכל מוסכמות סמנטיות gen-ai של OTEL. הערה: GenericPart פועל כ- catch-all לצורך תאימות קדימה עם סוגי חלקים מותאמים אישית או עתידיים. מאחר שהיא |
| ObservabilityConfigurationOptions |
אפשרויות תצורת התבוננות - מרחיב את אפשרויות זמן הריצה. כל העקיפות הן פונקציות שנקראות בכל גישה למאפיין. עובר בירושה מ- RuntimeConfigurationOptions:
הערה: |
| OutputMessagesParam |
קלט מקובל עבור |
| ParentContext |
הקשר אב ליצירת טווח. קבלת אחת מהפעולות הבאות:
|
| PerRequestSpanProcessorConfigurationOptions |
אפשרויות תצורה עבור PerRequestSpanProcessor - מרחיב את אפשרויות זמן הריצה. כל העקיפות הן פונקציות שנקראות בכל גישה למאפיין. עובר בירושה מ- RuntimeConfigurationOptions:
|
| ResponseMessagesParam |
קלט מקובל עבור |
ערכי Enum
| ExporterEventNames |
שמות אירועים המשמשים את Agent365Exporter לרישום ולניטור. אלה הם סוגי אירועים עם מספר מונה נמוך כדי להבטיח ניטור וצבירה יעילים. |
| FinishReason |
הסיבה לכך שמודל הפסיק ליצור לפי מוסכמות סמנטיות gen-ai של OTEL. |
| InferenceOperationType |
מייצג פעולה שונה עבור סוגים עבור מסיקה של מודל |
| InvocationRole |
מייצג תפקידים שונים ה יכולים להפעיל סוכן |
| MessageRole |
תפקיד של משתתף בהודעה לכל מוסכמות סמנטיות של OTEL gen-ai. |
| Modality |
מודליות מדיה עבור חלקי Blob, קובץ ו- URI. |
פונקציות
| create |
יצירת הקשר חדש עם הפניה מפורשת לטווח אב. הדבר מאפשר לצאצא להתפרס להיות הורה כראוי גם כאשר הקשר אסינכרוני מנותק. |
| extract |
חילוץ הקשר מעקב מכותרות HTTP נכנסות באמצעות מפץ W3C הרשום באופן כללי. החזרת OTel ParentContext שניתן להעביר למחלקות טווח כ- ParentContext. דוגמה
|
| format |
עיצוב אובייקט שגיאה לרישום באמצעות מעקב אחר הודעות ומחסנית |
| get |
אחזר את אסימון הייצוא לפי בקשה מהקשר OTel נתון (או מהאסימוני הפעיל). |
| get |
קבל את מופע הרישום הנוכחי |
| inject |
הכנסת הקשר המעקב הנוכחי ( דוגמה
|
| is |
בדוק אם ייצוא לפי בקשה זמין. קדימות: פנימי עוקף משתנה > סביבה של > ספק תצורה. כאשר אפשרות זו זמינה, ה- PerRequestSpanProcessor נמצא בשימוש במקום BatchSpanProcessor. האסימון מועבר דרך OTel Context (אחסון מקומי אסינכרוני) בזמן הייצוא. |
| normalize |
נורמליזציה של
|
| normalize |
נורמליזציה של
|
| reset |
איפוס לרישום המסוף המוגדר כברירת מחדל (בעיקר לבדיקה) |
| run |
הפעל פונקציה בתוך הקשר שנושאת את אסימון הייצוא לפי בקשה. פעולה זו שומרת את האסימון רק בהקשר OTel (ALS), לעולם לא ברישום כלשהו. ניתן לעדכן את האסימון |
| run |
חילוץ הקשר מעקב מכותרות HTTP נכנסות והפעלת ההתקשרות חזרה בתוך הקשר זה. כל התפרסיות שנוצרו בתוך ההתקשרות חזרה יופעלו למעקב שחולץ. דוגמה
|
| run |
הפעלת פונקציית התקשרות חזרה בהקשר בעל הפניה מפורשת לטווח אב. אפשרות זו שימושית ליצירת טווחי צאצא בהתכתבות חזרה אסינכרונית שבהן הפצת ההקשר מנותקת. |
| safe |
מבטיח שהערך יהיה תמיד מחרוזת הניתנת לניתוח JSON.
|
| serialize |
עריכה בסידרה של עטיפת הודעה מגירסה ל- JSON. הפלט הוא אובייקט העטיפה המלא: ה-try/catch מבטיח שהקלטת מדידת שימוש אינה מתזתת גם כאשר חלקי הודעה מכילים ערכים שאינם ניתנים לעריכה בסידרה של JSON (לדוגמה, BigInt, קבצי refs מעגליים). |
| set |
הגדרת יישום רישום מותאם אישית עבור ערכת ה- SDK של יכולת התצפית דוגמה עם וינסטון:
|
| update |
עדכן את אסימון הייצוא בהקשר OTel הפעיל. קרא לזה כדי לרענן את האסימון לפני סיום טווח הבסיס כאשר ייתכן שתוקפו של האסימון המקורי פג במהלך בקשה ארוכת טווח. יש לבצע קריאה לאותו הקשר אסינכרוני שנוצר על-ידי |
משתנים
| A365_MESSAGE_SCHEMA_VERSION | |
| default |
ספק ברירת מחדל משותף עבור ObservabilityConfiguration. |
| default |
ספק ברירת מחדל משותף עבור 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()
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>
אובייקט מ Mutable שבו ייכתבו כותרות הקשר של מעקב.
- ctx
-
Context
אופציונלי OTel Context to inject from. ברירות מחדל להקשר הפעיל.
החזרות
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
החזרות
normalizeOutputMessages(OutputMessagesParam)
נורמליזציה של OutputMessagesParam עטיפת גירסה OutputMessages .
-
string/string[]→ מומרות לפריטיםOutputMessage[]עם גלישה -
OutputMessages→ הוחזר as-is
function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages
פרמטרים
- param
- OutputMessagesParam
החזרות
resetLogger()
איפוס לרישום המסוף המוגדר כברירת מחדל (בעיקר לבדיקה)
function resetLogger()
runWithExportToken<T>(string, () => T)
הפעל פונקציה בתוך הקשר שנושאת את אסימון הייצוא לפי בקשה. פעולה זו שומרת את האסימון רק בהקשר OTel (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, קבצי refs מעגליים).
function serializeMessages(wrapper: InputMessages | OutputMessages): string
פרמטרים
- wrapper
החזרות
string
setLogger(ILogger)
הגדרת יישום רישום מותאם אישית עבור ערכת ה- SDK של יכולת התצפית
דוגמה עם וינסטון:
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>
סוג נתונים
defaultPerRequestSpanProcessorConfigurationProvider
ספק ברירת מחדל משותף עבור PerRequestSpanProcessorConfiguration.
defaultPerRequestSpanProcessorConfigurationProvider: DefaultConfigurationProvider<PerRequestSpanProcessorConfiguration>
סוג נתונים
logger
מופע ברירת המחדל של הרישום לצורך תאימות לאחור. נציגים לרישום הכללי שניתן להחליף באמצעות setLogger().
logger: ILogger