Microsoft OpenTelemetry Distro

Microsoft OpenTelemetry Distro adalah distribusi observabilitas terpadu yang menyediakan satu pengalaman onboarding untuk mengumpulkan jejak, metrik, dan log dari aplikasi agenik maupun nonagenik. Distro ini mendukung observabilitas untuk Microsoft Agent 365, Microsoft Foundry, Azure Monitor, serta backend yang kompatibel dengan OpenTelemetry Protocol (OTLP). Distro ini mendukung .NET, Node.js, dan Python, serta menyederhanakan penyiapan yang terfragmentasi di berbagai tumpukan observabilitas dengan satu impor dan satu panggilan konfigurasi.

Manfaat utama

Microsoft OpenTelemetry Distro menawarkan manfaat berikut:

  • Satu paket, satu API: Ganti beberapa paket eksportir dan instrumentasi dengan satu dependensi.
  • Dukungan multi-backend: Kirim telemetri ke Azure Monitor, titik akhir yang kompatibel dengan OpenTelemetry Protocol (OTLP) seperti Datadog, Grafana, atau New Relic, dan Microsoft Agent 365 secara bersamaan.
  • Instrumentasi bawaan: Gunakan instrumentasi otomatis untuk HTTP, database, Azure SDK, Azure Functions, dan lainnya tanpa konfigurasi tambahan.
  • Berbasis standar: Didasarkan pada OpenTelemetry, kerangka kerja observabilitas standar industri.
  • Boilerplate minimal: Tambahkan satu impor dan satu panggilan fungsi ke titik entri aplikasi Anda.

Penginstalan dan konfigurasi

Panduan ini menunjukkan kepada Anda cara menambahkan observabilitas ke aplikasi Anda dengan Microsoft OpenTelemetry Distro. Distro secara otomatis mengumpulkan pelacakan, metrik, dan log dengan instrumentasi bawaan, dan mengekspor telemetri ke Azure Monitor, titik akhir OpenTelemetry Protocol (OTLP) apa pun, atau Microsoft Agent 365.

Menginstal pustaka

Untuk mulai menggunakan Microsoft OpenTelemetry Distro, instal pustaka yang sesuai untuk platform pengembangan Anda menggunakan pengelola paket bahasa Anda.

Prasyarat: Python 3.10 atau yang lebih baru.

pip install microsoft-opentelemetry

Konfigurasi

Eksportir Agent 365 tidak menggunakan string koneksi. Titik akhirnya ditemukan secara otomatis berdasarkan penyewa. Untuk mengaktifkan ekspor ke Agent 365, atur target eksportir dan sediakan token resolver yang mengembalikan token akses untuk setiap ID agen dan ID penyewa yang diberikan.

Panggil use_microsoft_opentelemetry() untuk mengaktifkan observabilitas.

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
    ),
)

Untuk resolusi token kustom (daripada token resolver default), lihat Token resolver manual.

Anda dapat menyesuaikan perilaku eksportir dengan meneruskan kwargs a365_* opsional ke use_microsoft_opentelemetry().

Parameter Deskripsi Default
a365_use_s2s_endpoint Ketika True, menggunakan jalur titik akhir layanan ke layanan. False
a365_max_queue_size Ukuran maksimum antrean untuk prosesor batch. 2048
a365_scheduled_delay_ms Penundaan dalam milidetik antara batch ekspor. 5000
a365_exporter_timeout_ms Batas waktu dalam milidetik untuk operasi ekspor. 30000
a365_max_export_batch_size Ukuran batch maksimum untuk operasi ekspor. 512

Propagasi konteks

Untuk mempertahankan observabilitas di seluruh operasi Agent 365 terdistribusi, lakukan propagasi konteks. Ketika Anda melakukan propagasi konteks melalui agen dan layanan, pastikan bahwa penelusuran, log, dan metrik dikorelasikan dengan benar di seluruh siklus hidup permintaan. Korelasi ini diperlukan untuk pengalaman pemantauan Microsoft Agent 365 yang lengkap dan efektif.

