Permintaan, respons, dan kode error API Telemetri

API Telemetri berupa JSON melalui HTTP di https://api.logbrew.co. SDK publik mengirim batch yang dikelolanya ke POST /v1/events. Klien native kustom mengirim envelope native ke POST /api/telemetry/ingest. Kedua rute ingest memerlukan bearer ingest khusus proyek. Pembacaan dan perubahan milik akun memakai bearer akun. Jangan pernah memakai bearer akun atau sesi browser sebagai konfigurasi SDK atau ingest. Jangan pernah mengirim bearer ingest ke rute baca.

Kirim permintaan dengan lingkup terbatas

Gunakan daftar periksa ini sebelum klien mengirim permintaan:

Pilih rute dan metode HTTP dari tabel endpoint.
Gunakan bearer yang benar: bearer ingest untuk ingest, bearer akun untuk semua hal lain.
Pilih lingkup proyek yang didukung rute. Jangan perluas lingkup setelah respons kosong.
Tambahkan hanya kunci kueri yang diterima rute. Lihat Filter kueri.
Kirim Content-Type: application/json jika rute punya body JSON.
Baca status HTTP dan body respons sebelum Anda mencoba lagi.
Jauhkan bearer, tiket feed, dan body respons lengkap dari log dan prompt agen.

Endpoint

Ingest

Metode	Path	Tujuan
`POST`	`/v1/events`	Ingest batch yang dibuat dan dikirim SDK LogBrew publik.
`POST`	`/api/telemetry/ingest`	Ingest envelope telemetri native dari klien kustom.

Biarkan SDK membuat batch /v1/events. Jangan menyusunnya secara manual. Untuk envelope native, lihat Integrasi SDK.

Pembacaan telemetri

Metode	Path	Tujuan
`GET`	`/api/logs`	Tampilkan daftar log terstruktur.
`GET`	`/api/logs/{log_id}`	Baca satu log.
`GET`	`/api/logs/attributes`	Tampilkan daftar path dan tipe atribut log yang bisa dicari filter.
`GET`	`/api/telemetry/issues`	Tampilkan daftar masalah terkelompok.
`GET`	`/api/telemetry/issues/{issue_id}`	Baca satu masalah terkelompok.
`GET`	`/api/telemetry/issues/{issue_id}/events`	Tampilkan daftar kemunculan dari satu masalah terkelompok.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Perbarui status, prioritas, atau penanggung jawab satu masalah.
`POST`	`/api/telemetry/issues/bulk`	Perbarui status, prioritas, atau penanggung jawab 1 sampai 100 masalah dalam satu proyek.
`GET`	`/api/telemetry/issues/assignees`	Tampilkan daftar akun dan tim yang bisa ditugaskan masalah di satu proyek.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	Tampilkan daftar usulan pemilik satu masalah.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	Baca atau tetapkan aturan kepemilikan dan teks CODEOWNERS satu proyek.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	Baca riwayat perubahan satu masalah.
`GET`	`/api/telemetry/issues/notifications`	Tampilkan daftar masalah yang ditugaskan orang lain kepada Anda atau tim Anda.
`POST`	`/api/telemetry/issues/notifications/read`	Tandai notifikasi masalah Anda sebagai sudah dibaca.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	Tetapkan aturan tingkat keparahan untuk masalah.
`PUT`	`/api/logs/{log_id}/triage-rule`	Tetapkan aturan tingkat keparahan dan status diabaikan untuk semua log yang cocok dengan log tersebut.
`GET`	`/api/telemetry/traces`	Temukan trace dalam lingkup proyek.
`GET`	`/api/telemetry/traces/{trace_id}`	Tampilkan daftar span untuk satu trace.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	Baca ringkasan terbatas dari satu trace.
`GET`	`/api/telemetry/actions`	Tampilkan daftar aksi produk.
`GET`	`/api/telemetry/metrics`	Tampilkan daftar sampel metrik.
`GET`	`/api/telemetry/metrics/series`	Baca satu metrik per interval waktu.
`GET`	`/api/telemetry/releases`	Tampilkan daftar ringkasan rilis.
`GET`	`/api/telemetry/summary/volume`	Baca jumlah sinyal untuk satu proyek per interval waktu.

