Menggunakan OpenTelemetry dan pelacakan aktivitas

Penyusun API Data (DAB) mendukung OpenTelemetry untuk pelacakan dan metrik terdistribusi, memungkinkan Anda memantau dan mendiagnosis perilaku di seluruh REST, GraphQL, operasi database, dan middleware internal.

Diagram memperlihatkan alur OpenTelemetry.

Prasyarat

  • File konfigurasi DAB yang ada.
  • Menjalankan pengumpul OpenTelemetry atau backend (misalnya, Azure Monitor atau Jaeger).
  • CLI pembangun API Data. Menginstal CLI

Jalankan alat

Gunakan dab add-telemetry untuk menambahkan pengaturan OpenTelemetry ke konfigurasi Anda.

  1. Pastikan Anda memiliki file konfigurasi. Jika Anda perlu membuatnya, jalankan:

    dab init \
    --database-type mssql \
    --connection-string "<sql-connection-string>"

  2. Tambahkan pengaturan OpenTelemetry ke file konfigurasi Anda.

    dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

  3. Memulai DAB.

    dab start

Lakukan pengujian pada backend telemetri Anda

  1. Buka backend OpenTelemetry atau antarmuka pengguna kolektor Anda.

  2. Pastikan bahwa tracing dan metrik diterima untuk panggilan REST, GraphQL, atau database.

Nota

Dasbor .NET Aspire adalah bagian ideal dari perulangan pengembang. Ini mencakup tampilan bawaan untuk pelacakan dan metrik OpenTelemetry.

Jejak penyusun API Data

DAB membuat "aktivitas" dari OpenTelemetry untuk:

  • Permintaan HTTP masuk (titik akhir REST)
  • Operasi GraphQL
  • Kueri database (per entitas)
  • Langkah-langkah middleware internal (misalnya, penanganan permintaan, pelacakan kesalahan)
  • Eksekusi alat MCP (setiap panggilan alat bahasa manipulasi data (DML) dan pemanggilan alat kustom)

Nota

Fungsionalitas penyusun API Data yang dijelaskan di bagian ini tersedia di versi 2.0 dan yang lebih baru. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Setiap aktivitas mencakup tag terperinci (metadata), seperti:

  • http.method,http.url,http.querystring,status.code
  • action.type (CRUD, operasi GraphQL)
  • user.role, user-agent
  • data-source.type, data-source.name
  • api.type (REST atau GraphQL)

Kesalahan dan pengecualian juga ditelusuri dengan info terperinci.

Metrik API Pembangun Data

DAB memancarkan metrik OpenTelemetry seperti:

  • Total Permintaan: Penghitung, diberi label menurut metode HTTP, status, endpoint, dan jenis API.
  • Kesalahan: Penghitung, diberi label berdasarkan jenis kesalahan, metode HTTP, status, titik akhir, dan jenis API.
  • Durasi Permintaan: Histogram (dalam milidetik), dilabeli oleh metode HTTP, status, titik akhir, dan jenis API.
  • Permintaan Aktif: Penghitung naik/turun untuk permintaan bersamaan.

Metrik menggunakan .NET Meter API dan OpenTelemetry SDK.

Configuration

open-telemetry Tambahkan bagian di bawah runtime.telemetry dalam file konfigurasi Anda.

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://otel-collector:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Command-line

Konfigurasikan OpenTelemetry melalui dab add-telemetry.

  • --otel-enabled
  • --otel-endpoint
  • --otel-protocol
  • --otel-service-name
  • --otel-headers

Example

dab add-telemetry \
    -c dab-config.json \
    --otel-enabled true \
    --otel-endpoint "http://localhost:4317" \
    --otel-protocol "grpc" \
    --otel-service-name "dab"

Konfigurasi yang dihasilkan

Nota

Opsi OpenTelemetry tidak tersedia di dab configure.

{
    "runtime": {
        "telemetry": {
            "open-telemetry": {
                "enabled": true,
                "endpoint": "http://localhost:4317",
                "service-name": "dab",
                "exporter-protocol": "grpc"
            }
        }
    }
}

Ekspor dan visualisasi

Telemetri diekspor melalui .NET OpenTelemetry SDK ke back end yang dikonfigurasi seperti Azure Monitor atau Jaeger. Pastikan back end Anda berjalan dan dapat dijangkau pada alamat yang ditentukan endpoint. Anda dapat menggunakan back end yang kompatibel dengan OpenTelemetry untuk visualisasi.

OpenTelemetry SDK mengontrol waktu ekspor. Ini mengekspor jejak ketika aktivitas selesai. Ini mengekspor metrik pada interval berkala yang dikonfigurasi oleh SDK. Jika Anda tidak mengatur interval, SDK menggunakan defaultnya.

Nota

Kontainer sementara yang dimatikan dengan cepat dapat keluar sebelum ekspor selesai. Izinkan jendela penghentian yang mulus dan menghindari penghentian agresif sehingga telemetri yang tertunda dapat dikirimkan.

Catatan implementasi

  • Jejak dan metrik mencakup semua operasi REST, GraphQL, MCP, dan database
  • Middleware dan pengendali kesalahan juga memancarkan telemetri
  • Konteks disebarluaskan melalui permintaan

Konten terkait

  • Last updated on