@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	ตัวสร้างสําหรับการกําหนดค่า Agent 365 ด้วยการติดตาม OpenTelemetry
ExecuteToolScope	ให้ขอบเขตการติดตาม OpenTelemetry สําหรับการดําเนินการของเครื่องมือ AI
InferenceScope	ให้ขอบเขตการติดตาม OpenTelemetry สําหรับการดําเนินการอนุมาน AI ที่สร้าง
InvokeAgentScope	ให้ขอบเขตการติดตาม OpenTelemetry สําหรับการดําเนินการเรียกใช้ตัวแทน AI
ObservabilityConfiguration	การกําหนดค่าสําหรับแพคเกจความสามารถในการสังเกตได้ สืบทอดการตั้งค่ารันไทม์และเพิ่มการตั้งค่าเฉพาะความสามารถในการสังเกตได้
ObservabilityManager	จุดเข้าใช้งานหลักสําหรับตัวแทน 365 ซึ่งให้บริการการติดตาม OpenTelemetry สําหรับตัวแทนและเครื่องมือ AI
OpenTelemetryConstants	ค่าคงที่ OpenTelemetry สําหรับ Agent 365
OpenTelemetryScope	ระดับฐานสําหรับขอบเขตการติดตาม OpenTelemetry
OutputScope	มีขอบเขตการติดตาม OpenTelemetry สําหรับการติดตามข้อความผลลัพธ์ที่มีการเชื่อมโยงขยายหลัก
PerRequestSpanProcessorConfiguration	การกําหนดค่าสําหรับ PerRequestSpanProcessor สืบทอดการตั้งค่ารันไทม์ (clusterCategory, isNodeEnvDevelopment) และเพิ่ม guardrails ตัวประมวลผลต่อคําขอ ซึ่งจะแยกจาก ObservabilityConfiguration เนื่องจาก PerRequestSpanProcessor จะใช้เฉพาะในสถานการณ์เฉพาะและไม่ควรแสดงการตั้งค่าเหล่านี้ใน ObservabilityConfiguration ทั่วไป

อินเทอร์เฟซ

