Reliability and RoutingJuly 15, 2026Big Y

Log Observabilitas AI API: Apa yang Perlu Dicatat untuk Insiden Routing Model

Gunakan log observabilitas AI API untuk men-debug insiden routing model dengan request ID, rute, percobaan ulang, fallback, token, latensi, biaya, dan metadata yang aman untuk privasi.

Observabilitas AI API adalah yang memungkinkan tim engineering merekonstruksi insiden routing model tanpa menebak-nebak. Seorang pengguna melaporkan timeout, model fallback menjawab secara berbeda, provider mengembalikan 429, atau biaya melonjak setelah perpindahan upstream. Tinjauan insiden membutuhkan lebih dari sekadar prompt mentah dan status code. Tinjauan tersebut membutuhkan catatan log yang menunjukkan request, route, rantai retry, model yang dipilih, profil latensi, usage, biaya, dan kontrol privasi atas apa yang disimpan.

Panduan ini adalah checklist di tingkat field untuk log observabilitas AI API dalam insiden routing. Panduan ini ditulis untuk tim yang menggunakan AI gateway, router multi-provider, atau compatibility layer di mana satu request aplikasi dapat melewati beberapa jalur upstream yang mungkin berbeda. Tujuannya bukan menyimpan setiap prompt selamanya. Tujuannya adalah menyimpan metadata yang cukup untuk membuktikan apa yang terjadi sambil tetap mengendalikan input sensitif, output, argumen tool, dan pengenal pelanggan.

Flatkey cocok untuk masalah ini karena copy produk publiknya berfokus pada satu API key, base URL yang kompatibel dengan OpenAI di https://router.flatkey.ai/v1, penagihan terpadu, dan satu dashboard untuk key, usage, dan routing. Flatkey juga merujuk pada switching otomatis dan load balancing di seluruh akun upstream. Fitur-fitur keandalan itu hanya berguna jika log dapat menjawab pertanyaan routing setelah kejadian.

Observabilitas AI API Dimulai dari Pertanyaan Insiden

Sebelum memilih field, definisikan pertanyaan yang harus dijawab oleh incident commander. Untuk routing model, observabilitas AI API harus membuat pertanyaan-pertanyaan ini dapat dijawab dari satu record request atau satu trace yang terhubung:

Aplikasi, environment, tim, key, workflow, dan owner yang aman bagi pelanggan mana yang mengirim request?
Family endpoint, model yang diminta, kebijakan route, dan aturan fallback mana yang berlaku pada saat request?
Provider, model, akun upstream, atau route mana yang benar-benar melayani respons?
Apakah request di-retry, dialihkan, dibatasi, di-queue, diblokir, atau dibatalkan?
Status code, kelas error provider, header rate-limit, timeout, atau event stream mana yang mengubah hasil?
Berapa banyak token input, output, cached, dan reasoning yang dihitung, dan berapa biaya route tersebut?
Apakah kontrol privasi menyimpan payload mentah, payload yang disensor, hanya metadata, atau tidak ada entri log?

Jika sebuah log tidak dapat menjawab pertanyaan-pertanyaan itu, tim akan mengisi kekosongan dengan ingatan Slack, screenshot, dan tiket dukungan provider. Itu memperlambat remediasi dan membuat perubahan route di masa depan lebih sulit untuk dipercaya.

Checklist Log Insiden Routing Model

Tabel di bawah ini adalah aset inti observabilitas AI API untuk artikel ini. Gunakan sebagai checklist implementasi untuk log API LLM, log gateway, atau event data warehouse.