Atribut bagasi

Gunakan BaggageBuilder untuk menetapkan informasi kontekstual yang mengalir melalui semua rentang dalam permintaan. SDK menerapkan SpanProcessor yang menyalin semua entri bagasi yang tidak kosong ke setiap rentang yang baru dimulai tanpa menimpa atribut yang sudah ada.

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

Untuk mengisi BaggageBuilder secara otomatis dari TurnContext, gunakan helper populate dalam paket microsoft-opentelemetry. Fungsi helper ini secara otomatis mengekstrak detail pemanggil, agen, penyewa, saluran, dan percakapan dari aktivitas.

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

Middleware bagasi

Jika agen Anda menggunakan paket integrasi hosting, daftarkan middleware bagasi untuk secara otomatis mengisi bagasi pada setiap permintaan yang masuk. Langkah ini menghilangkan kebutuhan untuk memanggil BaggageBuilder secara manual di setiap handler aktivitas.

Di Python, daftarkan middleware bagasi melalui ObservabilityHostingManager.configure() alih-alih langsung pada adapter.

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

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

Middleware melewatkan pengaturan bagasi untuk balasan asinkron (peristiwa ContinueConversation) untuk menghindari penimpaan bagasi yang sudah ditetapkan oleh permintaan asal.

Memvalidasi data yang mengalir dalam produk

Untuk melihat telemetri agen di Microsoft Purview atau Microsoft Defender, pastikan persyaratan berikut terpenuhi:

Instrumentasi otomatis

Microsoft OpenTelemetry Distro menggabungkan alur OpenTelemetry standar dengan instrumentasi yang dikuratori Microsoft. Distro dapat mengumpulkan telemetri aplikasi, telemetri infrastruktur, telemetri agen, dan telemetri AI generatif, tergantung pada bahasa dan konfigurasi.

Kategori Cakupan
Alur sinyal Jejak, metrik, dan log.
Deteksi sumber daya Konteks layanan, host, cloud, dan runtime Azure jika didukung.
Instrumentasi infrastruktur Klien HTTP, ASP.NET Core, Azure SDK, database, dan kerangka kerja pengelogan jika didukung.
Instrumentasi AI generatif OpenAI, Azure OpenAI, Kernel Semantik, LangChain, OpenAI Agents SDK, dan Agent Framework jika didukung.
Cakupan agen manual Pemanggilan agen, pelaksanaan alat, inferensi, dan telemetri keluaran jika didukung.
Eksportir dan prosesor Azure Monitor, Microsoft Agent 365, OTLP, output konsol, prosesor rentang, prosesor log, dan pembaca metrik.

Cakupan instrumentasi

Bahasa Instrumentasi aplikasi umum Instrumentasi AI generatif dan agen umum
Python Sumber daya OpenTelemetry, prosesor, pembaca, pengelogan, metrik, dan jejak. Kernel Semantik, OpenAI Agents SDK, Agent Framework, LangChain, bagasi Microsoft Agent 365, dan cakupan Microsoft Agent 365.
Node.js HTTP, Azure SDK, Azure Functions, MongoDB, MySQL, PostgreSQL, Redis, Bunyan, dan Winston. OpenAI Agents SDK, LangChain, bagasi Microsoft Agent 365, dan cakupan Microsoft Agent 365.
.NET ASP.NET Core, HttpClient, SQL Client, Azure SDK, deteksi sumber daya, metrik, dan log. Cakupan Kernel Semantik, OpenAI dan Azure OpenAI, Agent Framework, bagasi Microsoft Agent 365, serta Microsoft Agent 365.

Instrumentasi otomatis memantau sinyal telemetri yang dipancarkan oleh pustaka dan kerangka kerja yang didukung. Instrumentasi manual digunakan ketika aplikasi perlu mendeskripsikan operasi khusus agen, seperti pemanggilan, eksekusi alat, inferensi, atau output asinkron.

