Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro เป็นการกระจายการเฝ้าสังเกตแบบครบวงจรที่มอบประสบการณ์การเริ่มต้นใช้งานหนึ่งเดียวสำหรับการรวบรวมการติดตาม เมตริก และบันทึกจากแอปพลิเคชันทั้งแบบใช้เอเจนต์และไม่ใช้เอเจนต์ รองรับความสามารถในการเฝ้าสังเกตสำหรับ Microsoft Agent 365, Microsoft Foundry, Azure Monitor และระบบส่วนหลังที่เข้ากันได้กับ OpenTelemetry Protocol (OTLP) Distro รองรับ .NET, Node.js และ Python และมาแทนการตั้งค่าที่แยกส่วนในสแต็กความสามารถในการเฝ้าสังเกตหลายรายการด้วยการนำเข้าครั้งเดียวและการเรียกใช้การกำหนดค่าครั้งเดียว

สวัสดิการที่สำคัญ

ข้อดีของ Microsoft OpenTelemetry Distro มีดังนี้:

แพคเกจเดียว, API เดียว: แทนที่แพคเกจตัวส่งออกและการวัดค่าระบบหลายรายการด้วยการขึ้นต่อกันรายการเดียว
การรองรับระบบส่วนหลังหลายระบบ: ส่งข้อมูลการวัดและส่งข้อมูลทางไกลไปยัง Azure Monitor, จุดเชื่อมต่อใดๆ ที่เข้ากันได้กับ OpenTelemetry Protocol (OTLP) เช่น Datadog, Grafana หรือ New Relic และ Microsoft Agent 365 พร้อมกัน
การวัดค่าระบบในตัว: ใช้การวัดค่าระบบอัตโนมัติสำหรับ HTTP, ฐานข้อมูล, Azure SDK, ฟังก์ชัน Azure และอื่น ๆ โดยไม่ต้องกำหนดค่าเพิ่มเติม
อิงตามมาตรฐาน: สร้างบน OpenTelemetry ซึ่งเป็นเฟรมเวิร์กการเฝ้าสังเกตมาตรฐานอุตสาหกรรม
ต้นแบบขั้นต่ำ: เพิ่มการนําเข้าครั้งเดียวและการเรียกใช้ฟังก์ชันครั้งเดียวไปยังจุดเข้าใช้งานแอปพลิเคชันของคุณ

การติดตั้งและการกำหนดค่า

คู่มือฉบับนี้แสดงวิธีเพิ่มระบบเฝ้าสังเกตให้กับแอปพลิเคชันของคุณด้วย Microsoft OpenTelemetry Distro Distro จะรวบรวมการติดตาม, เมตริกและบันทึกโดยอัตโนมัติด้วยการวัดค่าระบบในตัว และส่งออกข้อมูลการวัดและส่งข้อมูลทางไกลไปยัง Azure Monitor, จุดเชื่อมต่อ OpenTelemetry Protocol (OTLP) ใด ๆ หรือ Microsoft Agent 365

ติดตั้งไลบรารี

เมื่อต้องการเริ่มต้นใช้งาน Microsoft OpenTelemetry Distro ให้ติดตั้งไลบรารีที่เหมาะสมสำหรับแพลตฟอร์มการพัฒนาของคุณโดยใช้ตัวจัดการแพคเกจของภาษาของคุณ

ข้อกำหนดเบื้องต้น: Python 3.10 หรือใหม่กว่า

pip install microsoft-opentelemetry

ข้อกำหนดเบื้องต้น: Node.js 18 หรือใหม่กว่า แอป ESM ต้องใช้ Node.js 20.6.0 หรือใหม่กว่า

npm install @microsoft/opentelemetry

สำคัญ

เรียกใช้ useMicrosoftOpenTelemetry() โดยเร็วที่สุดในจุดเข้าใช้แอปพลิเคชัน เพื่อให้การวัดค่าระบบสามารถแก้ไขไลบรารีก่อนที่จะโหลด

สำหรับแอป ESM ให้ลงทะเบียน hook สำหรับการวัดค่าระบบก่อนนำเข้าโมดูลที่วัด ใช้ค่าสถานะ --import เมื่อเริ่มต้น:

node --import @microsoft/opentelemetry/loader ./dist/index.js

ติดตั้งแพคเกจ Microsoft.OpenTelemetry NuGet แพคเกจนี้ประกอบด้วยรันไทม์การเฝ้าสังเกตของ Agent 365 การผนวกรวมโฮสติ้ง การวัดค่าระบบอัตโนมัติสำหรับเฟรมเวิร์ก AI ที่รองรับ และไลบรารี OpenTelemetry มาตรฐาน

<PackageReference Include="Microsoft.OpenTelemetry" />

หรือใช้ .NET CLI:

dotnet add package Microsoft.OpenTelemetry

ธนบัตร

หากแพคเกจไม่พร้อมใช้งานบนฟีด NuGet สาธารณะ ให้เพิ่มไฟล์ nuget.config ไว้ที่รากโครงการของคุณ ดู ไฟล์ README ที่จัดเก็บ .NET สำหรับการกำหนดค่าฟีด

โครงแบบ

ตัวส่งออก Agent 365 ไม่ใช้สตริงการเชื่อมต่อ แต่ค้นหาจุดเชื่อมต่อโดยอัตโนมัติตามผู้เช่า เมื่อต้องการเปิดใช้งานการส่งออกไปยัง Agent 365 ให้ตั้งค่าเป้าหมายของตัวส่งออกและกำหนดตัวแก้ไขโทเค็นที่คืนค่าโทเค็นการเข้าถึงสำหรับรหัสเอเจนต์และรหัสผู้เช่าที่กำหนด

เรียกใช้ use_microsoft_opentelemetry() เพื่อเปิดใช้งานการเฝ้าสังเกต

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache

token_cache = AgenticTokenCache()

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=lambda agent_id, tenant_id: (
        (t := asyncio.run(token_cache.get_observability_token(agent_id, tenant_id)))
        and t.token or None
    ),
)

สำหรับการแก้ไขโทเค็นแบบกำหนดเอง (แทนที่จะใช้ตัวแก้ไขโทเค็นเริ่มต้น) ดูที่ ตัวแก้ไขโทเค็นด้วยตนเอง

คุณสามารถปรับแต่งลักษณะการทำงานของตัวส่งออกได้โดยการส่ง a365_*kwargs เสริมไปยัง use_microsoft_opentelemetry()

พารามิเตอร์	คำอธิบาย	ค่าเริ่มต้น
`a365_use_s2s_endpoint`	เมื่อ `True` ใช้พาธของจุดเชื่อมต่อแบบบริการต่อบริการ	`False`
`a365_max_queue_size`	ขนาดคิวสูงสุดสำหรับตัวประมวลผลชุดงาน	`2048`
`a365_scheduled_delay_ms`	หน่วงเวลาเป็นมิลลิวินาทีระหว่างชุดงานการส่งออก	`5000`
`a365_exporter_timeout_ms`	การหมดเวลาในหน่วยมิลลิวินาทีสำหรับการดำเนินการส่งออก	`30000`
`a365_max_export_batch_size`	ขนาดชุดงานสูงสุดสำหรับการดำเนินการส่งออก	`512`

ใช้ ObservabilityManager ร่วมกับ AgenticTokenCacheInstance เพื่อจัดการการแคชโทเค็นโดยอัตโนมัติ:

import { useMicrosoftOpenTelemetry, AgenticTokenCacheInstance } from '@microsoft/opentelemetry';
import { resourceFromAttributes } from '@opentelemetry/resources';

useMicrosoftOpenTelemetry({
  resource: resourceFromAttributes({
    'service.name': 'Default Token Cache Sample',
    'service.version': '1.0.0',
  }),
  azureMonitor: {
    enabled: Boolean(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING),
  },
  instrumentationOptions: {
    http: { enabled: false },
  },
  a365: {
    enabled: process.env.ENABLE_A365_OBSERVABILITY_EXPORTER !== 'false',
    tokenResolver: (agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId) ?? '',
  },
});

คุณสามารถปรับแต่งลักษณะการทำงานของตัวส่งออกได้โดยการตั้งค่าคุณสมบัติเพิ่มเติมบนอ็อบเจ็กต์ a365

คุณสมบัติ	คำอธิบาย	ค่าเริ่มต้น
`useS2SEndpoint`	เมื่อ `true` ใช้พาธของจุดเชื่อมต่อแบบบริการต่อบริการ	`false`
`maxQueueSize`	ขนาดคิวสูงสุดสำหรับตัวประมวลผลชุดงาน	`2048`
`scheduledDelayMilliseconds`	หน่วงเวลาเป็นมิลลิวินาทีระหว่างชุดงานการส่งออก	`5000`
`exporterTimeoutMilliseconds`	การหมดเวลาเป็นมิลลิวินาทีสำหรับการดำเนินการส่งออกทั้งหมด	`90000`
`httpRequestTimeoutMilliseconds`	การหมดเวลาเป็นมิลลิวินาทีสำหรับการร้องขอทาง HTTP แต่ละรายการที่ส่งไปยังส่วนหลัง	`30000`
`maxExportBatchSize`	ขนาดชุดงานสูงสุดสำหรับการดำเนินการส่งออก	`512`