Grup Bidang	Bidang yang Perlu Dicatat	Mengapa Ini Penting dalam Insiden Routing	Catatan Privasi
Correlation IDs	ID permintaan aplikasi, `X-Client-Request-Id`, `x-request-id` penyedia, W3C `traceparent`, ID log gateway, ID event.	Menghubungkan error yang terlihat oleh pengguna, keputusan gateway, permintaan penyedia, span trace, dan tiket dukungan.	Gunakan ID buram. Jangan menyematkan email, IP, nama tenant, atau teks prompt ke dalam field trace.
Tenant and owner	Proyek, lingkungan, ID atau hash kunci API, tim, alur kerja, ID akun yang aman bagi pelanggan, pusat biaya.	Menunjukkan siapa yang terdampak dan siapa yang memiliki kuota, biaya, dan perbaikan.	Lebih baik gunakan ID internal yang stabil daripada nama pelanggan mentah atau email pengguna.
Requested route	Keluarga endpoint, model yang diminta, preferensi penyedia, kebijakan rute, kebijakan fallback, versi alias model, versi katalog/harga.	Merekonstruksi apa yang diminta klien dan apa yang diizinkan router untuk dilakukan saat itu.	Simpan prompt di luar objek rute kecuali mode debug yang disetujui secara terpisah sedang aktif.
Selected route	Penyedia akhir, model akhir, akun atau channel upstream, region jika relevan, alasan keputusan rute, ID aturan kebijakan.	Membuktikan apakah model utama menyajikan respons atau jalur fallback mengubah perilaku atau biaya.	ID akun harus berupa referensi internal, bukan secret penyedia atau kredensial lengkap.
Retry and fallback chain	Indeks percobaan, jumlah retry, penyedia/model sebelumnya, kelas kegagalan, kode status, target fallback, hasil akhir.	Mencegah retry buta dan menunjukkan apakah tangga failover berperilaku sesuai rancangan.	Simpan kelas error dan cuplikan yang aman. Hindari menyimpan seluruh body error penyedia jika dapat mengulang konten prompt.
Latency and streaming	Waktu mulai permintaan, durasi gateway, durasi penyedia, waktu ke token/chunk pertama, streaming dimulai, streaming selesai, alasan abort, putusnya koneksi klien.	Membedakan latensi penyedia, waktu routing gateway, hambatan streaming, dan pembatalan di sisi klien.	Chunk streaming adalah konten. Catat metadata waktu secara default dan konten hanya di bawah mode debug yang diatur.
Usage and cost	Token input, token output, token cache, token reasoning, unit image/video jika relevan, jumlah permintaan, item baris, biaya estimasi atau final.	Menjelaskan dampak anggaran saat fallback mengalihkan traffic ke penyedia, model, atau tingkat layanan lain.	Agregasikan berdasarkan key, alur kerja, dan tim untuk dashboard normal; batasi tampilan per pengguna.
Response shape	Alasan selesai, ID/nama tool call, jenis output, status respons, detail pemotongan atau tidak lengkap, tingkat layanan.	Menunjukkan apakah model berhenti secara normal, memanggil tool, mencapai batas, atau mengembalikan respons yang tidak lengkap.	Argumen tool dan hasil tool dapat berisi data sensitif. Simpan ID dan nama secara default.
Errors and rate limits	Status HTTP, kode error penyedia, kelas timeout, retry-after, header request remaining/limit/reset, header token remaining/limit/reset.	Membedakan permintaan yang buruk, kegagalan autentikasi, insiden penyedia, habisnya kuota, dan badai rate-limit.	Normalisasi error penyedia ke kelas yang aman sebelum memasukkannya ke alat analitik yang luas.
Governance and retention	Tindakan DLP, ID kebijakan, mode logging konten, flag redaction, hash payload, kelas retensi, kelayakan penghapusan.	Memungkinkan keamanan dan kepatuhan memverifikasi mengapa konten disimpan, di-redact, diblokir, atau dikecualikan.	Secara default gunakan log hanya metadata ketika konten mentah tidak diperlukan untuk alur dukungan atau audit yang ditetapkan.

Capture IDs Before You Debug The Provider

Tugas pertama dari observabilitas AI API adalah korelasi. Referensi API OpenAI merekomendasikan pencatatan ID permintaan di produksi dan mendokumentasikan baik nilai x-request-id yang dihasilkan penyedia maupun nilai X-Client-Request-Id yang disediakan pemanggil. Yang terakhir penting ketika timeout atau kegagalan jaringan mencegah klien Anda menerima header respons penyedia.