Tambahkan sumber, meteran, prosesor, atau pembaca OpenTelemetry kustom ketika aplikasi Anda menghasilkan telemetri yang tidak tercakup oleh instrumentasi bawaan.

Penting

Instrumentasi otomatis hanya mengisi atribut OpenTelemetry standar. Itu tidak mencakup semua atribut yang diperlukan Agent 365. Anda harus menambahkan atribut khusus Microsoft melalui BaggageBuilder. Untuk melihat atribut yang diperlukan, lihat Menyimpan atribut validasi.

Pustaka instrumentasi bawaan

Instrumentasi otomatis mendengarkan telemetri yang dihasilkan oleh kerangka kerja yang didukung dan meneruskannya melalui alur OpenTelemetry Distro. Untuk skenario agen, atur bagasi seperti ID penyewa dan ID agen sebelum kerangka kerja yang telah diinstrumentasi membuat rentang.

Kerangka Python Node.js .NET
Kernel Semantik Didukung Tidak didukung Didukung
OpenAI dan OpenAI Agents SDK Didukung Didukung Didukung
Agent Framework Didukung Tidak didukung Didukung
LangChain Didukung Didukung Tidak terdaftar

Kernel Semantik

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},
    },
)

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},
    },
)

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},
    },
)

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},
    },
)

Instrumentasi manual

Gunakan instrumentasi manual saat instrumentasi otomatis tidak menjelaskan pengoperasian agen dengan cukup detail. Cakupan manual memungkinkan aplikasi menjelaskan aktivitas agen umum dengan cara yang konsisten di seluruh bahasa.

Scope Gunakan untuk
InvokeAgentScope Awal dan penyelesaian pemanggilan agen.
ExecuteToolScope Panggilan alat yang dibuat oleh agen.
InferenceScope Operasi inferensi model AI
OutputScope Output yang harus direkam setelah cakupan asal selesai.

Gunakan kembali nilai permintaan dan identitas agen yang sama di seluruh cakupan dalam satu permintaan agar telemetri terkait dapat dikorelasikan.

Pemanggilan agen

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."])

Eksekusi alat

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)

Inferensi

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"])

Output

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

Dokumentasi produk harus menentukan persyaratan validasi khusus produk untuk cakupan ini.

Validasi lokal

Validasi lokal memastikan bahwa aplikasi menghasilkan telemetri sebelum tujuan khusus produk divalidasi. Gunakan output konsol atau titik akhir OTLP lokal untuk memeriksa apakah jejak, metrik, dan log dibuat.

Validasi dengan titik akhir OTLP lokal

Konfigurasikan Distro untuk mengirim telemetri ke kolektor lokal atau titik akhir yang kompatibel dengan OTLP.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry()

Validasi dengan output lokal

Gunakan output lokal saat Anda ingin mengonfirmasi instrumentasi sebelum mengirim telemetri ke tujuan jarak jauh.

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.

Tinjau output lokal untuk rentang dari sumber yang diharapkan, seperti permintaan HTTP, panggilan OpenAI atau Azure OpenAI, cakupan pemanggilan agen, cakupan eksekusi alat, atau cakupan inferensi. Validasi khusus tujuan terdapat dalam dokumentasi produk untuk tujuan tersebut.

Menyiapkan autentikasi manual

Saat Anda menggunakan eksportir Agent 365, Anda harus menyediakan mekanisme untuk memberikan token autentikasi. Token resolver bekerja pada setiap batch ekspor menggunakan ID agen dan ID penyewa dari konteks bagasi aktif. Distro mendukung dua pendekatan.

Kiat

Jika Anda membangun agen dengan Agen SDK Microsoft 365, lihat Penyiapan Autentikasi Observabilitas untuk Agen SDK untuk petunjuk langkah demi langkah dalam mengonfigurasi akuisisi token OBO dan S2S untuk agen agenik dan non-agenik.