สําหรับตัวเลือกการกําหนดค่าแบบเต็มและตัวแปรสภาพแวดล้อม โปรดดู ไฟล์ README ที่จัดเก็บ JavaScript

ใน Program.cs เรียกใช้ UseMicrosoftOpenTelemetry() เพื่อเปิดใช้งานการเฝ้าสังเกต การแจงนับค่าสถานะ ExportTarget จะควบคุมว่าข้อมูลการวัดและส่งข้อมูลทางไกลจะถูกส่งไปที่ใด - สามารถรวมปลายทางกับ | (เช่น ExportTarget.Console | ExportTarget.Agent365)

แคชโทเค็นอัตโนมัติ (DI) (แนะนำสำหรับแอป Agent Framework):

เมื่อคุณไม่ได้ตั้งค่า TokenResolver ระบบ distro จะลงทะเบียน IExporterTokenCache<AgenticTokenStruct> โดยอัตโนมัติผ่าน DI เอเจนต์ของคุณเรียกใช้ RegisterObservability() ขณะรันไทม์เพื่อระบุข้อมูลรับรอง และแคชจะจัดการการรับโทเค็นและการรีเฟรช

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // TokenResolver is auto-registered via the agentic token cache in DI, with required imports in the next code snippet.
});

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

// In your agent class
public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

คุณสามารถปรับแต่งลักษณะการทำงานของตัวส่งออกได้โดยการตั้งค่าคุณสมบัติเพิ่มเติมบน o.Agent365.Exporter

คุณสมบัติ	คำอธิบาย	ค่าเริ่มต้น
`UseS2SEndpoint`	เมื่อ `true` ใช้พาธของจุดเชื่อมต่อแบบบริการต่อบริการ	`false`
`MaxQueueSize`	ขนาดคิวสูงสุดสำหรับตัวประมวลผลชุดงาน	`2048`
`ScheduledDelayMilliseconds`	หน่วงเวลาเป็นมิลลิวินาทีระหว่างชุดงานการส่งออก	`5000`
`ExporterTimeoutMilliseconds`	การหมดเวลาในหน่วยมิลลิวินาทีสำหรับการดำเนินการส่งออก	`30000`
`MaxExportBatchSize`	ขนาดชุดงานสูงสุดสำหรับการดำเนินการส่งออก	`512`

ธนบัตร

ENABLE_A365_OBSERVABILITY_EXPORTER เป็นแนวคิดของ Python และ JavaScript ใน .NET คุณควบคุมตัวส่งออก Agent 365 ได้โดยตรงในโค้ดผ่าน ExportTarget.Agent365

ส่งผ่านบริบท

เพื่อรักษาความสามารถในการเฝ้าสังเกตในการดำเนินการ Agent 365 แบบกระจาย ให้ส่งผ่านบริบท เมื่อคุณส่งผ่านบริบทผ่านเอเจนต์และบริการของคุณ คุณจะมั่นใจได้ว่าการติดตาม บันทึก และเมตริกจะถูกเชื่อมโยงกันอย่างเหมาะสมตลอดวงจรชีวิตของคำขอทั้งหมด ความสัมพันธ์นี้จําเป็นสําหรับประสบการณ์การตรวจสอบของ Microsoft Agent 365 ที่สมบูรณ์และมีประสิทธิภาพ

แอตทริบิวต์ Baggage

ใช้ BaggageBuilder เพื่อกำหนดข้อมูลตามบริบทที่ส่งผ่านทุกสแปนในคำขอ SDK มีการนำ SpanProcessor มาใช้ ซึ่งจะคัดลอกรายการ baggage ที่ไม่ว่างเปล่าทั้งหมดไปยังสแปนที่เพิ่งเริ่มต้นใหม่โดยไม่เขียนทับแอตทริบิวต์ที่มีอยู่

from microsoft.opentelemetry.a365.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

หากต้องการเติมข้อมูล BaggageBuilder โดยอัตโนมัติจาก TurnContext ให้ใช้ตัวช่วย populate ในแพคเกจ microsoft-opentelemetry ตัวช่วยนี้จะแยกรายละเอียดผู้เรียกใช้ เอเจนต์ ผู้เช่า ช่องทาง และการสนทนาจากกิจกรรมโดยอัตโนมัติ

from microsoft.opentelemetry.a365.core import BaggageBuilder
from microsoft.opentelemetry.a365.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

import { BaggageBuilder, InvokeAgentScope, ExecuteToolScope } from '@microsoft/opentelemetry';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

หากต้องการเติมข้อมูล BaggageBuilder โดยอัตโนมัติจาก TurnContext ให้ใช้ตัวช่วย fromTurnContext ในแพคเกจ @microsoft/opentelemetry ตัวช่วยนี้จะแยกรายละเอียดผู้เรียกใช้ เอเจนต์ ผู้เช่า ช่องทาง และการสนทนาจากกิจกรรมโดยอัตโนมัติ

import { BaggageBuilder, BaggageBuilderUtils } from '@microsoft/opentelemetry';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

baggageScope.run(() => {
  // Baggage is auto-populated from the TurnContext activity
});

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

หากต้องการเติมข้อมูล BaggageBuilder โดยอัตโนมัติจาก ITurnContext ให้ใช้วิธีการขยาย FromTurnContext ในแพคเกจ Microsoft.Agents.A365.Observability.Hosting วิธีนี้จะดึงข้อมูลผู้เรียกใช้ เอเจนต์ ผู้เช่า ช่องทาง และรายละเอียดการสนทนาออกจากกิจกรรมโดยอัตโนมัติ

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

มิดเดิลแวร์ Baggage

หากเอเจนต์ของคุณใช้แพคเกจการผนวกรวมโฮสติ้ง ให้ลงทะเบียนมิดเดิลแวร์ Baggage เพื่อเติมค่า Baggage โดยอัตโนมัติสำหรับทุกคำขอที่เข้ามา ขั้นตอนนี้ขจัดความจำเป็นในการเรียกใช้ BaggageBuilder ด้วยตนเองในตัวจัดการกิจกรรมแต่ละตัว

ใน Python ลงทะเบียนมิดเดิลแวร์ Baggage ผ่าน ObservabilityHostingManager.configure() แทนการลงทะเบียนโดยตรงบนอะแดปเตอร์

from microsoft.opentelemetry.a365.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

มิดเดิลแวร์จะข้ามการตั้งค่า Baggage สําหรับการตอบกลับแบบอะซิงโครนัส (เหตุการณ์ ContinueConversation) เพื่อหลีกเลี่ยงการเขียนทับ Baggage ที่คําขอต้นทางตั้งค่าไว้แล้ว

ลงทะเบียน BaggageMiddleware บนอะแดปเตอร์ โดยจะดึงรายละเอียดของผู้เรียกใช้ เอเจนต์ ผู้เช่า ช่องทาง และการสนทนาโดยอัตโนมัติจากทุก TurnContext ที่เข้ามา และครอบคำขอไว้ในขอบเขต Baggage

import { BaggageMiddleware } from '@microsoft/opentelemetry';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

อีกทางเลือกหนึ่งคือ ใช้ ObservabilityHostingManager เพื่อกำหนดค่ามิดเดิลแวร์ Baggage พร้อมกับคุณลักษณะการโฮสต์อื่น ๆ

import { ObservabilityHostingManager } from '@microsoft/opentelemetry';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

ลงทะเบียน BaggageTurnMiddleware บนอะแดปเตอร์ โดยจะดึงรายละเอียดของผู้เรียกใช้ เอเจนต์ ผู้เช่า ช่องทาง และการสนทนาโดยอัตโนมัติจากทุก ITurnContext ที่เข้ามา และครอบคำขอไว้ในขอบเขต Baggage

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

หากคุณต้องการ Baggage ระดับ HTTP (ตัวอย่างเช่น เพื่อตั้งค่ารหัสผู้เช่าและเอเจนต์ก่อนที่ไปป์ไลน์ Bot Framework จะทำงาน) ให้ลงทะเบียน ObservabilityBaggageMiddleware ในไปป์ไลน์ ASP.NET Core โดยใช้วิธีการส่วนขยาย UseObservabilityRequestContext คุณต้องจัดเตรียมฟังก์ชันตัวแก้ไขที่ดึงค่ารหัสผู้เช่าและรหัสเอเจนต์จากบริบท HTTP

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

ตรวจสอบความถูกต้องของข้อมูลที่ไปยังผลิตภัณฑ์

เพื่อดูข้อมูลการวัดและส่งข้อมูลทางไกลของเอเจนต์ใน Microsoft Purview หรือ Microsoft Defender โปรดตรวจสอบให้แน่ใจว่าเป็นไปตามข้อกำหนดต่อไปนี้:

Microsoft Purview: ต้องเปิดการตรวจสอบสำหรับองค์กรของคุณ สำหรับคำแนะนำ ดูที่ เปิดหรือปิดการตรวจสอบ
Microsoft Defender: ต้องกำหนดค่าการค้นหาภัยคุกคามขั้นสูงเพื่อเข้าถึงตาราง CloudAppEvents โปรดดูรายละเอียดที่ ตาราง CloudAppEvents ในสคีมาการค้นหาภัยคุกคามขั้นสูง

การวัดค่าระบบอัตโนมัติ

Microsoft OpenTelemetry Distro รวมไปป์ไลน์ OpenTelemetry มาตรฐานเข้ากับการวัดค่าระบบที่ดูแลโดย Microsoft Distro สามารถรวบรวมข้อมูลการวัดและส่งข้อมูลทางไกลของแอปพลิเคชัน การวัดและส่งข้อมูลทางไกลของโครงสร้างพื้นฐาน และการวัดและส่งข้อมูลทางไกลของเอเจนต์หรือ AI สร้างสรรค์ ขึ้นอยู่กับภาษาและการกำหนดค่า

ประเภท	ขอบเขตการครอบคลุม
ไปป์ไลน์สัญญาณ	การติดตาม เมตริก และบันทึก
การตรวจหาทรัพยากร	บริบทรันไทม์ของบริการ โฮสต์ คลาวด์ และ Azure ตามที่รองรับ
การวัดค่าระบบของโครงสร้างพื้นฐาน	HTTP, ASP.NET Core, Azure SDK, ไคลเอ็นต์ฐานข้อมูล และเฟรมเวิร์กการบันทึกที่รองรับ
การวัดค่าระบบสำหรับ AI สร้างสรรค์	OpenAI, Azure OpenAI, Semantic Kernel, LangChain, OpenAI Agents SDK และ Agent Framework ที่รองรับ
ขอบเขตของเอเจนต์ที่กำหนดด้วยตนเอง	การเรียกใช้เอเจนต์ การดำเนินการเครื่องมือ การอนุมาน และการวัดและส่งข้อมูลทางไกลผลลัพธ์ที่รองรับ
ตัวส่งออกและตัวประมวลผล	Azure Monitor, Microsoft Agent 365, OTLP, เอาต์พุตคอนโซล, โปรเซสเซอร์สแปน, ตัวประมวลผลบันทึก, และตัวอ่านเมตริก

ขอบเขตของการวัดค่าระบบ

Language	การวัดค่าระบบสำหรับการใช้งานทั่วไป	เอเจนต์ทั่วไปและการวัดค่าระบบ AI สร้างสรรค์
Python	ทรัพยากร OpenTelemetry, โปรเซสเซอร์, ตัวอ่าน, การบันทึก, เมตริก และการติดตาม	Semantic Kernel, OpenAI Agents SDK, Agent Framework, LangChain, Microsoft Agent 365 baggage และขอบเขต Microsoft Agent 365
Node.js	HTTP, Azure SDK, ฟังก์ชัน Azure, MongoDB, MySQL, PostgreSQL, Redis, Bunyan และ Winston	OpenAI Agents SDK, LangChain, Microsoft Agent 365 baggage และขอบเขต Microsoft Agent 365
.NET	ASP.NET Core, HttpClient, SQL Client, Azure SDK, การตรวจหาทรัพยากร, เมตริก และบันทึก	Semantic Kernel, OpenAI และ Azure OpenAI, Agent Framework, Microsoft Agent 365 baggage และขอบเขต Microsoft Agent 365

การวัดค่าระบบอัตโนมัติจะรอรับสัญญาณการวัดและส่งข้อมูลทางไกลที่ปล่อยออกมาจากไลบรารีและเฟรมเวิร์กที่รองรับ การวัดค่าระบบแบบดำเนินการด้วยตนเองจะใช้เมื่อแอปพลิเคชันจำเป็นต้องอธิบายการดำเนินการเฉพาะของเอเจนต์ เช่น การเรียกใช้ การดำเนินการของเครื่องมือ การอนุมาน หรือเอาต์พุตแบบอะซิงโครนัส

เพิ่มแหล่งที่มา มิเตอร์ โปรเซสเซอร์ หรือตัวอ่าน OpenTelemetry แบบกำหนดเองเมื่อแอปพลิเคชันของคุณปล่อยข้อมูลการวัดและส่งข้อมูลทางไกลที่ไม่ครอบคลุมโดยการวัดค่าระบบในตัว

สำคัญ

การวัดค่าระบบอัตโนมัติจะเพิ่มเฉพาะแอตทริบิวต์มาตรฐานของ OpenTelemetry เท่านั้น ไม่ได้รวมแอตทริบิวต์ทั้งหมดที่ Agent 365 ต้องการ คุณต้องเพิ่มแอตทริบิวต์เฉพาะของ Microsoft ผ่าน BaggageBuilder หากต้องการดูว่าแอตทริบิวต์ใดจําเป็น โปรดดู แอตทริบิวต์การตรวจสอบความถูกต้องของที่เก็บ

ไลบรารีการวัดค่าระบบในตัว

การวัดค่าระบบอัตโนมัติจะรอรับข้อมูลการวัดและส่งข้อมูลทางไกลที่ถูกส่งออกมาจากเฟรมเวิร์กที่รองรับ และส่งต่อข้อมูลเหล่านั้นผ่านไปยังไปป์ไลน์ OpenTelemetry ของ Distro สำหรับสถานการณ์ของเอเจนต์ ให้ตั้งค่า baggage เช่น รหัสผู้เช่าและรหัสเอเจนต์ก่อนที่เฟรมเวิร์กที่ถูกวัดจะสร้างสแปน

กรอบการทำงาน	Python	Node.js	.NET
Semantic Kernel	ได้รับการสนับสนุน	ไม่สนับสนุน	ได้รับการสนับสนุน
OpenAI และ OpenAI Agents SDK	ได้รับการสนับสนุน	รองรับ	ได้รับการสนับสนุน
Agent Framework	ได้รับการสนับสนุน	ไม่สนับสนุน	ได้รับการสนับสนุน
LangChain	ได้รับการสนับสนุน	ได้รับการสนับสนุน	ไม่อยู่ในรายการ

Semantic Kernel

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "semantic_kernel": {"enabled": True},
    },
)

การวัดค่าระบบของ Semantic Kernel จะเปิดใช้งานโดยค่าเริ่มต้น หากต้องการปิดใช้งาน ให้ตั้งค่าตัวเลือกการวัดค่าระบบอย่างชัดแจ้ง

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableSemanticKernelInstrumentation = false;
});

OpenAI

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "openai_agents": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    openaiAgents: { enabled: true },
  },
});

การวัดค่าระบบของ OpenAI และ Azure OpenAI จะเปิดใช้งานตามค่าเริ่มต้น หากต้องการปิดใช้งาน ให้ตั้งค่าตัวเลือกการวัดค่าระบบอย่างชัดแจ้ง

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableOpenAIInstrumentation = false;
});

Agent Framework

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "agent_framework": {"enabled": True},
    },
)

การวัดค่าระบบของ Agent Framework จะเปิดใช้งานโดยค่าเริ่มต้น หากต้องการปิดใช้งาน ให้ตั้งค่าตัวเลือกการวัดค่าระบบอย่างชัดแจ้ง

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Instrumentation.EnableAgentFrameworkInstrumentation = false;
});

LangChain

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "your-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
    instrumentation_options={
        "langchain": {"enabled": True},
    },
)

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "your-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
  instrumentationOptions: {
    langchain: { enabled: true },
  },
});

การวัดค่าระบบแบบกำหนดเอง

ใช้การวัดค่าระบบแบบดำเนินการเองเมื่อการวัดค่าระบบอัตโนมัติไม่ได้อธิบายการทำงานของเอเจนต์ได้ละเอียดเพียงพอ ขอบเขตแบบดำเนินการเองช่วยให้แอปพลิเคชันอธิบายกิจกรรมเอเจนต์ทั่วไปในลักษณะที่สอดคล้องกันในหลายภาษา

ขอบเขต	ใช้สำหรับ
`InvokeAgentScope`	การเริ่มต้นและการเสร็จสิ้นของการเรียกใช้เอเจนต์
`ExecuteToolScope`	การเรียกใช้เครื่องมือโดยเอเจนต์
`InferenceScope`	การอนุมานของโมเดล AI
`OutputScope`	ผลลัพธ์ที่ต้องบันทึกเมื่อขอบเขตต้นทางเสร็จสิ้นแล้ว

นำค่าคำขอและข้อมูลประจำตัวของเอเจนต์เดียวกันกลับมาใช้ในแต่ละขอบเขตของคำขอ เพื่อให้สามารถเชื่อมโยงข้อมูลการวัดและส่งข้อมูลทางไกลที่เกี่ยวข้องกันได้

การเรียกใช้เอเจนต์