Untuk gateway, tambahkan satu lapisan lagi: ID permintaan gateway yang bertahan melewati retry dan fallback internal. Jika satu permintaan pengguna mencoba penyedia A, lalu penyedia B, dan akhirnya model cadangan, ID gateway harus mengikat semua percobaan tersebut. ID permintaan penyedia harus tetap spesifik per percobaan. ID trace harus mengikat panggilan AI ini ke sisa permintaan aplikasi.

W3C Trace Context mendefinisikan traceparent dan tracestate untuk menyebarkan konteks trace terdistribusi lintas layanan. Gunakan header tersebut untuk korelasi trace, bukan identitas pelanggan. Bagian privasi W3C tegas: field tracing tidak boleh membawa informasi pribadi yang dapat diidentifikasi atau informasi sensitif lainnya.

Log Requested Route And Selected Route Separately

Kesalahan umum dalam pemantauan AI gateway adalah hanya mencatat penyedia dan model akhir. Itu menghilangkan bukti routing yang paling penting: apa yang diminta klien dan apa yang diizinkan oleh kebijakan sebelum gateway mengambil keputusan.

Jaga dua objek ini tetap terpisah:

Rute yang diminta: keluarga endpoint, model atau alias yang diminta, kebijakan rute, preferensi penyedia, kebijakan fallback, versi katalog, versi harga, dan mode permintaan seperti streaming atau batch.
Rute yang dipilih: penyedia akhir, model akhir, akun atau kanal upstream, wilayah bila relevan, alasan keputusan rute, dan ID aturan kebijakan.

Pemisahan ini penting ketika respons fallback valid tetapi mengejutkan. Jika rute yang diminta adalah chat/completions dengan streaming diaktifkan, dan rute yang dipilih beralih ke model lain setelah timeout, tinjauan insiden dapat melihat jalur yang dimaksud sekaligus jalur yang sebenarnya. Ini juga membantu tim keuangan memahami mengapa penggunaan muncul di bawah model atau item baris yang berbeda.

Pembeli Flatkey harus menerapkan pola evaluasi yang sama. Mulailah dengan daftar periksa persyaratan gateway AI API, lalu gunakan playbook load balancing dan failover untuk menentukan perubahan rute mana yang diizinkan sebelum Anda meninjau log.

Catat Rangkaian Retry Dan Fallback

Retry adalah saat log yang tidak lengkap menjadi mahal. Jika satu-satunya field yang disimpan adalah status akhir dan model akhir, tim tidak dapat mengetahui apakah permintaan berhasil pada percobaan pertama, setelah satu retry, atau setelah lima retry lintas penyedia. Observabilitas AI API tingkat insiden memperlakukan retry dan fallback sebagai sebuah rantai.

Setiap percobaan harus mencakup:

Indeks percobaan dan ID permintaan gateway induk.
Penyedia, model, akun upstream, dan keluarga endpoint untuk percobaan tersebut.
Waktu mulai, durasi, kelas timeout, dan status streaming.
Kode status, kelas error penyedia, ID permintaan penyedia, dan metadata rate-limit.
Target fallback dan alasan keputusan saat percobaan tidak mengakhiri rantai.

Rantai ini mencegah gateway menyembunyikan mode kegagalan yang nyata. Permintaan yang salah format harus gagal tertutup, bukan berputar melalui penyedia. Error 500 dari penyedia mungkin membenarkan satu retry. Batas kuota mungkin beralih ke akun upstream yang disetujui. Ketidakcocokan model yang menghadap pelanggan mungkin memerlukan error terkontrol alih-alih fallback diam-diam.

Ukur Latensi Untuk Stream, Bukan Hanya Panggilan Yang Selesai

Respons streaming membutuhkan lebih dari sekadar durasi total. Dokumentasi observabilitas AI Gateway dari Vercel menyoroti waktu ke token pertama, durasi permintaan, jumlah token, dan pengeluaran sebagai metrik gateway. Konvensi semantik GenAI OpenTelemetry menyertakan gen_ai.response.time_to_first_chunk dan gen_ai.request.stream. Field tersebut berguna karena banyak insiden routing adalah insiden streaming: penyedia menerima permintaan, chunk pertama terlambat, stream macet, atau klien terputus.

