Alur Kerja Kerangka Kerja Agen Microsoft - Pengamatan

Pengamatan memberikan wawasan tentang status internal dan perilaku alur kerja selama eksekusi. Ini termasuk kemampuan pengelogan, metrik, dan pelacakan yang membantu memantau dan men-debug alur kerja.

Petunjuk / Saran

Pengamatan adalah fitur yang mencakup keseluruhan kerangka kerja dan tidak terbatas pada alur kerja. Untuk informasi selengkapnya, lihat Pengamatan.

Selain telemetri GenAI standar, Alur Kerja Kerangka Kerja Agen memancarkan rentang, log, dan metrik tambahan untuk memberikan wawasan yang lebih mendalam tentang eksekusi alur kerja. Fitur pengamatan ini membantu pengembang memahami alur pesan, performa pelaksana, dan kesalahan apa pun yang mungkin terjadi.

Aktifkan Observabilitas

Lihat Mengaktifkan Observabilitas untuk petunjuk tentang mengaktifkan pengamatan dalam aplikasi Anda.

Lihat Mengaktifkan Observabilitas untuk petunjuk tentang mengaktifkan pengamatan dalam aplikasi Anda.

Rentang Alur Kerja

Rentang berikut dihasilkan selama eksekusi alur kerja:

Nama Span Deskripsi
workflow.build Dipancarkan untuk setiap build alur kerja.
workflow.session Jangkauan luar mewakili seluruh masa pakai eksekusi alur kerja, dari awal hingga berhenti atau terjadi kesalahan.
workflow_invoke Dipancarkan untuk setiap siklus input-ke-halt dalam sesi alur kerja.
executor.process {executor_id} Dikeluarkan untuk setiap eksekutor yang memproses pesan. ID eksekutor ditambahkan ke nama rentang.
edge_group.process Dikeluarkan untuk setiap kelompok tepi yang memproses pesan.
message.send Dipancarkan untuk setiap pesan yang dikirimkan dari satu pelaksana ke pelaksana lainnya.

Rentang berikut dihasilkan selama eksekusi alur kerja:

Nama Span Deskripsi
workflow.build Dipancarkan untuk setiap build alur kerja.
workflow.run Dikeluarkan untuk setiap pelaksanaan alur kerja.
executor.process {executor_id} Dikeluarkan untuk setiap eksekutor yang memproses pesan. ID eksekutor ditambahkan ke nama rentang.
edge_group.process {edge_group_type} Dikeluarkan untuk setiap kelompok tepi yang memproses pesan. Jenis grup tepi ditambahkan ke nama cakupan.
message.send Dipancarkan untuk setiap pesan yang dikirimkan dari satu pelaksana ke pelaksana lainnya.

Rentang berikut dihasilkan selama eksekusi alur kerja:

Nama Span Deskripsi
workflow.build Dipancarkan untuk setiap build alur kerja.
workflow.session Rentang luar mewakili masa pakai sesi eksekusi alur kerja.
workflow_invoke Dipancarkan untuk setiap siklus input-ke-halt dalam sesi alur kerja.
executor.process {executor_id} Dikeluarkan untuk setiap eksekutor yang memproses pesan. ID eksekutor ditambahkan ke nama rentang.
edge_group.process Dikeluarkan untuk setiap kelompok tepi yang memproses pesan.
message.send Dipancarkan untuk setiap pesan yang dikirim dari satu pelaksana ke eksekutor lainnya.

Atribut Rentang

Span membawa atribut yang memberikan konteks tambahan tentang operasi. Atribut berikut diatur pada rentang alur kerja:

Attribute Rentang Deskripsi
workflow.id workflow.build, workflow.session Pengidentifikasi unik alur kerja.
workflow.name workflow.session Nama alur kerja.
workflow.description workflow.session Deskripsi alur kerja.
workflow.definition workflow.build Definisi JSON dari grafik alur kerja.
session.id workflow.session Pengidentifikasi sesi unik.
executor.id executor.process Identifikasi unik pelaksana.
executor.type executor.process Nama jenis pelaksana.
executor.input executor.process Pesan input. Hanya atur saat data sensitif diaktifkan.
executor.output executor.process Keluaran eksekutor. Hanya atur saat data sensitif diaktifkan.
message.type executor.process, message.send Nama jenis pesan.
message.content message.send Konten pesan. Hanya atur saat data sensitif diaktifkan.
message.source_id message.send ID pelaksana yang mengirim pesan.
message.target_id message.send ID pelaksana target, jika ditentukan.
edge_group.type edge_group.process Jenis grup tepi.
edge_group.delivered edge_group.process Apakah pesan sudah dikirimkan (boolean)
edge_group.delivery_status edge_group.process Hasil pengiriman (lihat Status Pengiriman Grup Edge).
error.type Setiap rentang pada kesalahan Nama jenis pengecualian.
Attribute Rentang Deskripsi
workflow.id workflow.build, workflow.run Pengidentifikasi unik alur kerja.
workflow.name workflow.run Nama alur kerja.
workflow.description workflow.run Deskripsi alur kerja.
workflow.definition workflow.build Definisi JSON dari grafik alur kerja.
workflow_builder.name workflow.build Nama penyusun alur kerja.
workflow_builder.description workflow.build Deskripsi penyusun alur kerja.
executor.id executor.process Identifikasi unik pelaksana.
executor.type executor.process Nama jenis pelaksana.
message.type executor.process, message.send Nama jenis pesan.
message.payload_type executor.process Jenis data dari payload pesan.
message.destination_executor_id message.send ID pelaksana target, jika ditentukan.
message.source_id edge_group.process ID pelaksana yang mengirim pesan.
message.target_id edge_group.process ID pelaksana target, jika ditentukan.
edge_group.type edge_group.process Jenis grup tepi.
edge_group.id edge_group.process Pengidentifikasi unik grup tepi.
edge_group.delivered edge_group.process Apakah pesan sudah dikirimkan (boolean)
edge_group.delivery_status edge_group.process Hasil pengiriman (lihat Status Pengiriman Grup Edge).
Attribute Rentang Deskripsi
workflow.id workflow.build, workflow.session, workflow_invoke ID pelaksana yang memulai alur kerja.
workflow.name workflow.session, workflow_invoke Nama alur kerja, jika ditetapkan.
workflow.description workflow.session, workflow_invoke Deskripsi alur kerja, saat diatur.
workflow.definition workflow.build Definisi JSON dari grafik alur kerja.
session.id workflow.session, workflow_invoke Pengidentifikasi sesi alur kerja.
executor.id executor.process ID pelaksana.
executor.implementation.id executor.process ID implementasi pelaksana.
executor.input executor.process Pesan input. Hanya atur saat data sensitif diaktifkan.
executor.output executor.process Keluaran eksekutor. Hanya atur saat data sensitif diaktifkan.
message.type executor.process Nama jenis pesan yang diproses.
message.content message.send Konten pesan. Hanya atur saat data sensitif diaktifkan.
message.source_id edge_group.process, message.send ID pelaksana yang mengirim pesan.
message.target_id edge_group.process, message.send ID eksekutor target, jika ditentukan.
edge_group.type edge_group.process Jenis grup tepi yang sedang diproses.
edge_group.delivered edge_group.process Apakah pesan telah tersampaikan.
edge_group.delivery_status edge_group.process Hasil pengiriman (lihat Status Pengiriman Grup Edge).
error.type Setiap rentang pada kesalahan Nama jenis pengecualian.
error.message Setiap rentang pada kesalahan Pesan pengecualian.

Peristiwa Rentang Waktu

Peristiwa rentang adalah entri log terstruktur yang melekat pada rentang, menyediakan garis waktu momen kunci dalam setiap rentang.

Nama Peristiwa Rentang Deskripsi
build.started workflow.build Dipancarkan ketika proses build dimulai.
build.validation_completed workflow.build Dikeluarkan saat validasi build berhasil.
build.completed workflow.build Dimunculkan ketika build selesai dengan sukses.
build.error workflow.build Dikeluarkan saat build gagal.
session.started workflow.session Dikeluarkan saat sesi alur kerja dimulai.
session.completed workflow.session Dikeluarkan saat sesi alur kerja selesai.
session.error workflow.session Dipancarkan ketika sesi alur kerja mengalami kesalahan.
workflow.started workflow_invoke Dipancarkan saat pemanggilan alur kerja dimulai.
workflow.completed workflow_invoke Dipancarkan saat pemanggilan alur kerja selesai.
workflow.error workflow_invoke Diterbitkan ketika panggilan proses kerja mengalami kesalahan.
Nama Peristiwa Rentang Deskripsi
build.started workflow.build Dipancarkan ketika proses build dimulai.
build.validation_completed workflow.build Dikeluarkan saat validasi build berhasil.
build.completed workflow.build Dimunculkan ketika build selesai dengan sukses.
build.error workflow.build Dikeluarkan saat build gagal.
workflow.started workflow.run Dipancarkan saat alur kerja berjalan dimulai.
workflow.completed workflow.run Dipancarkan saat alur kerja berjalan selesai.
workflow.error workflow.run Dipancarkan saat alur kerja berjalan mengalami kesalahan.
Nama Peristiwa Rentang Deskripsi
build.started workflow.build Dipancarkan ketika proses build dimulai.
build.validation_completed workflow.build Dikeluarkan saat validasi build berhasil.
build.completed workflow.build Dimunculkan ketika build selesai dengan sukses.
build.error workflow.build Dikeluarkan saat build gagal.
session.started workflow.session Dikeluarkan saat sesi alur kerja dimulai.
session.completed workflow.session Dikeluarkan saat sesi alur kerja selesai.
session.error workflow.session Dipancarkan ketika sesi alur kerja mengalami kesalahan.
workflow.started workflow_invoke Dipancarkan saat pemanggilan alur kerja dimulai.
workflow.completed workflow_invoke Dipancarkan saat pemanggilan alur kerja selesai.
workflow.error workflow_invoke Diterbitkan ketika panggilan proses kerja mengalami kesalahan.