from microsoft.opentelemetry.a365.core import (
    AgentDetails,
    Channel,
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="Email Assistant",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

request = Request(
    content="Please help me organize my emails",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

with InvokeAgentScope.start(
    request=request,
    scope_details=scope_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Please help me organize my emails"])

    # Run the agent invocation.

    invoke_scope.record_output_messages(["I found 15 urgent emails."])

import { InvokeAgentScope } from "@microsoft/opentelemetry";
import type {
  AgentDetails,
  A365Request,
  InvokeAgentScopeDetails,
} from "@microsoft/opentelemetry";

const agentDetails: AgentDetails = {
  agentId: "agent-456",
  agentName: "Email Assistant",
  agentDescription: "An AI agent powered by Azure OpenAI",
  agentAUID: "auid-123",
  agentEmail: "agent@contoso.com",
  agentBlueprintId: "blueprint-789",
  tenantId: "tenant-123",
};

const request: A365Request = {
  content: "Please help me organize my emails",
  sessionId: "session-42",
  conversationId: "conv-xyz",
  channel: { name: "msteams" },
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: "myagent.contoso.com", port: 443 },
};

const invokeScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    invokeScope.recordInputMessages(["Please help me organize my emails"]);

    // Run the agent invocation.

    invokeScope.recordOutputMessages(["I found 15 urgent emails."]);
  });
} catch (error) {
  invokeScope.recordError(error as Error);
  throw error;
} finally {
  invokeScope.dispose();
}

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

var agentDetails = new AgentDetails(
    agentId: "agent-456",
    agentName: "Email Assistant",
    agentDescription: "An AI agent powered by Azure OpenAI",
    agenticUserId: "auid-123",
    agenticUserEmail: "agent@contoso.com",
    agentBlueprintId: "blueprint-789",
    tenantId: "tenant-123");

var request = new Request(
    content: "Please help me organize my emails",
    sessionId: "session-42",
    conversationId: "conv-xyz",
    channel: new Channel(name: "msteams"));

var scopeDetails = new InvokeAgentScopeDetails(
    endpoint: new Uri("https://myagent.contoso.com"));

using var invokeScope = InvokeAgentScope.Start(
    request: request,
    scopeDetails: scopeDetails,
    agentDetails: agentDetails);

invokeScope.RecordInputMessages(new[] { "Please help me organize my emails" });

// Run the agent invocation.

invokeScope.RecordOutputMessages(new[] { "I found 15 urgent emails." });

การเรียกใช้เครื่องมือ

from microsoft.opentelemetry.a365.core import (
    ExecuteToolScope,
    ServiceEndpoint,
    ToolCallDetails,
    ToolType,
)

tool_details = ToolCallDetails(
    tool_name="email-search",
    arguments={"query": "from:manager@contoso.com"},
    tool_call_id="tool-call-456",
    description="Search emails by criteria",
    tool_type=ToolType.FUNCTION.value,
    endpoint=ServiceEndpoint(
        hostname="tools.contoso.com",
        port=8080,
        protocol="https",
    ),
)

with ExecuteToolScope.start(
    request=request,
    details=tool_details,
    agent_details=agent_details,
) as scope:
    result = search_emails(tool_details.arguments)
    scope.record_response(result)

import { ExecuteToolScope } from "@microsoft/opentelemetry";
import type { ToolCallDetails } from "@microsoft/opentelemetry";

const toolDetails: ToolCallDetails = {
  toolName: "email-search",
  arguments: JSON.stringify({ query: "from:manager@contoso.com" }),
  toolCallId: "tool-call-456",
  description: "Search emails by criteria",
  toolType: "function",
  endpoint: {
    host: "tools.contoso.com",
    port: 8080,
    protocol: "https",
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var toolDetails = new ToolCallDetails(
    toolName: "email-search",
    arguments: "{\"query\": \"from:manager@contoso.com\"}",
    toolCallId: "tool-call-456",
    description: "Search emails by criteria",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080"));

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolDetails,
    agentDetails: agentDetails);

// Execute the tool.

scope.RecordResponse("{\"count\": 15}");

การอนุมาน

from microsoft.opentelemetry.a365.core import (
    InferenceCallDetails,
    InferenceOperationType,
    InferenceScope,
)

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
)

with InferenceScope.start(
    request=request,
    details=inference_details,
    agent_details=agent_details,
) as scope:
    scope.record_input_messages(["Summarize the following emails for me."])
    response = call_llm()
    scope.record_output_messages([response.text])
    scope.record_input_tokens(response.usage.input_tokens)
    scope.record_output_tokens(response.usage.output_tokens)
    scope.record_finish_reasons(["stop"])

import { InferenceOperationType, InferenceScope } from "@microsoft/opentelemetry";
import type { InferenceDetails } from "@microsoft/opentelemetry";

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: "gpt-4o-mini",
  providerName: "azure-openai",
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  await invokeScope.withActiveSpanAsync(async () => {
    scope.recordInputMessages(["Summarize the following emails for me."]);
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
    scope.recordFinishReasons(["stop"]);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI");

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails);

scope.RecordInputMessages(new[] { "Summarize the following emails for me." });

// Call the model.

scope.RecordOutputMessages(new[] { "Here is your email summary." });
scope.RecordInputTokens(145);
scope.RecordOutputTokens(82);
scope.RecordFinishReasons(new[] { "stop" });

เอาท์พุท

from microsoft.opentelemetry.a365.core import OutputScope, Response, SpanDetails

# Capture this before exiting the originating InvokeAgentScope context.
parent_context = invoke_scope.get_span_context()
response = Response(
    messages=["Here is your organized inbox."],
)

with OutputScope.start(
    request=request,
    response=response,
    agent_details=agent_details,
    user_details=None,
    span_details=SpanDetails(parent_context=parent_context),
) as scope:
    pass

import { OutputScope } from "@microsoft/opentelemetry";
import type { A365SpanDetails, OutputResponse } from "@microsoft/opentelemetry";

// Capture this before disposing the originating InvokeAgentScope.
const parentContext = invokeScope.getSpanContext();
const response: OutputResponse = {
  messages: ["Here is your organized inbox."],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined,
  { parentContext } as A365SpanDetails
);

scope.dispose();

// Capture this before disposing the originating InvokeAgentScope.
var parentContext = invokeScope.GetActivityContext();
var response = new Response(new[] { "Here is your organized inbox." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext));

เอกสารประกอบผลิตภัณฑ์ควรระบุข้อกำหนดการตรวจสอบความถูกต้องเฉพาะผลิตภัณฑ์สำหรับขอบเขตเหล่านี้

การตรวจสอบความถูกต้องภายในเครื่อง

การตรวจสอบความถูกต้องภายในเครื่องยืนยันว่าแอปพลิเคชันสร้างการวัดและส่งข้อมูลทางไกลก่อนที่ปลายทางเฉพาะผลิตภัณฑ์จะได้รับการตรวจสอบความถูกต้อง ใช้เอาต์พุตคอนโซลหรือจุดเชื่อมต่อ OTLP ภายในเครื่องเพื่อตรวจสอบว่ามีการสร้างการติดตาม เมตริก และบันทึก

ตรวจสอบความถูกต้องด้วยจุดเชื่อมต่อ OTLP ภายในเครื่อง

กำหนดค่า Distro เพื่อส่งข้อมูลการวัดและส่งข้อมูลทางไกลไปยังตัวรวบรวมภายในเครื่องหรือจุดเชื่อมต่อ OTLP อื่น

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

useMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Otlp;
    o.OtlpEndpoint = new Uri("http://localhost:4317");
});

ตรวจสอบด้วยเอาต์พุตในเครื่อง

ใช้เอาต์พุตในเครื่องเมื่อคุณต้องการยืนยันการวัดค่าระบบก่อนส่งข้อมูลการวัดและส่งข้อมูลทางไกลไปยังปลายทางระยะไกล

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

from microsoft.opentelemetry import use_microsoft_opentelemetry

def token_resolver(agent_id, tenant_id):
    return "local-validation-token"

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=token_resolver,
)

# Run instrumented application code.

export ENABLE_A365_OBSERVABILITY_EXPORTER=false

import {
  useMicrosoftOpenTelemetry,
  shutdownMicrosoftOpenTelemetry,
} from "@microsoft/opentelemetry";

const tokenResolver = (agentId, tenantId) => {
  return "local-validation-token";
};

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver,
  },
});

// Run instrumented application code.

await shutdownMicrosoftOpenTelemetry();

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Console;
});

ตรวจสอบเอาต์พุตในเครื่องสำหรับสแปนจากแหล่งที่มาที่คาดไว้ เช่น การร้องขอทาง HTTP, การเรียกใช้ OpenAI หรือ Azure OpenAI, ขอบเขตการเรียกใช้เอเจนต์, ขอบเขตการดำเนินการของเครื่องมือ หรือขอบเขตการอนุมาน การตรวจสอบความถูกต้องเฉพาะปลายทางอยู่ในเอกสารประกอบผลิตภัณฑ์สำหรับปลายทางนั้น