Setidaknya, catat waktu mulai permintaan, durasi gateway, durasi penyedia, waktu ke token atau chunk pertama, flag stream dimulai, flag stream selesai, alasan abort, dan status putusnya klien. Untuk respons non-streaming, field yang sama dapat tetap null atau false. Ini menjaga satu skema untuk Chat Completions, Responses, dan keluarga endpoint khusus penyedia.

Jangan simpan chunk stream secara default. Chunk stream adalah konten respons, dan konten respons dapat mencakup data pengguna, konteks yang diambil, hasil alat, atau informasi yang diatur. Untuk observabilitas AI API normal, metadata waktu biasanya sudah cukup untuk mendiagnosis hambatan.

Hubungkan Penggunaan Dan Biaya Ke Keputusan Rute

Penggunaan dan biaya adalah field insiden, bukan hanya field keuangan. Contoh API Responses OpenAI mencakup penggunaan token input, output, cached, reasoning, dan total. Endpoint penggunaan organisasi OpenAI mendukung pengelompokan berdasarkan project, user, API key, model, batch, dan service tier; endpoint biaya mendukung pengelompokan project, line item, dan API key. Dokumentasi AI Gateway Vercel juga menjelaskan ringkasan permintaan berdasarkan project dan API key, jumlah token, durasi P75, TTFT P75, dan biaya.

Untuk observabilitas AI API, tangkap penggunaan dan biaya di level percobaan bila memungkinkan dan selalu di level permintaan akhir. Fallback mungkin benar secara operasional tetapi mengejutkan secara finansial. Tanpa model, rute, penggunaan, dan biaya dalam event yang sama, tim keuangan mungkin melihat lonjakan pengeluaran sebelum engineering dapat menjelaskannya.

Copy publik harga dan homepage Flatkey mengarah pada harga yang jelas, penagihan terpadu, analitik penggunaan, dan dasbor untuk kunci, penggunaan, dan routing. Cuplikan harga bertanggal 18 Juni 2026 yang disimpan untuk tugas ini menghasilkan 638 baris model, 23 vendor, dan keluarga endpoint termasuk OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent, image generation, dan OpenAI video. Perlakukan hitungan tersebut sebagai bukti bertanggal, lalu verifikasi halaman harga langsung dan catatan dasbor untuk model spesifik dalam alur kerja Anda.

Gunakan Logging Hanya Metadata Sebagai Default

Prompt dan respons mentah adalah alat debug yang kuat, tetapi juga log yang berisiko. Dokumentasi logging AI Gateway Cloudflare adalah pola referensi yang berguna: mereka menjelaskan log permintaan dengan prompt, respons, penyedia, timestamp, status, penggunaan token, biaya, durasi, dan user agent, dan mereka juga mendokumentasikan header yang dapat menekan penyimpanan body permintaan dan respons mentah sambil tetap mempertahankan metadata seperti jumlah token, model, penyedia, kode status, biaya, dan durasi.

Itulah sikap default yang tepat untuk log API LLM: kumpulkan metadata secara default, lalu minta mode debug eksplisit atau alur kerja dukungan sebelum konten mentah disimpan. Konvensi semantik GenAI OpenTelemetry menandai pesan input, pesan output, instruksi sistem, argumen pemanggilan alat, dan hasil pemanggilan alat sebagai field yang dapat berisi informasi sensitif. Kebijakan logging Anda harus mencerminkan hal itu.

Kebijakan praktis memiliki empat mode:

Tidak ada log: digunakan untuk permintaan yang tidak boleh disimpan melampaui pemrosesan sementara.
Hanya metadata: rute, ID, latensi, status, penggunaan, biaya, dan flag redaksi.
Payload yang sudah diredaaksi: bidang request/response terpilih setelah penghapusan PII dan rahasia.
Payload mentah: tangkapan debug jangka pendek dengan kontrol akses untuk insiden tertentu atau kasus dukungan yang disetujui pelanggan.