AgentDetails	รายละเอียดเกี่ยวกับตัวแทน AI
BlobPart	ข้อมูลไบนารีแบบอินไลน์ (เข้ารหัส base64)
BuilderOptions	ตัวเลือกการกําหนดค่าสําหรับตัวสร้างความสามารถในการสังเกตการณ์ของตัวแทน 365
CallerDetails	รายละเอียดผู้โทรสําหรับการสร้างขอบเขต สนับสนุนการโทรของมนุษย์ ตัวแทนผู้โทร หรือทั้งสองอย่าง (A2A กับมนุษย์ในกลุ่ม) หมายเหตุการย้าย: ใน v1 ชื่อ `CallerDetails` ที่อ้างอิงถึงข้อมูลประจําตัวของผู้เรียกโดยมนุษย์ (ตอนนี้ UserDetails) ใน v2 จะได้รับการ repursed เป็น wrapper ที่จัดกลุ่มทั้งข้อมูลของมนุษย์และตัวแทนการโทร ดู UserDetails — ข้อมูลประจําตัวผู้โทรของมนุษย์ (ก่อนหน้านี้ `CallerDetails`) ดู CHANGELOG.md — ส่วนการเปลี่ยนแปลงสําหรับคําแนะนําการโยกย้าย
Channel	แสดงช่องสําหรับการเรียก
ChatMessage	ข้อความที่ป้อนเข้าที่ส่งไปยังแบบจําลอง (แบบแผนความหมายของ OTEL gen-ai)
FilePart	อ้างอิงไปยังไฟล์ที่อัปโหลดไว้ล่วงหน้า
GenericPart	ส่วนที่สามารถขยายได้สําหรับประเภทแบบกําหนดเอง / ในอนาคต
GenericServerToolCall	เครื่องมือเซิร์ฟเวอร์ที่ขยายได้เรียกรายละเอียดด้วยชนิดตัวแยกประเภท
GenericServerToolCallResponse	เครื่องมือเซิร์ฟเวอร์ที่ขยายได้เรียกการตอบสนองด้วยชนิดตัวแยกแยะ
ILogger	อินเทอร์เฟซตัวบันทึกแบบกําหนดเองสําหรับการสังเกตการณ์ Agent 365 ใช้อินเทอร์เฟซนี้เพื่อสนับสนุนการบันทึก Backend
InferenceDetails	รายละเอียดสําหรับการเรียกการอนุมาน
InferenceResponse	รายละเอียดสําหรับการบันทึกการตอบสนองจากการเรียกการอนุมาน
InputMessages
InvokeAgentScopeDetails	รายละเอียดสําหรับขอบเขตการเรียกตัวแทน
OutputMessage	ข้อความผลลัพธ์ที่สร้างขึ้นโดยแบบจําลอง (อนุมานความหมายของ OTEL gen-ai)
OutputMessages
OutputResponse	แสดงการตอบสนองที่มีข้อความเอาต์พุตจากตัวแทน ใช้กับ OutputScope สําหรับการติดตามข้อความผลลัพธ์ ยอมรับสตริงแบบธรรมดา วัตถุ OTEL OutputMessage ที่มีโครงสร้าง หรือคําสั่งดิบ (ถือว่าเป็นผลลัพธ์การเรียกใช้เครื่องมือต่อข้อมูลจําเพาะ 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` รองรับสตริงเดียว อาร์เรย์ของสตริง (เข้ากันย้อนหลัง) หรือ wrapper รุ่น
MessagePart	การรวมกันของส่วนของข้อความทั้งหมดสําหรับแต่ละแบบแผนความหมาย OTEL gen-ai หมายเหตุ: GenericPart ทําหน้าที่เป็น catch-all สําหรับความเข้ากันได้ไปข้างหน้ากับชนิดของส่วนที่กําหนดเองหรือในอนาคต เนื่องจากเป็น `type` (ไม่ใช่สัญพจน์) ใช้งาน`stringswitch`/`case`จะไม่ก่อให้เกิดข้อผิดพลาดในการคอมไพล์เวลาสําหรับกรณีที่ไม่สามารถจัดการได้`part.type`
ObservabilityConfigurationOptions	ตัวเลือกการกําหนดค่าความสามารถในการสังเกต - ขยายตัวเลือกรันไทม์ การแทนที่ทั้งหมดจะถูกเรียกบนการเข้าถึงคุณสมบัติแต่ละรายการ สืบทอดมาจากตัวเลือกการกําหนดค่ารันไทม์: clusterCategory isNodeEnvDevelopment หมายเหตุ: `isDevelopmentEnvironment` เป็น Getter ที่ได้รับมาบนคลาสการกําหนดค่า (ตาม clusterCategory) ไม่ใช่ตัวเลือกที่แทนที่ได้
OutputMessagesParam	ค่าป้อนเข้าที่ยอมรับสําหรับ`recordOutputMessages` รองรับสตริงเดียว อาร์เรย์ของสตริง (เข้ากันย้อนหลัง) หรือ wrapper รุ่น
ParentContext	บริบทหลักสําหรับการสร้างการขยาย ยอมรับอย่างใดอย่างหนึ่ง: ParentSpanRef: คู่ traceId/spanId ที่ชัดเจน (วิธีการแบบแมนวล) ParentContext: บริบท OTel โดยทั่วไปมาจาก extractContextFromHeaders หรือ `propagation.extract()`
PerRequestSpanProcessorConfigurationOptions	ตัวเลือกการกําหนดค่าสําหรับ PerRequestSpanProcessor - ขยายตัวเลือกรันไทม์ การแทนที่ทั้งหมดจะถูกเรียกบนการเข้าถึงคุณสมบัติแต่ละรายการ สืบทอดมาจากตัวเลือกการกําหนดค่ารันไทม์: clusterCategory, isNodeEnvDevelopment
ResponseMessagesParam	ค่าป้อนเข้าที่ยอมรับสําหรับ`OutputResponse.messages` รองรับสตริงแบบธรรมดา, OutputMessages ที่มีโครงสร้าง หรือคําสั่งดิบ (ถือว่าเป็นผลลัพธ์การเรียกใช้เครื่องมือต่อข้อมูลจําเพาะ OTEL และอนุกรมโดยตรงผ่าน JSON.stringify)

Enums

ExporterEventNames	ชื่อเหตุการณ์ที่ใช้โดย Agent365Exporter สําหรับการบันทึกและการตรวจสอบ เหล่านี้เป็นประเภทเหตุการณ์ที่มีคาร์ดินาลลิตี้ต่ําเพื่อให้แน่ใจว่ามีการตรวจสอบและการรวมที่มีประสิทธิภาพ
FinishReason	เหตุผลที่แบบจําลองหยุดการสร้างต่ออนุมานเชิงความหมายของ OTEL gen-ai
InferenceOperationType	แสดงการดําเนินการที่แตกต่างกันสําหรับชนิดสําหรับการอนุมานแบบจําลอง
InvocationRole	แสดงบทบาทที่แตกต่างกันที่สามารถเรียกใช้ตัวแทนได้
MessageRole	บทบาทของผู้เข้าร่วมข้อความต่อแบบแผนเชิงความหมายของ OTEL gen-ai
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 (ที่เก็บข้อมูลภายในเครื่อง async) ในเวลาการส่งออก
normalizeInputMessages(InputMessagesParam)	ปรับให้เป็นมาตรฐานตัวรวบ`InputMessagesParamInputMessages`ให้เป็นเวอร์ชัน `string` / `string[]` →ถูกแปลงเป็น `ChatMessage[]` และตัดคํา `InputMessages` →ส่งกลับ as-is
normalizeOutputMessages(OutputMessagesParam)	ปรับให้เป็นมาตรฐานตัวรวบ`OutputMessagesParamOutputMessages`ให้เป็นเวอร์ชัน `string` / `string[]` →ถูกแปลงเป็น `OutputMessage[]` และตัดคํา `OutputMessages` →ส่งกลับ as-is
resetLogger()	รีเซ็ตไปยังตัวบันทึกคอนโซลเริ่มต้น (ส่วนใหญ่สําหรับการทดสอบ)
runWithExportToken<T>(string, () => T)	เรียกใช้ฟังก์ชันภายในบริบทที่มีโทเค็นการส่งออกตามคําขอ ซึ่งเก็บโทเค็นเฉพาะในบริบท OTel (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 เอาต์พุตคือวัตถุ Wrapper แบบเต็ม: `{"version":"0.1.0","messages":[...]}` การลอง/ตรวจจับ ช่วยให้แน่ใจว่าการบันทึกการวัดและส่งข้อมูลทางไกลจะไม่ขว้างแม้ในส่วนของข้อความจะมีค่าที่ไม่ใช่ JSON -serializable (เช่น BigInt, circular refs)
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 ที่เลือกได้เพื่อใส่ข้อมูลเข้าไป ค่าเริ่มต้นเป็นบริบทที่ใช้งานอยู่

การส่งคืน

Record<string, string>

วัตถุเดียวกัน headers เพื่อความสะดวกในการเกี่ยวโยง

isPerRequestExportEnabled(IConfigurationProvider<PerRequestSpanProcessorConfiguration>)

ตรวจสอบว่ามีการเปิดใช้งานการส่งออกตามคําขอหรือไม่ ลําดับความสําคัญ: การแทนที่ภายในจะ > แทนที่ตัวแปรสภาพแวดล้อมของตัวให้บริการ > การกําหนดค่า เมื่อเปิดใช้งาน จะมีการใช้ PerRequestSpanProcessor แทน BatchSpanProcessor โทเค็นจะถูกส่งผ่านบริบท OTel (ที่เก็บข้อมูลภายในเครื่อง async) ในเวลาการส่งออก

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

พารามิเตอร์

configProvider: IConfigurationProvider<PerRequestSpanProcessorConfiguration>

ตัวให้บริการการกําหนดค่าทางเลือก ค่าเริ่มต้นเป็น defaultPerRequestSpanProcessorConfigurationProvider ถ้าไม่ได้ระบุ

การส่งคืน

boolean

normalizeInputMessages(InputMessagesParam)

ปรับให้เป็นมาตรฐานตัวรวบInputMessagesParamInputMessagesให้เป็นเวอร์ชัน

string / string[] →ถูกแปลงเป็น ChatMessage[] และตัดคํา
InputMessages →ส่งกลับ as-is

function normalizeInputMessages(param: InputMessagesParam): InputMessages

พารามิเตอร์

param: InputMessagesParam

การส่งคืน

InputMessages

normalizeOutputMessages(OutputMessagesParam)

ปรับให้เป็นมาตรฐานตัวรวบOutputMessagesParamOutputMessagesให้เป็นเวอร์ชัน

string / string[] →ถูกแปลงเป็น OutputMessage[] และตัดคํา
OutputMessages →ส่งกลับ as-is

function normalizeOutputMessages(param: OutputMessagesParam): OutputMessages

พารามิเตอร์

param: OutputMessagesParam

การส่งคืน

OutputMessages

resetLogger()

รีเซ็ตไปยังตัวบันทึกคอนโซลเริ่มต้น (ส่วนใหญ่สําหรับการทดสอบ)

function resetLogger()

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

เรียกใช้ฟังก์ชันภายในบริบทที่มีโทเค็นการส่งออกตามคําขอ ซึ่งเก็บโทเค็นเฉพาะในบริบท OTel (ALS) เท่านั้น ไม่อยู่ในรีจิสทรีใด ๆ

โทเค็นสามารถอัปเดตได้ในภายหลัง updateExportToken() ก่อนที่จะมีการล้างข้อมูลการติดตาม — มีประโยชน์เมื่อการเรียกกลับทํางานเป็นเวลานานและโทเค็นต้นฉบับอาจหมดอายุก่อนการส่งออก

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

พารามิเตอร์

token: string

fn: () => 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

ฟังก์ชันที่จะดําเนินการภายในบริบทที่แยกออกมา

การส่งคืน

ผลลัพธ์ของการเรียกกลับ

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

เรียกใช้ฟังก์ชันการเรียกกลับภายในบริบทที่มีการอ้างอิงขยายพาเรนต์ที่ชัดเจน การดําเนินการนี้จะเป็นประโยชน์สําหรับการสร้างช่วงลูกในการเรียกกลับแบบต่างเวลาซึ่งการเผยแพร่บริบทไม่สามารถทําได้

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

พารามิเตอร์

parent: ParentSpanRef

การอ้างอิงขยายหลัก

callback: () => 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

เอาต์พุตคือวัตถุ Wrapper แบบเต็ม: {"version":"0.1.0","messages":[...]}

การลอง/ตรวจจับ ช่วยให้แน่ใจว่าการบันทึกการวัดและส่งข้อมูลทางไกลจะไม่ขว้างแม้ในส่วนของข้อความจะมีค่าที่ไม่ใช่ JSON -serializable (เช่น BigInt, circular refs)

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

จริง ถ้าโทเค็นได้รับการอัปเดตสําเร็จแล้ว เท็จถ้าไม่พบผู้ถือโทเค็น

รายละเอียดตัวแปร

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