ตั้งค่าการรับรองความถูกต้องด้วยตนเอง

เมื่อคุณใช้ตัวส่งออก Agent 365 คุณต้องจัดเตรียมกลไกในการจัดหาโทเค็นการรับรองความถูกต้อง ตัวแก้ไขโทเค็นจะทำงานกับแต่ละชุดงานการส่งออกโดยใช้รหัสเอเจนต์และรหัสผู้เช่าจากบริบท baggage ที่กำลังใช้งานอยู่ ระบบ Distro รองรับวิธีการสองแบบ

เคล็ดลับ

หากคุณกำลังสร้างเอเจนต์ด้วย SDK เอเจนต์สำหรับ Microsoft 365 โปรดดู การตั้งค่าการรับรองความถูกต้องของการเฝ้าสังเกตสำหรับ SDK เอเจนต์ เพื่อดูคำแนะนำทีละขั้นตอนเกี่ยวกับการกำหนดค่าการรับโทเค็น OBO และ S2S สำหรับทั้งเอเจนต์แบบเอเจนต์และเอเจนต์ที่ไม่ใช่แบบเอเจนติก

ตัวแก้ไขโทเค็นด้วยตนเอง

ใช้ตัวแก้ไขโทเค็นด้วยตนเองเมื่อคุณได้รับโทเค็นนอกไปป์ไลน์ Agent Framework เมื่อคุณสร้างแอปที่ไม่ได้ใช้ Agent Framework หรือเมื่อคุณใช้การรับรองความถูกต้องแบบบริการต่อบริการ (S2S) (โฟลว์ข้อมูลรับรองไคลเอ็นต์) เอเจนต์สามารถสร้างโทเค็นได้เอง เช่น โดยใช้ Microsoft Authentication Library (MSAL) หรือวิธีการรับโทเค็นอื่น ๆ แต่ต้องตรวจสอบว่าโทเค็นนั้นมีขอบเขตการเฝ้าสังเกตที่ถูกต้อง (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite)

ธนบัตร

สำหรับการรับรองความถูกต้องแบบบริการต่อบริการ (S2S) คุณต้องใช้วิธีการตัวแก้ไขโทเค็นด้วยตนเองนี้ แคชโทเค็นแบบเอเจนติกรองรับเฉพาะโฟลว์การรับรองความถูกต้องในนามของผู้ใช้ (OBO)

ตัวอย่างต่อไปนี้แสดงรูปแบบตัวแก้ไขโทเค็น OBO (ในนามของผู้ใช้) — เอเจนต์จะรับโทเค็นของผู้ใช้ผ่านตัวจัดการการรับรองความถูกต้องแบบเอเจนตฺกและแลกเปลี่ยนโทเค็นนั้นเป็นโทเค็นที่มีขอบเขตสำหรับการเฝ้าสังเกต สำหรับตัวอย่าง S2S (บริการต่อบริการ) และการเปรียบเทียบการรับรองความถูกต้อง OBO กับ S2S โปรดดู การตั้งค่าการรับรองความถูกต้องของการเฝ้าสังเกตสำหรับ SDK เอเจนต์

ตัวแก้ไขต้องเป็นแบบซิงโครนัส รับโทเค็นในตัวจัดการกิจกรรมแบบอะซิงโครนัสของคุณ (หรือผ่าน MSAL) แล้วเก็บไว้ในแคชเพื่อใช้งานกับตัวแก้ไข

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

_cached_token: str | None = None

def my_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_token

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=my_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    global _cached_token
    _cached_token = await AGENT_APP.auth.exchange_token(
        context,
        scopes=get_observability_authentication_scope(),
        auth_handler_id="AGENTIC",
    )

import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";
import { TurnState, AgentApplication, TurnContext, MemoryStorage } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';

useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: (agentId: string, tenantId: string, authScopes?: string[]) =>
      myTokenService.getToken(agentId, tenantId),
  },
});


export class A365Agent extends AgentApplication<TurnState> {
  isApplicationInstalled: boolean = true;
  termsAndConditionsAccepted: boolean = true;
  agentName = 'A365 Agent';
  authHandlerName = 'agentic';

  constructor() {
    const useAgenticAuth = process.env.USE_AGENTIC_AUTH === 'true';

    super({
      storage: new MemoryStorage(),
      ...(useAgenticAuth && {
        authorization: {
          agentic: {
            type: 'agentic',
          }
        }
      })
    });

    this.onActivity(ActivityTypes.Message, async (context: TurnContext, state: TurnState) => {
      await this.handleAgentMessageActivity(context, state);
    });
  }

  async handleAgentMessageActivity(turnContext: TurnContext, _state: TurnState): Promise<void> {
    if (process.env.USE_AGENTIC_AUTH !== 'true') {
      console.log('[A365Agent] Authorization not configured, skipping observability token preload');
      return;
    }

    const agentId = turnContext?.activity?.recipient?.agenticAppId ?? '';
    const tenantId = turnContext?.activity?.recipient?.tenantId ?? '';

    // Acquire auth token via OBO exchange
    const authToken = await this.authorization.exchangeToken(turnContext, 'agentic', {
      scopes: ['api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite']
    });

    // Cache the token so it can be returned by the token resolver
    myTokenService.set(agentId, tenantId, authToken?.token || '');
  }
}

using Microsoft.OpenTelemetry;

builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
    {
        return await MyTokenService.GetTokenAsync(agentId, tenantId);
    };
});

เมื่อคุณตั้งค่า TokenResolver อย่างชัดเจน ระบบจะไม่ลงทะเบียนแคชโทเค็น DI อัตโนมัติ และจะใช้ตัวแก้ไขของคุณแทน

แคชโทเค็นแบบเอเจนติกกับแอป Agent Framework

สำหรับแอป Agent Framework ที่ใช้การรับรองความถูกต้องแบบในนามของผู้ใช้ (OBO) ระบบ distro จะลงทะเบียน IExporterTokenCache<AgenticTokenStruct> ผ่าน DI โดยอัตโนมัติ หากคุณไม่ได้ตั้งค่า TokenResolver แบบกำหนดเอง เอเจนต์ของคุณเรียกใช้ RegisterObservability() ขณะรันไทม์เพื่อระบุข้อมูลรับรอง และแคชจะจัดการการรับโทเค็นและการรีเฟรช

ธนบัตร

วิธีการนี้สนับสนุนเฉพาะโฟลว์การรับรองความถูกต้องในนามของผู้ใช้ (OBO) เท่านั้น สำหรับการรับรองความถูกต้องแบบบริการต่อบริการ (S2S) ให้ใช้ ตัวแก้ไขโทเค็นแบบดำเนินการเอง แทน

from microsoft.opentelemetry import use_microsoft_opentelemetry
from microsoft.opentelemetry.a365.hosting.token_cache_helpers import AgenticTokenCache, AgenticTokenStruct
from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope

token_cache = AgenticTokenCache()

_cached_tokens: dict[tuple[str, str], str | None] = {}

# Keep the sync resolver side-effect free; refresh the cache in the async request handler.
def sync_token_resolver(agent_id: str, tenant_id: str) -> str | None:
    return _cached_tokens.get((agent_id, tenant_id))

use_microsoft_opentelemetry(enable_a365=True, a365_token_resolver=sync_token_resolver)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    agent_id = context.activity.recipient.id
    tenant_id = context.activity.recipient.tenant_id
    token_cache.register_observability(
        agent_id=agent_id,
        tenant_id=tenant_id,
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )
    _cached_tokens[(agent_id, tenant_id)] = await token_cache.get_observability_token(
        agent_id, tenant_id,
    )

ใช้ configureA365Hosting ในการลงทะเบียนมิดเดิลแวร์ A365 บนอะแดปเตอร์ มิดเดิลแวร์นี้จัดการ baggage และการจัดการโทเค็นโดยอัตโนมัติ

import { configureA365Hosting } from "@microsoft/opentelemetry";

configureA365Hosting(adapter, {
  enableBaggage: true,
  enableOutputLogging: false,
});

ตั้งค่า enableOutputLogging: false หากไม่ต้องการให้เนื้อหาการตอบถูกบันทึกเป็นแอตทริบิวต์ของสแปน

// Program.cs — no TokenResolver needed
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    // IExporterTokenCache<AgenticTokenStruct> is auto-registered via DI
});

ในคลาสเอเจนต์ ให้เรียกใช้ RegisterObservability() ในแต่ละรอบ:

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options,
        IExporterTokenCache<AgenticTokenStruct> agentTokenCache) : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(
        ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        _agentTokenCache.RegisterObservability(
            turnContext.Activity.Recipient.AgenticAppId,
            turnContext.Activity.Recipient.TenantId,
            new AgenticTokenStruct(
                userAuthorization: UserAuthorization,
                turnContext: turnContext,
                authHandlerName: "AGENTIC"),
            EnvironmentUtils.GetObservabilityAuthenticationScope());
    }
}

แอตทริบิวต์การตรวจสอบความถูกต้องของที่จัดเก็บ