Contoh Event Log Routing

Template ini sengaja mengutamakan metadata. Sesuaikan nama-namanya dengan sistem logging Anda, tetapi pertahankan pemisahan antara rute yang diminta, rute yang dipilih, percobaan, penggunaan, biaya, dan kontrol privasi.

{
  "gateway_request_id": "gw_01jz_route_abc",
  "app_request_id": "req_9a7c",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "client_request_id": "7c2c1b3a-4b55-4e36-bd47-8d1c2e2f2e11",
  "owner": {
    "project": "checkout-ai",
    "environment": "production",
    "api_key_id": "key_hash_6f12",
    "team": "platform",
    "workflow": "customer-chat"
  },
  "requested_route": {
    "endpoint_family": "chat_completions",
    "model": "primary-chat-model",
    "stream": true,
    "route_policy_id": "chat-prod-v8",
    "fallback_policy_id": "chat-prod-safe-fallback-v3",
    "catalog_version": "2026-06-18"
  },
  "selected_route": {
    "provider": "provider_b",
    "model": "backup-chat-model",
    "upstream_account": "acct_pool_2",
    "decision_reason": "primary_timeout",
    "policy_rule_id": "fallback_on_timeout_once"
  },
  "attempts": [
    {
      "index": 1,
      "provider": "provider_a",
      "model": "primary-chat-model",
      "provider_request_id": "req_provider_a_123",
      "status_code": 504,
      "error_class": "timeout",
      "duration_ms": 12000,
      "fallback_target": "provider_b"
    },
    {
      "index": 2,
      "provider": "provider_b",
      "model": "backup-chat-model",
      "provider_request_id": "req_provider_b_456",
      "status_code": 200,
      "duration_ms": 2400,
      "time_to_first_chunk_ms": 620,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 1284,
    "output_tokens": 312,
    "cached_input_tokens": 0,
    "reasoning_output_tokens": 0
  },
  "cost": {
    "currency": "usd",
    "estimated_amount": 0.0048,
    "line_item": "backup-chat-model"
  },
  "privacy": {
    "content_logging_mode": "metadata_only",
    "payload_redacted": true,
    "retention_class": "30_day_incident_metadata"
  }
}

Nama-nama field ini hanyalah contoh, bukan kontrak API Flatkey. Gunakan ini untuk menguji apakah gateway, data warehouse, dan alat insiden Anda dapat menjawab pertanyaan rute tanpa memerlukan konten mentah.

Alur Triage 10 Menit

Ketika insiden routing model dimulai, alur observabilitas AI API harus cukup singkat agar engineer on-call dapat menjalankannya di bawah tekanan:

Temukan permintaan yang berkorelasi: cari berdasarkan ID permintaan aplikasi, ID permintaan gateway, ID error yang terlihat oleh pengguna, ID permintaan provider, atau ID trace.
Bandingkan rute yang diminta dan yang dipilih: konfirmasi model yang diminta, kebijakan rute, aturan fallback, provider akhir, dan model akhir.
Baca rantai percobaan: identifikasi kegagalan pertama, jumlah retry, target fallback, dan hasil akhir.
Periksa konteks rate limit dan kuota: inspeksi header sisa, batas, dan reset saat provider mengembalikan 429 atau terjadi tekanan token.
Pisahkan latensi dari streaming: bandingkan durasi gateway, durasi provider, waktu ke chunk pertama, akhir stream, dan disconnect klien.
Rekonsiliasi penggunaan dan biaya: tinjau jumlah token, service tier, item baris biaya, serta kepemilikan tim/kunci.
Tinjau mode privasi: konfirmasi apakah log berupa hanya metadata, sudah diredaaksi, mentah, atau sengaja tidak disertakan.
Tentukan tindakan rute: rollback kebijakan, nonaktifkan rute, turunkan bobot traffic, naikkan kuota, antrekan pekerjaan latar belakang, atau fail closed.

Setelah insiden, ubah langkah yang sama menjadi tampilan dashboard. Review tercepat terjadi saat engineering, support, dan finance dapat memeriksa bentuk event yang sama.

Bagaimana Flatkey Cocok untuk Observabilitas AI API

Flatkey diposisikan untuk tim yang menginginkan satu API key, satu endpoint router yang kompatibel, harga yang jelas, penagihan terpadu, dan satu dashboard untuk key, penggunaan, dan routing. Untuk artikel ini, jalur pembuktian yang relevan bersifat praktis: arahkan klien staging ke https://router.flatkey.ai/v1, kirim permintaan melalui key non-production, picu kegagalan terkontrol jika memungkinkan, dan konfirmasi catatan penggunaan, routing, error, dan biaya mana yang muncul di dashboard.

Gunakan pelacakan penggunaan AI per key untuk memisahkan traffic staging, production, pelanggan, dan workflow. Gunakan manajemen kuota AI API untuk mencegah fallback menghabiskan budget bersama. Gunakan atribusi biaya AI API berdasarkan tim saat perubahan routing membutuhkan penanggung jawab dari finance.

CTA-nya sederhana: jika tim Anda ingin menguji observabilitas AI API di balik satu key, dapatkan key, jalankan rute staging melalui Flatkey, dan tinjau apakah log menjawab pertanyaan insiden di atas sebelum Anda mengandalkan switching otomatis di produksi.

FAQ

Apa itu observabilitas AI API?

Observabilitas AI API adalah kemampuan untuk memeriksa traffic API model di seluruh ID request, trace, model, provider, keputusan rute, retry, fallback, penggunaan, biaya, latensi, error, dan kontrol privasi. Untuk insiden routing, ini harus menjelaskan baik apa yang diminta klien maupun apa yang sebenarnya dipilih gateway.

Apa yang seharusnya dicatat oleh log API LLM?

Log API LLM harus menangkap correlation ID, metadata pemilik, route yang diminta, route yang dipilih, rantai retry, latensi, status streaming, penggunaan token, biaya, alasan selesai, kelas error, konteks rate-limit, dan mode logging konten. Prompt dan output mentah sebaiknya bersifat opsional, diatur aksesnya, dan disanitasi jika memungkinkan.

Mengapa mencatat model yang diminta dan model respons secara terpisah?

Model yang diminta menunjukkan niat klien. Model respons menunjukkan apa yang benar-benar melayani permintaan. Dalam insiden fallback, keduanya bisa berbeda. Mencatat keduanya sangat penting untuk tinjauan kualitas, rekonsiliasi biaya, dan komunikasi dukungan.

Bagaimana request ID membantu dukungan provider?

Request ID dari provider mengidentifikasi panggilan API upstream. Request ID yang dikirim oleh pemanggil dapat membantu ketika timeout mencegah header respons পৌঁถึง klien Anda. Simpan kedua ID dalam catatan insiden, bersama dengan gateway request ID dan trace ID.

Apakah monitoring AI gateway harus menyimpan prompt mentah?

Tidak secara default. Monitoring AI gateway biasanya membutuhkan metadata terlebih dahulu: route, model, status, durasi, penggunaan, biaya, dan mode privasi. Simpan prompt atau respons mentah hanya dalam alur kerja debug, support, atau audit yang ditentukan, dengan retensi dan kontrol akses.

Sumber yang Digunakan

Pemeriksaan Akhir Sebelum Anda Mengubah Routing

Sebelum Anda mempercayai fallback otomatis, jadikan observabilitas AI API sebagai bagian dari release gate. Pastikan kebijakan route, ladder retry, field token dan biaya, header rate-limit, timestamp streaming, provider request ID, mode privasi, dan kelas retensi. Lalu jalankan insiden staging yang terkontrol dan verifikasi bahwa log dapat menjelaskan hasilnya tanpa akses prompt mentah.

Flatkey mengurangi permukaan integrasi menjadi satu key dan satu base URL yang kompatibel. Untuk mengevaluasi lapisan keandalan itu dengan traffic Anda sendiri, dapatkan key, jalankan workflow staging, dan periksa routing, penggunaan, biaya, serta catatan error yang akan dibutuhkan tim Anda saat insiden nyata.