Ketika eksekutor mengirim pesan ke eksekutor lain, message.send span dibuat sebagai anak dari executor.process span. Namun, rentang pelaksana target executor.processbukan merupakan bagian dari rentang message.send karena eksekusinya tidak bersarang. Sebaliknya, rentang pelaksana target executor.process ke rentang pelaksana sumber . Penautan ini membuat jalur yang dapat dilacak melalui eksekusi alur kerja tanpa menyiratkan hierarki panggilan berlapis.

Pendekatan penautan yang sama berlaku untuk edge_group.process rentang, yang ditautkan ke rentang sumber message.send untuk pelacakan kausalitas. Ini mendukung skenario fan-in di mana beberapa rentang sumber berkontribusi pada rentang pemrosesan tunggal.

Status Pengiriman Grup Edge

Rentang pemrosesan grup Edge mencakup atribut status pengiriman yang menunjukkan hasil perutean pesan melalui setiap grup tepi. Atribut edge_group.delivery_status diatur ke salah satu nilai berikut:

Kedudukan Deskripsi
delivered Pesan dikirimkan ke eksekutor target.
dropped type mismatch Pelaksana target tidak dapat menangani jenis pesan.
dropped target mismatch Pesan menentukan target yang tidak cocok dengan tepi ini.
dropped condition false Kondisi perutean ujung dievaluasi sebagai salah.
exception Pengecualian terjadi selama pemrosesan tepi.
buffered Pesan di-buffer, menunggu pesan tambahan (fan-in).

Atribut edge_group.delivered boolean memberikan pemeriksaan cepat apakah pesan berhasil dikirimkan.

Konfigurasi Telemetri

Telemetri alur kerja dapat diaktifkan melalui WithOpenTelemetry metode ekstensi pada penyusun alur kerja. Kelas WorkflowTelemetryOptions ini memberikan kontrol terperinci atas rentang mana yang dipancarkan.

Option Default Deskripsi
EnableSensitiveData false Termasuk input mentah, output, dan konten pesan di dalam atribut span.
DisableWorkflowBuild false Menonaktifkan rentang workflow.build.
DisableWorkflowRun false Menonaktifkan workflow.session dan workflow_invoke rentang.
DisableExecutorProcess false Menonaktifkan rentang executor.process.
DisableEdgeGroupProcess false Menonaktifkan rentang edge_group.process.
DisableMessageSend false Menonaktifkan rentang message.send.

Peringatan

Mengaktifkan data sensitif menyebabkan konten pesan mentah, input pelaksana, dan output eksekutor disertakan dalam telemetri. Hanya aktifkan ini di lingkungan yang aman di mana data telemetri dilindungi dengan tepat.

Telemetri alur kerja diaktifkan melalui fungsi global enable_instrumentation() . Saat instrumentasi diaktifkan, semua rentang alur kerja dipancarkan secara otomatis. Fungsi configure_otel_providers() ini dapat digunakan untuk menyiapkan pengekspor untuk jejak, metrik, dan log.

Peringatan

Tinjau konfigurasi alur telemetri Anda untuk memastikan data sensitif dilindungi dengan tepat saat mengekspor jejak.

Pengamatan alur kerja

Telemetri alur kerja dapat diaktifkan dengan WithTelemetry pada penyusun alur kerja. Gunakan paket tracer OpenTelemetry untuk alur kerja untuk menghubungkan span ke penyedia OpenTelemetry Anda.

Mengaktifkan pelacakan alur kerja

import workflowotel "github.com/microsoft/agent-framework-go/workflow/observability/opentelemetry"

wf, err := workflow.NewBuilder(startExecutor).
    AddEdge(startExecutor, nextExecutor).
    WithTelemetry(
        workflowotel.New(workflowotel.Config{}),
        workflow.TelemetryOptions{EnableSensitiveData: true},
    ).
    Build()

TelemetryOptions dapat menonaktifkan pembuatan/eksekusi alur kerja, proses eksekutor, kelompok edge, atau span pengiriman pesan, dan dapat menyertakan input dan output yang diserialisasi saat EnableSensitiveData diatur.

Mengamati peristiwa alur kerja

Pantau eksekusi alur kerja melalui aliran peristiwa:

for evt := range run.NewEvents() {
    switch e := evt.(type) {
    case workflow.ExecutorCompletedEvent:
        log.Printf("Executor %s completed", e.ExecutorID)
    }
}

Langkah Selanjutnya

  • Last updated on