เพื่อให้การตรวจสอบความถูกต้องของที่จัดเก็บสำเร็จ เอเจนต์ของคุณต้องดำเนินการ InvokeAgentScope, InferenceScope และ ExecuteToolScope แต่ละขอบเขตจะสอดคล้องกับการดำเนินการสแปนในสคีมาแบบมาตรฐาน:

ขอบเขต SDK	การดำเนินการสแปน	รหัสอ้างอิงสากล
`InvokeAgentScope`	`invoke_agent`	`IA`
`ExecuteToolScope`	`execute_tool`	`ET`
`InferenceScope`	`chat`	`CH`
`OutputScope`	`output_messages`	`OM`

สำหรับรายการแอตทริบิวต์ที่จำเป็นและไม่จำเป็นแบบเต็มสำหรับแต่ละขอบเขต — รวมถึงความหมายของแต่ละแอตทริบิวต์ แนวทางการเลือกค่า และแอตทริบิวต์ใดที่สามารถค้นหาได้ผ่านคุณลักษณะการค้นหาภัยคุกคามขั้นสูงของ Microsoft Defender — โปรดดู ข้อมูลอ้างอิงแอตทริบิวต์สำหรับการเฝ้าสังเกตของ Agent 365 คอลัมน์ ใช้กับ ระบุขอบเขตที่แต่ละแอตทริบิวต์อยู่ และคอลัมน์ จำเป็น แยกแอตทริบิวต์ที่บังคับ (M) ออกจากแอตทริบิวต์ที่ไม่บังคับ (O)

ทดสอบเอเจนต์ของคุณด้วยการเฝ้าสังเกต

หลังจากเปิดใช้งานการเฝ้าสังเกตแล้ว ให้ตรวจสอบว่ามีการบันทึกข้อมูลการวัดและส่งข้อมูลทางไกล:

ไปที่ https://admin.cloud.microsoft/#/agents/all
เลือกเอเจนต์ของคุณ แล้วเลือก กิจกรรม
ตรวจสอบว่าเซสชันและการเรียกใช้เครื่องมือปรากฏขึ้น

แอปพลิเคชันตัวอย่างและการกำหนดค่าขั้นสูง

สำหรับตัวอย่างการใช้งานและตัวเลือกการกำหนดค่าขั้นสูงสามารถดูได้ที่ที่เก็บ GitHub สำหรับแต่ละภาษา:

กำลังแก้ไขปัญหา

ส่วนนี้อธิบายปัญหาทั่วไปที่เกิดขึ้นเมื่อมีการนำไปใช้และใช้งาน Microsoft OpenTelemetry Distro กับ Agent 365

ปัญหา	คำอธิบาย
ข้อมูลการเฝ้าสังเกตไม่ปรากฏขึ้น	ข้อมูลการวัดและส่งข้อมูลทางไกลไม่แสดงผลเนื่องจากยังไม่ได้เปิดใช้งานการส่งออก Agent 365 การตั้งค่ายังไม่สมบูรณ์ หรือการรับโทเค็นล้มเหลว
ไม่มีรหัสผู้เช่าหรือรหัสเอเจนต์ -สแปนถูกข้าม	สแปนจะถูกกรองออกก่อนส่งออกเมื่อไม่มีแอตทริบิวต์ข้อมูลประจำตัวของผู้เช่าหรือเอเจนต์ที่จำเป็น
การแก้ไขโทเค็นล้มเหลว - ข้ามการส่งออกหรือไม่ได้รับอนุญาต	การส่งออกจะถูกข้ามหรือปฏิเสธเมื่อตัวแก้ไขโทเค็นไม่ส่งคืนโทเค็นหรือเกิดข้อผิดพลาดระหว่างการรับโทเค็น
HTTP 401 ไม่ได้รับอนุญาต	คำขอไปถึงบริการ แต่การรับรองความถูกต้องล้มเหลวเนื่องจากโทเค็นไม่ถูกต้อง หมดอายุ หรือสำหรับกลุ่มเป้าหมายที่ไม่ถูกต้อง
HTTP 403 ไม่อนุญาต	การอนุญาตล้มเหลวเนื่องจากไม่มีการให้สิทธิการใช้งานของผู้เช่าหรือไม่มีสิทธิในการเขียนข้อมูลการเฝ้าสังเกต
HTTP 403 ไม่อนุญาต - รหัสเอเจนต์ไม่ตรงกัน	บริการจะปฏิเสธการส่งออกเมื่อรหัสเอเจนต์ในคำขอไม่ตรงกับข้อมูลประจำตัวของเอเจนต์ที่ได้รับอนุญาตจากโทเค็น
ข้อผิดพลาด HTTP 429 หรือ 5xx – ข้อผิดพลาดชั่วคราว	การควบคุมปริมาณใช้ชั่วคราวหรือความไม่เสถียรของระบบส่วนหลังขัดจังหวะการส่งออก และอาจต้องลองใหม่หรือปรับแต่งการส่งออกเป็นชุดงาน
หมดเวลาส่งออก	การดำเนินการส่งออกเกินเวลาที่กำหนดเนื่องจากความล่าช้าในเครือข่ายหรือการตอบสนองของจุดเชื่อมต่อ
การส่งออกสำเร็จแต่ข้อมูลการวัดและส่งข้อมูลทางไกลไม่ปรากฏใน Defender หรือ Purview	การนําเข้าข้อมูลสําเร็จ แต่การมองเห็นล่าช้าหรือถูกบล็อกโดยข้อกําหนดเบื้องต้นและข้อกําหนดของสคีมาขั้นปลาย

เคล็ดลับ

คู่มือการแก้ไขปัญหา Agent 365 ประกอบด้วยคำแนะนำการแก้ไขปัญหาระดับสูง แนวทางปฏิบัติที่ดีที่สุด และลิงก์ไปยังเนื้อหาการแก้ไขปัญหาสำหรับแต่ละส่วนของวงจรการพัฒนา Agent 365

ข้อมูลการเฝ้าสังเกตไม่ปรากฏขึ้น

อาการ:

เอเจนต์กำลังทำงาน
ไม่มีข้อมูลการวัดและส่งข้อมูลทางไกลในศูนย์การจัดการ
ไม่เห็นกิจกรรมของเอเจนต์

สาเหตุหลัก:

ไม่ได้เปิดใช้งานการส่งออก Agent 365
ข้อผิดพลาดในการกำหนดค่า
ปัญหาเกี่ยวกับตัวแก้ไขโทเค็น

การแก้ไขปัญหา: ลองทําตามขั้นตอนต่อไปนี้เพื่อแก้ไขปัญหา:

ตรวจสอบว่าเปิดใช้งานการส่งออก Agent 365

คุณต้องเปิดใช้งานตัวส่งออก Agent 365 ด้วยตนเอง หากคุณไม่ได้ตั้งค่า distro อาจเลือกใช้ตัวส่งออกคอนโซลหรือไม่ส่งออกข้อมูลใด ๆ เปิดใช้งานในโค้ด:
- Python
- Node.js
- .NET
```
from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)
```
หรือตั้งค่าตัวแปรสภาพแวดล้อม:
```
export ENABLE_A365_OBSERVABILITY_EXPORTER=true
```
ธนบัตร

ENABLE_A365_OBSERVABILITY_EXPORTER เป็นตัวสลับสำรองที่จะมีผลเฉพาะเมื่อ enable_a365=True ถูกตั้งค่าในโค้ด คุณสามารถควบคุมได้ผ่าน a365_enable_observability_exporterkwarg
```
useMicrosoftOpenTelemetry({
  a365: { enabled: true },
});
```
หรือตั้งค่าตัวแปรสภาพแวดล้อม:
```
ENABLE_A365_OBSERVABILITY_EXPORTER=true
```
ธนบัตร

ENABLE_A365_OBSERVABILITY_EXPORTER เป็นตัวสลับสำรองที่จะมีผลเฉพาะเมื่อมีการระบุตัวเลือก a365 ในโค้ดเท่านั้น. ไม่สามารถเปิดใช้งานตัวส่งออก A365 ได้ด้วยตัวเอง
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.TokenResolver = async (agentId, tenantId) =>
        await myTokenService.GetTokenAsync(agentId, tenantId);
});
```

ตรวจสอบการกําหนดค่าตัวแก้ไขโทเค็น

ตัวส่งออกต้องการตัวแก้ไขโทเค็นที่ถูกต้องซึ่งคืนค่าโทเค็นแบบแบเรอร์สำหรับแต่ละคำขอการส่งออก หากตัวแก้ไขโทเค็นขาดหายไปหรือส่งคืน null การส่งออกจะถูกข้ามไปอย่างเงียบๆ
เปิดใช้งานการส่งออกคอนโซลและตรวจสอบการวัดและส่งข้อมูลทางไกลในเครื่อง

เพิ่มตัวส่งออกคอนโซลเพื่อยืนยันว่าข้อมูลการวัดและส่งข้อมูลทางไกลถูกสร้างขึ้นก่อนที่จะไปถึงจุดเชื่อมต่อ Agent 365:
- Python
- Node.js
- .NET
```
use_microsoft_opentelemetry(enable_a365=True, enable_console=True)
```
```
useMicrosoftOpenTelemetry({ enableConsoleExporters: true });
```
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365 | ExportTarget.Console;
});
```