Token resolver manual

Gunakan resolver manual saat Anda memperoleh token di luar alur Agent Framework, saat Anda membangun aplikasi non-Agent Framework, atau saat Anda menggunakan autentikasi layanan ke layanan (S2S) (alur kredensial klien). Agen dapat menghasilkan token mereka sendiri, misalnya melalui Pustaka Autentikasi Microsoft (MSAL) atau metode akuisisi token lainnya, tetapi mereka perlu memastikan token memiliki cakupan observabilitas yang sesuai (api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite).

Catatan

Untuk autentikasi layanan ke layanan (S2S), Anda harus menggunakan pendekatan token resolver manual ini. Cache token agenik hanya mendukung alur autentikasi atas nama (OBO).

Contoh berikut menampilkan pola token resolver OBO (atas nama) — agen memperoleh token pengguna melalui handler autentikasi agenik dan menukarnya dengan token cakupan observabilitas. Untuk contoh S2S (layanan ke layanan) dan perbandingan autentikasi OBO vs S2S, lihat Penyiapan Autentikasi Observabilitas untuk Agent SDK.

Resolver harus sinkron. Dapatkan token di handler aktivitas asinkron Anda (atau melalui MSAL) dan simpan dalam cache untuk digunakan oleh resolver.

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",
    )

Cache token agenik dengan aplikasi Agent Framework

Untuk aplikasi Agent Framework yang menggunakan autentikasi on-behalf-of (OBO), distro secara otomatis mendaftarkan IExporterTokenCache<AgenticTokenStruct> melalui DI ketika Anda tidak menetapkan TokenResolver kustom. Agen Anda memanggil RegisterObservability() saat runtime untuk menyediakan kredensial, dan cache menangani akuisisi dan refresh token.

Catatan

Pendekatan ini hanya mendukung alur autentikasi atas nama (OBtO). Untuk autentikasi layanan ke layanan (S2S), gunakan token resolver manual sebagai alternatif.

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,
    )

Menyimpan atribut validasi

Untuk validasi penyimpanan yang berhasil, agen Anda harus mengimplementasikan InvokeAgentScope, InferenceScope, dan ExecuteToolScope. Setiap cakupan berhubungan dengan operasi rentang dalam skema kanonis:

Cakupan SDK Operasi rentang Kode referensi universal
InvokeAgentScope invoke_agent IA
ExecuteToolScope execute_tool ET
InferenceScope chat CH
OutputScope output_messages OM

Untuk daftar lengkap atribut wajib dan opsional per cakupan—termasuk penjelasan setiap atribut, panduan pemilihan nilai, dan atribut yang dapat dicari melalui perburuan tingkat lanjut Microsoft Defender—lihat Referensi atribut observabilitas Agent 365. Kolom Berlaku untuk menunjukkan cakupan tempat setiap atribut berada, dan kolom Wajib membedakan atribut yang wajib (M) dari yang opsional (O).

Menguji agen dengan observabilitas

Setelah menerapkan observabilitas, verifikasi bahwa telemetri telah tercatat:

  1. Membuka https://admin.cloud.microsoft/#/agents/all.
  2. Pilih agen Anda, lalu pilih Aktivitas.
  3. Pastikan bahwa sesi dan panggilan ke alat muncul.

Sampel aplikasi dan konfigurasi tingkat lanjut

Untuk sampel kerja dan opsi konfigurasi tingkat lanjut, lihat repositori GitHub untuk setiap bahasa:

Pemecahan masalah

Bagian ini menjelaskan masalah umum saat menerapkan dan menggunakan Microsoft OpenTelemetry Distro dengan Agent 365.