Deployment

Metode	Path	Perintah CLI
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	Tidak ada
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	Tidak ada

Catat deployment dari otomatisasi rilis setelah deployment berhasil atau gagal. Body PUT berisi project_id, release, environment, service_name, status (succeeded atau failed), started_at, finished_at, dan commit_sha yang opsional. Gunakan nilai release, environment, dan service_name yang sama dengan yang dikirim SDK Anda. Akun harus memiliki proyek tersebut. deployment_id adalah ID Anda sendiri untuk deployment. Percobaan ulang dengan ID dan body yang sama mengembalikan deployment yang tersimpan. ID yang sama dengan body berbeda gagal dengan 409 dan idempotency_conflict. Gunakan ID baru untuk deployment yang berbeda.

Investigasi

Setiap rute investigasi mengembalikan paket bukti terbatas untuk satu subjek. Perintah logbrew explain di CLI membaca rute ini dan memvalidasi responsnya.

Metode	Path	Perintah CLI
`GET`	`/api/logs/{log_id}/investigation`	`logbrew explain log`
`GET`	`/api/telemetry/issues/{issue_id}/investigation`	`logbrew explain issue`
`GET`	`/api/telemetry/issues/{issue_id}/correction-verification`	`logbrew investigate issue <issue_id> verify`
`GET`	`/api/telemetry/traces/{trace_id}/investigation`	`logbrew explain trace`
`GET`	`/api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`logbrew explain span`
`GET`	`/api/telemetry/actions/{action_id}/investigation`	`logbrew explain action`
`GET`	`/api/telemetry/metrics/investigation`	`logbrew explain metric`
`GET`	`/api/telemetry/releases/investigation`	`logbrew explain release`

Analitik produk

Metode	Path	Perintah CLI
`GET`	`/api/telemetry/analytics/overview`	`logbrew analytics overview`
`GET`	`/api/telemetry/analytics/properties`	`logbrew analytics properties`
`POST`	`/api/telemetry/analytics/funnel`	`logbrew analytics funnel`
`POST`	`/api/telemetry/analytics/retention`	`logbrew analytics retention`
`POST`	`/api/telemetry/analytics/lifecycle`	`logbrew analytics lifecycle`
`POST`	`/api/telemetry/analytics/paths`	`logbrew analytics paths`
`POST`	`/api/telemetry/analytics/segments/compare`	`logbrew analytics compare`

Rute analitik POST menerima body JSON, bukan kunci kueri. Lihat Analitik produk.

Feed langsung

Metode	Path	Tujuan
`POST`	`/api/feed/ticket`	Buat tiket feed langsung berumur pendek dengan bearer akun.
`GET`	`/api/feed/live?ticket=<ticket>`	Buka koneksi WebSocket dengan tiket itu.

Akun dan masuk

Rute penggunaan, kuota, langganan, dan logout ada di API akun.

Kode status sukses

Operasi	Status sukses
Ingest, pembacaan, pembaruan masalah, aturan, deployment, analitik, dan tiket feed	`200 OK`
Koneksi feed langsung	`101 Switching Protocols`, lalu pesan WebSocket

Respons 200 tidak membuktikan bahwa bukti sudah lengkap. Baca kolom cakupan, pemotongan, dan status di respons.

Filter kueri dan paginasi

Setiap rute baca menerima kunci kuerinya sendiri. Alias praktis seperti project, trace, dan user bukan kunci kueri. Secara default, rute daftar mengembalikan array polos, dan mengembalikan envelope kursor dengan pagination=cursor. Daftar deployment selalu mengembalikan objek halaman. Lihat Filter kueri.

Respons dan error

Format respons menampilkan satu contoh untuk setiap kelompok respons.
Error API mencantumkan kode error dan tindakan pemulihan.

Baca code sebelum pesan untuk manusia. Gunakan next_action untuk perilaku program dan next untuk panduan bagi manusia. Jangan mem-parse kata-kata di error atau next.

Perbarui masalah

Permintaan ini memakai bearer akun. Bearer ini sengaja dibedakan dari LOGBREW_INGEST_BEARER. Akun harus punya izin untuk mengelola masalah di proyek tempat masalah itu berada. Jika tidak, permintaan gagal dengan 403 dan forbidden. Izin yang sama mencakup perubahan status, prioritas, dan penanggung jawab, serta aturan masalah dan log. Setiap permintaan mengisi 1 atau lebih kolom berikut:

Kolom	Nilai
`status`	`unresolved`, `resolved`, atau `archived`. `ignored` adalah nama lama untuk `archived`.
`priority`	`high`, `medium`, atau `low`.
`assignee`	ID pengguna, `me` untuk akun yang sedang masuk, `team:<team_id>` untuk tim, atau `none` untuk menghapus penanggung jawab.

Permintaan tanpa satu pun kolom ini gagal dengan 422 dan validation_failed. Masalah punya 0 atau 1 penanggung jawab: satu akun atau satu tim. Akun harus bisa membaca proyek, dan tim harus berada di organisasi proyek. Jika tidak, permintaan gagal dengan 422 dan validation_failed, dan LogBrew tidak mengubah apa pun. Ambil daftar akun yang bisa Anda tugaskan dari Tampilkan daftar penanggung jawab. Nilai assignee lain juga gagal dengan 422 dan validation_failed. Prioritas yang Anda tetapkan akan tetap seperti itu. Tanpa prioritas yang Anda tetapkan, prioritas mengikuti tingkat keparahan masalah: error dan critical menjadi high, warning menjadi medium, dan info menjadi low. Kolom yang sudah berisi nilai yang diminta tidak berubah. Anda bisa mengirim permintaan yang sama lagi setelah timeout. Timeout tidak membuktikan bahwa perubahan tidak terjadi. Baca masalah lagi sebelum Anda mengirim perubahan yang berbeda.

Perbarui satu masalah

Tambahkan response_version=4 agar respons berisi archived, prioritas, dan penanggung jawab. Di versi 4, assignee bernilai { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" }, atau null. Versi 3 menampilkan penanggung jawab berupa tim sebagai null.

curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID?response_version=4" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "archived", "priority": "low", "assignee": "me" }'

Responsnya berupa masalah yang sudah diperbarui. Lihat contoh respons status masalah.

Perbarui masalah secara massal

Kirim project_id dan 1 sampai 100 ID masalah yang berbeda dari proyek itu:

curl -X POST "$LOGBREW_API_URL/api/telemetry/issues/bulk" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{
    "project_id": "<project-uuid>",
    "issue_ids": ["<issue-uuid-1>", "<issue-uuid-2>"],
    "assignee": "<user-uuid>"
  }'

Permintaan ini menerapkan perubahan yang sama ke setiap masalah. Respons berisi project_id dan results, dengan 1 hasil untuk setiap ID masalah, sesuai urutan di permintaan. Setiap hasil berisi issue_id, outcome, dan issue. issue adalah masalah terkini dalam versi respons 3, atau null untuk not_found. Tambahkan "response_version": 2 ke body agar setiap masalah dikembalikan dalam versi respons 4.

`outcome`	Arti
`updated`	LogBrew menerapkan perubahan.
`unchanged`	Masalah sudah berisi nilai yang diminta.
`not_found`	Proyek tidak punya masalah dengan ID ini. LogBrew tidak mengubah apa pun untuk ID itu.

Daftar kosong, lebih dari 100 ID, atau ID yang berulang gagal dengan 422 dan validation_failed. Pecah kumpulan yang lebih besar menjadi beberapa permintaan. Jika akun tidak bisa membaca proyek, permintaan gagal dengan 404 dan not_found.

Tampilkan daftar penanggung jawab

Kirim ID proyek untuk mendapatkan setiap akun yang bisa ditugaskan masalah di proyek itu:

curl "$LOGBREW_API_URL/api/telemetry/issues/assignees?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

Daftar ini berisi setiap akun yang bisa membaca proyek. Setiap entri berisi user_id, name, dan email. name bernilai null jika akun tidak punya nama. Tambahkan response_version=2 untuk juga mendapatkan teams: setiap tim di organisasi proyek, dengan team_id, slug, dan name. Lihat respons daftar penanggung jawab. Setiap akun yang bisa membaca proyek bisa mengambil daftar ini. Jika akun tidak bisa membaca proyek, permintaan gagal dengan 404 dan not_found. Saat anggota kehilangan akses ke proyek, masalah yang ditugaskan ke anggota itu tidak menampilkan penanggung jawab. Jika anggota itu mendapatkan akses lagi, masalah itu kembali menampilkan anggota tersebut, kecuali seseorang sudah mengubah atau menghapus penanggung jawabnya sementara itu.

Kepemilikan dan usulan pemilik

GET /api/telemetry/issues/ownership?project_id=<project-uuid> mengembalikan rules, codeowners, updated_at, dan unresolved_owners. Setiap akun yang bisa membaca proyek bisa membacanya. PUT dengan project_id serta rules, codeowners, atau keduanya mengganti teks tersebut dan butuh izin untuk mengelola masalah. Kolom yang tidak Anda kirim tetap menyimpan teksnya, dan string kosong menghapusnya. Setiap teks berukuran maksimal 128 KiB. Teks yang tidak valid gagal dengan 422 dan menyebutkan barisnya. GET /api/telemetry/issues/{issue_id}/owners?response_version=2 mengembalikan suggested_assignee, owners, dan inputs. Setiap pemilik punya type (user atau team), source (ownership_rule, codeowners, atau recent_activity), rule, line, dan matched. Versi 1, yaitu default, hanya menampilkan akun.

Riwayat masalah

GET /api/telemetry/issues/{issue_id}/activity?response_version=2 mengembalikan activity, mulai dari yang terbaru, dan next_cursor. Setiap entri punya type (status, priority, assigned, unassigned, severity_rule, atau first_seen), value, actor_id, actor, assignee_id, assignee, team, dan at. limit bernilai 1 sampai 200, dengan default 50. Kirim cursor_time dan cursor_id dari next_cursor untuk halaman berikutnya.

Notifikasi

GET /api/telemetry/issues/notifications mengembalikan notifications, unread, read_at, dan next_cursor. Setiap notifikasi adalah penugasan masalah kepada Anda atau tim Anda oleh akun lain. POST /api/telemetry/issues/notifications/read dengan objek JSON kosong, atau dengan read_at, memindahkan penanda baca Anda. Penanda ini tidak pernah mundur.

Tetapkan aturan masalah dan log

Aturan mengubah cara LogBrew menampilkan sinyal yang cocok. Aturan tidak menghapus data. severity yang terekam tetap sama, dan respons menampilkan aturan di triage.

Permintaan	Body JSON
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity berisi info, warning, error, critical, atau source. source menghapus tingkat keparahan pengganti dan kembali menampilkan tingkat keparahan yang terekam. Untuk aturan log, ignored: true menyembunyikan log yang cocok dari daftar log default. Baca log itu dengan status=ignored atau status=all. Aturan berlaku untuk sinyal cocok yang tersimpan dan yang akan datang. Nilai lain gagal dengan 422 dan validation_failed.

Jangan kirim rilis kosong. LogBrew menolaknya agar pelacakan rilis tetap tepercaya.

​Kirim permintaan dengan lingkup terbatas

​Endpoint

​Ingest

​Pembacaan telemetri

​Deployment

​Investigasi

​Analitik produk

​Feed langsung

​Akun dan masuk

​Kode status sukses

​Filter kueri dan paginasi

​Respons dan error

​Perbarui masalah

​Perbarui satu masalah

​Perbarui masalah secara massal

​Tampilkan daftar penanggung jawab

​Kepemilikan dan usulan pemilik

​Riwayat masalah

​Notifikasi

​Tetapkan aturan masalah dan log

Kirim permintaan dengan lingkup terbatas

Endpoint

Ingest

Pembacaan telemetri

Deployment

Investigasi

Analitik produk

Feed langsung

Akun dan masuk

Kode status sukses

Filter kueri dan paginasi

Respons dan error

Perbarui masalah

Perbarui satu masalah

Perbarui masalah secara massal

Tampilkan daftar penanggung jawab

Kepemilikan dan usulan pemilik

Riwayat masalah

Notifikasi

Tetapkan aturan masalah dan log