เปิดใช้งานการบันทึกรายละเอียด
- Python
- Node.js
- .NET
```
import logging

logging.basicConfig(level=logging.DEBUG)
```
ตั้งค่า A365_OBSERVABILITY_LOG_LEVEL เป็น info หรือ warn เพื่อแสดงการวินิจฉัยตัวส่งออก A365 ภายใน:
```
A365_OBSERVABILITY_LOG_LEVEL=info
```
ส่วนประกอบภายในบันทึกผ่าน ILoggerFactory จาก DI ในแอป ASP.NET Core การบันทึกจะส่งผ่านไปป์ไลน์ที่กำหนดค่าของแอปโดยอัตโนมัติ สําหรับแอปคอนโซล ให้ตั้งค่าอย่างชัดแจ้ง:
```
builder.Services.AddLogging(logging => logging.AddConsole());
```

ตรวจสอบบันทึกเพื่อหาข้อผิดพลาดในการส่งออก

ใช้คำสั่ง az webapp log tail เพื่อค้นหาข้อผิดพลาดที่เกี่ยวข้องกับการเฝ้าสังเกตในบันทึก
```
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```

ไม่มีรหัสผู้เช่าหรือรหัสเอเจนต์ — ข้ามสแปน

อาการ: ระบบจะลดสแปนอย่างเงียบ ๆ และไม่ส่งออก บางแพลตฟอร์มบันทึกจำนวนสแปนที่ข้ามหรือมีข้อความ เช่น No spans with tenant/agent identity found แพลตฟอร์มอื่น ๆ ละทิ้งสแปนโดยไม่บันทึกไว้

วิธีการแก้ไขปัญหา:

ก่อนการส่งออก distro จะแบ่งสแปนตามรหัสผู้เช่าและรหัสเอเจนต์ สแปนที่ไม่มีรหัสผู้เช่าหรือรหัสเอเจนต์จะถูกละทิ้งและจะไม่ถูกส่งไปยังบริการ
ตรวจสอบว่า BaggageBuilder ตั้งค่าด้วยรหัสผู้เช่าและรหัสเอเจนต์ก่อนที่จะสร้างสแปน ค่าดังกล่าวจะถูกส่งผ่านบริบท OpenTelemetry และแนบกับทุกสแปนที่สร้างขึ้นภายในขอบเขต baggage สำหรับ API เฉพาะแพลตฟอร์ม ดู แอตทริบิวต์ baggage
หากคุณกําลังใช้มิดเดิลแวร์ baggage หรือเปลี่ยนตัวช่วยบริบทจากแพคเกจการผนวกรวมโฮสติ้ง ให้ยืนยันว่ากิจกรรม TurnContext มีผู้รับที่ถูกต้องพร้อมข้อมูลประจําตัวของเอเจนต์

ข้อผิดพลาดในการแก้ไขโทเค็น — การส่งออกถูกข้ามหรือไม่ได้รับอนุญาต

อาการ: ตัวแก้ไขโทเค็นส่งคืน null หรือเกิดข้อผิดพลาด ทั้งนี้ขึ้นอยู่กับแพลตฟอร์ม การส่งออกจะถูกข้ามไปหรือเกิดข้อผิดพลาดที่มี HTTP 401

วิธีการแก้ไขปัญหา:

ตัวแก้ไขโทเค็นเป็นสิ่งจำเป็น หากไม่มี ตัวส่งออกจะแสดงข้อผิดพลาดเมื่อเริ่มต้นระบบ ตรวจสอบว่ามีตัวแก้ไขโทเค็นและส่งคืนโทเค็นแบบแบเรอร์ที่ถูกต้อง
ตรวจสอบให้แน่ใจว่ารหัสผู้เช่าและรหัสเอเจนต์ที่ถูกต้องถูกส่งผ่านไปยัง BaggageBuilder เนื่องจากค่าเหล่านี้จะถูกส่งต่อไปยังตัวแก้ไขโทเค็น
สำหรับเอเจนต์ที่โฮสต์บน Azure ให้ตรวจสอบว่า Managed Identity มีสิทธิ์ API ที่จำเป็นสำหรับขอบเขตการเฝ้าสังเกต
สำหรับแอป .NET ที่ใช้แพคเกจโฮสติ้งของ Agent Framework การแลกเปลี่ยนโทเค็นจะได้รับการจัดการโดยอัตโนมัติผ่าน DI หากไม่มีโทเค็น ให้ยืนยันว่า Microsoft.Agents.A365.Observability.Hosting ได้รับการติดตั้งและลงทะเบียนแล้ว

HTTP 401 ไม่ได้รับอนุญาต

อาการ: การส่งออกล้มเหลวด้วย HTTP 401 ตัวส่งออกไม่ลองส่งออกซ้ำเมื่อเกิดข้อผิดพลาดนี้

วิธีการแก้ไขปัญหา:

ตรวจสอบว่ากลุ่มเป้าหมายของโทเค็นตรงกับขอบเขตจุดเชื่อมต่อการเฝ้าสังเกต
ตรวจสอบว่าตัวแก้ไขโทเค็นไม่ได้ส่งคืนโทเค็นของผู้ใช้ที่ได้รับมอบสิทธิ์ โทเค็นสำหรับกลุ่มเป้าหมายที่ไม่ถูกต้อง หรือโทเค็นที่หมดอายุ

HTTP 403 ไม่อนุญาต

อาการ: การส่งออกล้มเหลวด้วย HTTP 403 ตัวส่งออกไม่ลองส่งออกซ้ำเมื่อเกิดข้อผิดพลาดนี้

สาเหตุหลัก: ข้อผิดพลาด HTTP 403 อาจมีสาเหตุที่แตกต่างกัน ตรวจสอบแนวทางแก้ไขต่อไปนี้ตามลำดับ

วิธีการแก้ไขปัญหา:

ไม่มีสิทธิการใช้งาน — ตรวจสอบว่าผู้เช่าของคุณมีสิทธิการใช้งานอย่างใดอย่างหนึ่งต่อไปนี้กำหนดไว้ใน ศูนย์การจัดการ Microsoft 365:
- ทดสอบ – Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
ไม่มีสิทธิการใช้งาน Agent365.Observability.OtelWrite — ให้สิทธิ์กับข้อมูลประจําตัวของคุณ (ข้อมูลประจําตัวที่มีการจัดการหรือการลงทะเบียนแอป) หากไม่มี การส่งออกข้อมูลการวัดและส่งข้อมูลทางไกลจะล้มเหลวด้วย HTTP 403

ให้สิทธิ์

ใช้ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้:

Agent 365 CLI

ต้องใช้บัญชีผู้ดูแลระบบส่วนกลาง; เรียกใช้จากไดเรกทอรีโครงการเอเจนต์ที่มี a365.config.json หรือใช้ --agent-name
```
a365 setup permissions bot
```
หรือโดยไม่มีไฟล์กำหนดค่า:
```
a365 setup permissions bot --agent-name "<agent-name>"
```
พอร์ทัล Entra

ไม่จำเป็นต้องใช้ไฟล์กำหนดค่า; ต้องมีสิทธิ์การเข้าถึงของผู้ดูแลระบบส่วนกลางสำหรับการลงทะเบียนแอปในแบบพิมพ์เขียว
1. ไปที่ พอร์ทัล Entra>การลงทะเบียนแอป> เลือกแอปแบบพิมพ์เขียวของคุณ
2. ไปที่ สิทธิ์ API>เพิ่มสิทธิ์>API ที่องค์กรของฉันใช้> ให้ค้นหา 9b975845-388f-4429-889e-eab1ef63949c
3. เลือก สิทธิ์ที่ได้รับมอบหมาย> เลือก Agent365.Observability.OtelWrite>เพิ่มสิทธิ์
4. ทําซ้ำขั้นตอนที่ 2-3 คราวนี้เลือก สิทธิ์ของแอปพลิเคชัน> เลือก Agent365.Observability.OtelWrite>เพิ่มสิทธิ์
5. คลิก ให้ความยินยอมของผู้ดูแลระบบ และยืนยัน
ทั้ง Agent365.Observability.OtelWrite (แบบมอบสิทธิ์) และ Agent365.Observability.OtelWrite (แบบแอปพลิเคชัน) แสดงสถานะ Granted

HTTP 403 ไม่อนุญาต — รหัสเอเจนต์ไม่ตรงกัน

อาการ: การส่งออกไม่สำเร็จด้วย HTTP 403 และข้อความเซิร์ฟเวอร์ที่คล้ายกัน 403 Forbidden ที่มี agent-ID-mismatch ความล้มเหลวในการเรียกใช้จุดเชื่อมต่อการติดตาม Agent 365