Masalah Deskripsi
Data observabilitas tidak muncul Tidak ada telemetri yang terlihat karena ekspor Agent 365 tidak diaktifkan, penyiapan tidak lengkap, atau resolusi token gagal.
ID penyewa atau ID agen tidak ada - rentang dilewati Rentang difilter sebelum ekspor saat atribut identitas penyewa atau agen yang diperlukan tidak ada.
Kegagalan resolusi token - ekspor dilewati atau tidak diizinkan Ekspor dilewati atau ditolak ketika token resolver tidak mengembalikan token atau terjadi kesalahan saat akuisisi token.
HTTP 401 Tidak Sah Permintaan sampai ke layanan tetapi autentikasi gagal karena token tidak valid, kedaluwarsa, atau untuk audiens yang salah.
HTTP 403 Forbidden Otorisasi gagal akibat tidak adanya lisensi penyewa atau izin menulis observabilitas.
HTTP 403 Forbidden - Ketidakcocokan ID Agen Layanan menolak ekspor ketika ID agen dalam permintaan tidak cocok dengan identitas agen yang diotorisasi oleh token.
Kesalahan HTTP 429 atau 5xx - Kesalahan sementara Pembatasan sementara atau ketidakstabilan backend mengganggu ekspor dan mungkin memerlukan pengulangan atau penyesuaian batch.
Batas waktu ekspor Operasi ekspor melebihi batas waktu karena penundaan jaringan atau latensi respons titik akhir.
Ekspor berhasil tetapi telemetri tidak muncul di Defender atau Purview Penyerapan data berhasil tetapi visibilitas tertunda atau diblokir oleh prasyarat hilir dan persyaratan skema.

Kiat

Panduan Pemecahan Masalah Agent 365 berisi rekomendasi pemecahan masalah tingkat tinggi, praktik terbaik, dan tautan ke konten pemecahan masalah untuk setiap bagian dari siklus hidup pengembangan Agent 365.

Data observabilitas tidak muncul

Gejala:

  • Agen sedang berjalan
  • Tidak ada telemetri di pusat admin
  • Tidak dapat melihat aktivitas agen

Akar penyebab:

  • Ekspor Agent 365 tidak diaktifkan
  • Kesalahan konfigurasi
  • Masalah pada token resolver

Solusi: Coba langkah-langkah berikut untuk menyelesaikan masalah:

  • Pastikan ekspor Agent 365 sudah diaktifkan

    Anda harus mengaktifkan eksportir Agent 365 secara eksplisit. Jika tidak diatur, distro dapat beralih ke eksportir konsol atau tidak mengekspor apa pun. Aktifkan dalam kode:

    from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_a365=True,
    a365_enable_observability_exporter=True,
    a365_token_resolver=my_token_resolver,
)

    Atau atur variabel lingkungan:

    export ENABLE_A365_OBSERVABILITY_EXPORTER=true

    Catatan

    ENABLE_A365_OBSERVABILITY_EXPORTER adalah pengalih sekunder yang hanya berlaku ketika enable_a365=True diatur dalam kode. Anda juga dapat mengontrolnya melalui kwarg a365_enable_observability_exporter.

  • Periksa konfigurasi token resolver

    Eksportir memerlukan token resolver yang valid yang mengembalikan token pembawa untuk setiap permintaan ekspor. Jika token resolver tidak ada atau mengembalikan null, ekspor akan dilewati secara diam-diam.

  • Aktifkan ekspor konsol dan periksa telemetri secara lokal

    Tambahkan eksportir konsol untuk memverifikasi telemetri yang sedang dihasilkan sebelum mencapai titik akhir Agent 365:

    use_microsoft_opentelemetry(enable_a365=True, enable_console=True)

  • Aktifkan pengelogan berlebihan

    import logging

logging.basicConfig(level=logging.DEBUG)

  • Periksa log untuk kesalahan ekspor

    Gunakan perintah az webapp log tail untuk mencari kesalahan terkait observabilitas di log:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

ID penyewa atau ID agen hilang — rentang diabaikan

Gejala: Sistem secara diam-diam mengabaikan rentang dan tidak pernah mengekspornya. Beberapa platform mencatat jumlah rentang yang dilewati atau pesan seperti No spans with tenant/agent identity found. Yang lain membuangnya tanpa melakukan pengelogan.