สาเหตุหลัก: ข้อผิดพลาดนี้เกิดขึ้นเมื่อคุณใช้ รหัสไคลเอ็นต์แบบพิมพ์เขียว แทน รหัสไคลเอ็นต์อินสแตนซ์เอเจนต์ เมื่อตั้งค่ารายละเอียดเอเจนต์ รหัสเอเจนต์ใน URL การส่งออกไม่ตรงกับข้อมูลประจำตัวที่ได้รับอนุญาตจากโทเค็น ดังนั้นจุดเชื่อมต่อการติดตามจึงปฏิเสธคำขอ

วิธีการแก้ไขปัญหา:

ตรวจสอบว่ามีการเพิ่มรหัสผู้เช่าลงในรายการผู้เช่าที่อนุญาตของ Agent 365 หรือไม่
ตั้งค่ารายละเอียดเอเจนต์ด้วย รหัสไคลเอ็นต์ของอินสแตนซ์เอเจนต์ (ไม่ใช่รหัสไคลเอ็นต์แบบพิมพ์เขียว)
ตรวจสอบ URL การส่งออกที่สร้างขึ้น – URL นี้จะถูกบันทึกไว้หากคุณเปิดใช้งานตัวบันทึกของคุณ ยืนยันว่ารหัสเอเจนต์ใน URL ตรงกับรหัสไคลเอ็นต์อินสแตนซ์ของเอเจนต์
หากต้องการเปิดใช้งานการบันทึกการวินิจฉัยสำหรับแต่ละ SDK โปรดดู การตรวจสอบความถูกต้องภายในเครื่อง

ข้อผิดพลาด HTTP 429 หรือ 5xx – ข้อผิดพลาดชั่วคราว

อาการ: การส่งออกล้มเหลวด้วยรหัสสถานะ HTTP ชั่วคราว เช่น 429 หรือ 5xx

วิธีการแก้ไขปัญหา:

ข้อผิดพลาดเหล่านี้มักเป็นข้อผิดพลาดชั่วคราวและจะได้รับการแก้ไขเอง Python และ JavaScript distro จะลองใหม่โดยอัตโนมัติเมื่อพบรหัสสถานะ HTTP 408, 429 และ 5xx .NET distro จะไม่ลองใหม่โดยอัตโนมัติ
หากข้อผิดพลาดยังคงอยู่ ให้ตรวจสอบแดชบอร์ดสถานภาพบริการ
พิจารณาลดความถี่ในการส่งออกโดยการเพิ่มช่วงเวลาที่จัดกำหนดการระหว่างการส่งออกแต่ละชุดงาน หรือเพิ่มขนาดชุดงานสูงสุดที่ส่งออกได้ สำหรับ Python และ JavaScript ให้ใช้พารามิเตอร์ exporterOptions หรือ a365_* ที่เกี่ยวข้องที่ระบุไว้ใน ที่เก็บ GitHub สำหรับ .NET ให้ใช้ o.Agent365.Exporter.ScheduledDelayMilliseconds และ o.Agent365.Exporter.MaxExportBatchSize

หมดเวลาส่งออก

อาการ: ความพยายามในการส่งออกหมดเวลา

วิธีการแก้ไขปัญหา:

ตรวจสอบการเชื่อมต่อเครือข่ายไปยังจุดเชื่อมต่อการเฝ้าสังเกต
การหมดเวลาเริ่มต้นของการร้องขอทาง HTTP คือ 30 วินาทีในทุกแพลตฟอร์ม หากเกิดการหมดเวลาบ่อยครั้ง ให้เพิ่มค่าการหมดเวลาในตัวเลือกการส่งออกของคุณ:
- Python
- Node.js
- .NET
```
use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)
```
ดู ที่เก็บ Python สําหรับรายการตัวเลือก a365_* ทั้งหมด
```
useMicrosoftOpenTelemetry({
  a365: {
    enabled: true,
    tokenResolver: myTokenResolver,
    httpRequestTimeoutMilliseconds: 60000,
  },
});
```
```
builder.UseMicrosoftOpenTelemetry(o =>
{
    o.Exporters = ExportTarget.Agent365;
    o.Agent365.Exporter.ExporterTimeoutMilliseconds = 60000;
});
```

การส่งออกสำเร็จแต่ข้อมูลการวัดและส่งข้อมูลทางไกลไม่ปรากฏใน Defender หรือ Purview

อาการ: บันทึกแสดงการส่งออกสำเร็จ (HTTP 200) แต่ข้อมูลการวัดและส่งข้อมูลทางไกลไม่ปรากฏใน Microsoft Defender หรือ Microsoft Purview

วิธีการแก้ไขปัญหา:

ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดเบื้องต้นสำหรับการดูบันทึกที่ส่งออก:
- Microsoft Purview: ต้องเปิดการตรวจสอบสำหรับองค์กรของคุณ ดู เปิดหรือปิดการตรวจสอบ
- Microsoft Defender: ต้องกำหนดค่าการค้นหาภัยคุกคามขั้นสูงเพื่อเข้าถึงตาราง CloudAppEvents ดู ตาราง CloudAppEvents ในสคีมาการค้นหาภัยคุกคามขั้นสูง
ข้อมูลการวัดและส่งข้อมูลทางไกลอาจใช้เวลาหลายนาทีในการปรากฏหลังจากส่งออกสำเร็จ โปรดรอก่อนที่จะดำเนินการตรวจสอบเพิ่มเติม
ตรวจสอบว่าทุกสแปนมีแอตทริบิวต์ microsoft.tenant.id และ gen_ai.agent.id ที่ถูกต้อง สแปนที่ไม่มีแอตทริบิวต์ข้อมูลประจำตัวจะถูกเซิร์ฟเวอร์ทิ้ง แม้ว่าการส่งออก HTTP จะส่งคืนค่า 200 ก็ตาม

แนวคิดเกี่ยวกับการเฝ้าสังเกตของ Agent 365 - การไหลของข้อมูล, รูปแบบข้อมูลประจำตัว, การรับรองความถูกต้อง, ขอบเขต และข้อจำกัดที่ใช้กับทุกเส้นทางการผนวกรวมระบบ
ข้อมูลการอ้างอิงแอตทริบิวต์การเฝ้าสังเกตของ Agent 365 - สคีมาแอตทริบิวต์สแปนแบบมาตรฐานที่ทุกสแปนที่นำเข้าโดย Agent 365 ต้องยึดตาม

คำติชม

หน้านี้มีประโยชน์หรือไม่

Last updated on 2026-07-30

Microsoft OpenTelemetry Distro

สวัสดิการที่สำคัญ

การติดตั้งและการกำหนดค่า

ติดตั้งไลบรารี

โครงแบบ

ส่งผ่านบริบท

แอตทริบิวต์ Baggage

มิดเดิลแวร์ Baggage

ตรวจสอบความถูกต้องของข้อมูลที่ไปยังผลิตภัณฑ์

การวัดค่าระบบอัตโนมัติ

ขอบเขตของการวัดค่าระบบ

ไลบรารีการวัดค่าระบบในตัว

Semantic Kernel

OpenAI

Agent Framework

LangChain

การวัดค่าระบบแบบกำหนดเอง

การเรียกใช้เอเจนต์

การเรียกใช้เครื่องมือ

การอนุมาน

เอาท์พุท

การตรวจสอบความถูกต้องภายในเครื่อง

ตรวจสอบความถูกต้องด้วยจุดเชื่อมต่อ OTLP ภายในเครื่อง

ตรวจสอบด้วยเอาต์พุตในเครื่อง

ตั้งค่าการรับรองความถูกต้องด้วยตนเอง

ตัวแก้ไขโทเค็นด้วยตนเอง

แคชโทเค็นแบบเอเจนติกกับแอป Agent Framework

แอตทริบิวต์การตรวจสอบความถูกต้องของที่จัดเก็บ

ทดสอบเอเจนต์ของคุณด้วยการเฝ้าสังเกต

แอปพลิเคชันตัวอย่างและการกำหนดค่าขั้นสูง

กำลังแก้ไขปัญหา

ข้อมูลการเฝ้าสังเกตไม่ปรากฏขึ้น

ไม่มีรหัสผู้เช่าหรือรหัสเอเจนต์ — ข้ามสแปน

ข้อผิดพลาดในการแก้ไขโทเค็น — การส่งออกถูกข้ามหรือไม่ได้รับอนุญาต

HTTP 401 ไม่ได้รับอนุญาต

HTTP 403 ไม่อนุญาต

ให้สิทธิ์

HTTP 403 ไม่อนุญาต — รหัสเอเจนต์ไม่ตรงกัน

ข้อผิดพลาด HTTP 429 หรือ 5xx – ข้อผิดพลาดชั่วคราว

หมดเวลาส่งออก

การส่งออกสำเร็จแต่ข้อมูลการวัดและส่งข้อมูลทางไกลไม่ปรากฏใน Defender หรือ Purview

เนื้อหาที่เกี่ยวข้อง

คำติชม

แหล่งทรัพยากรเพิ่มเติม