Resolution:

  • Sebelum diekspor, distro membagi rentang berdasarkan identitas penyewa dan agen. Rentang yang tidak memiliki ID penyewa atau ID agen akan dibuang dan tidak pernah dikirim ke layanan.
  • Pastikan BaggageBuilder telah disiapkan dengan ID penyewa dan ID agen sebelum membuat rentang. Nilai ini diteruskan melalui konteks OpenTelemetry dan melekat pada semua rentang yang dibuat dalam cakupan bagasi. Untuk API khusus platform, lihat Atribut bagasi.
  • Jika Anda menggunakan middleware bagasi atau mengubah helper konteks dari paket integrasi hosting, pastikan aktivitas TurnContext memiliki penerima yang valid dengan identitas agen.

Kegagalan resolusi token — ekspor dilewati atau tidak diizinkan

Gejala: Token resolver mengembalikan null atau melempar kesalahan. Bergantung pada platformnya, ekspor dilewati sepenuhnya atau gagal dengan HTTP 401.

Resolution:

  • Token resolver diperlukan. Jika tidak tersedia, eksportir melempar kesalahan saat memulai. Verifikasi bahwa token resolver telah disediakan dan mengembalikan token pembawa yang valid.
  • Pastikan ID penyewa dan ID agen yang benar diteruskan ke BaggageBuilder, karena nilai-nilai ini akan diteruskan ke token resolver.
  • Untuk agen yang di-host di Azure, pastikan Identitas Terkelola memiliki izin API yang diperlukan untuk cakupan observabilitas.
  • Untuk aplikasi .NET yang menggunakan paket hosting Agent Framework, pertukaran token ditangani secara otomatis melalui DI. Jika token hilang, pastikan Microsoft.Agents.A365.Observability.Hosting telah diinstal dan didaftarkan.

HTTP 401 Tidak Sah

Gejala: Ekspor gagal dengan HTTP 401. Eksportir tidak mencoba ulang kesalahan ini.

Resolution:

  • Verifikasi bahwa audiens token sesuai dengan cakupan titik akhir observabilitas.
  • Periksa apakah token resolver tidak mengembalikan token pengguna delegasi, token untuk audiens yang salah, atau token kedaluwarsa.

HTTP 403 Forbidden

Gejala: Ekspor gagal dengan HTTP 403. Eksportir tidak mencoba ulang kesalahan ini.

Penyebab utama: Kesalahan HTTP 403 dapat memiliki berbagai penyebab. Periksa resolusi berikut secara berurutan.

Resolution:

  • Lisensi hilang — Verifikasi bahwa penyewa Anda memiliki salah satu lisensi berikut yang ditetapkan di Pusat admin Microsoft 365:

    • Uji - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • Izin Agent365.Observability.OtelWrite tidak ada — Berikan izin untuk identitas Anda (Identitas Terkelola atau pendaftaran aplikasi). Tanpa itu, ekspor telemetri gagal dengan HTTP 403.

Memberikan izin

Gunakan salah satu opsi berikut:

  • Agent 365 CLI

    Memerlukan akun Administrator Global; jalankan dari direktori proyek agen yang berisi a365.config.json, atau gunakan --agent-name.

    a365 setup permissions bot

    Atau, tanpa file konfigurasi:

    a365 setup permissions bot --agent-name "<agent-name>"

  • Portal Entra

    Tidak diperlukan file konfigurasi; memerlukan akses Administrator Global ke pendaftaran aplikasi Blueprint.

    1. Buka portal Entra>Pendaftaran Aplikasi> pilih aplikasi Blueprint Anda.
    2. Buka Izin API>Tambah izin>API yang digunakan organisasi saya> cari 9b975845-388f-4429-889e-eab1ef63949c.
    3. Pilih Izin yang didelegasikan> periksa Agent365.Observability.OtelWrite>Tambah izin.
    4. Ulangi langkah 2-3, kali ini pilih Izin aplikasi> centang Agent365.Observability.OtelWrite>Tambah izin.
    5. Klik Berikan persetujuan admin dan konfirmasi.

    Kedua Agent365.Observability.OtelWrite (Delegasi) maupun Agent365.Observability.OtelWrite (Aplikasi) menampilkan status Granted .

HTTP 403 Forbidden — Ketidakcocokan ID Agen

Gejala: Ekspor gagal dengan HTTP 403 dan pesan server yang mirip dengan 403 Forbidden dengan agent-ID-mismatch gagal memanggil titik akhir pelacakan Agent 365.

Akar penyebab: Kesalahan ini terjadi ketika Anda menggunakan ID klien blueprint bukan ID klien instans agen saat mengatur detail agen. ID agen pada URL ekspor tidak sesuai dengan identitas yang diotorisasi oleh token, sehingga titik akhir pelacakan menolak permintaan tersebut.

Resolution:

  • Verifikasi apakah ID penyewa telah ditambahkan ke daftar penyewa yang diizinkan Agent 365.
  • Atur detail agen dengan ID klien instans agen (bukan ID klien blueprint).
  • Verifikasi URL ekspor yang dihasilkan – URL tersebut dicatat jika Anda mengaktifkan logger. Pastikan ID agen pada URL sesuai dengan ID klien instans agen.
  • Untuk mengaktifkan pengelogan diagnostik per SDK, lihat Validasi Lokal.

Kesalahan HTTP 429 atau 5xx - Kesalahan sementara

Gejala: Ekspor gagal dengan kode status HTTP sementara seperti 429 atau 5xx.

Resolution:

  • Kesalahan ini biasanya bersifat sementara dan akan teratasi sendiri. Distro Python dan JavaScript secara otomatis melakukan percobaan ulang pada kode status HTTP 408, 429, dan 5xx. Distro .NET tidak melakukan percobaan ulang secara otomatis.
  • Jika kesalahan berlanjut, periksa dasbor kesehatan layanan.
  • Pertimbangkan untuk mengurangi frekuensi ekspor dengan meningkatkan penundaan terjadwal antar batch atau ukuran batch ekspor maksimum. Untuk Python dan JavaScript, gunakan parameter exporterOptions atau a365_* yang relevan yang didokumentasikan dalam repositori GitHub. Untuk .NET, gunakan o.Agent365.Exporter.ScheduledDelayMilliseconds dan o.Agent365.Exporter.MaxExportBatchSize.

Batas waktu ekspor

Gejala: Batas waktu upaya ekspor.

Resolution:

  • Periksa konektivitas jaringan ke titik akhir observabilitas.

  • Batas waktu permintaan HTTP default adalah 30 detik di semua platform. Jika Anda sering mengalami batas waktu, tingkatkan nilai batas waktu di opsi eksportir Anda:

    use_microsoft_opentelemetry(
    enable_a365=True,
    a365_token_resolver=my_token_resolver,
    # No direct timeout kwarg — set via environment variable or exporterOptions if supported
)

    Lihat repositori Python untuk daftar opsi lengkap a365_*.

Ekspor berhasil tetapi telemetri tidak muncul di Defender atau Purview

Gejala: Log menampilkan bahwa ekspor berhasil (HTTP 200), namun telemetri tidak terlihat di Microsoft Defender atau Microsoft Purview.

Resolution:

  • Pastikan Anda memenuhi prasyarat untuk melihat log yang diekspor:
  • Telemetri dapat membutuhkan beberapa menit untuk muncul setelah ekspor berhasil. Tunggu sebelum menyelidiki lebih lanjut.
  • Verifikasi bahwa rentang berisi atribut microsoft.tenant.id dan gen_ai.agent.id yang valid. Atribut identitas yang hilang menyebabkan rentang dibuang di sisi server, meskipun ekspor HTTP memberikan respons 200.

Konten terkait

  • Last updated on