Telemetri API'si istekleri, yanıtları ve hata kodları

Telemetri API’si, https://api.logbrew.co adresinde HTTP üzerinden JSON kullanır. Herkese açık SDK’lar yönettikleri toplu gönderimleri POST /v1/events adresine gönderir. Özel native istemciler native zarfları POST /api/telemetry/ingest adresine gönderir. İki alım rotası da proje kapsamlı bir alım bearer tokenı gerektirir. Okumalar ve hesaba ait değişiklikler hesap bearer tokenı kullanır. Hesap bearer tokenını veya tarayıcı oturumunu asla SDK ya da alım yapılandırması olarak kullanmayın. Alım bearer tokenını asla bir okuma rotasına göndermeyin.

Sınırlı bir istek gönderin

Bir istemci istek göndermeden önce bu kontrol listesini kullanın:

Uç nokta tablosundan rotayı ve HTTP yöntemini seçin.
Doğru bearer tokenını kullanın: Veri alımı için alım bearer tokenı, diğer her şey için hesap bearer tokenı.
Rotanın desteklediği proje kapsamını seçin. Boş bir yanıttan sonra kapsamı genişletmeyin.
Yalnızca rotanın kabul ettiği sorgu anahtarlarını ekleyin. Sorgu filtreleri sayfasına bakın.
Rotanın JSON gövdesi varsa Content-Type: application/json gönderin.
Yeniden denemeden önce HTTP durumunu ve yanıt gövdesini okuyun.
Bearer tokenlarını, akış biletlerini ve yanıt gövdelerinin tamamını logların ve agent promptlarının dışında tutun.

Uç noktalar

Veri alımı

Yöntem	Yol	Amaç
`POST`	`/v1/events`	Herkese açık LogBrew SDK’larının oluşturup gönderdiği toplu gönderimleri alır.
`POST`	`/api/telemetry/ingest`	Özel bir istemciden native telemetri zarflarını alır.

/v1/events toplu gönderimlerini SDK’nın oluşturmasına izin verin. Bunları elle oluşturmayın. Native zarf için SDK entegrasyonu sayfasına bakın.

Telemetri okumaları

Yöntem	Yol	Amaç
`GET`	`/api/logs`	Yapılandırılmış logları listeler.
`GET`	`/api/logs/{log_id}`	Tek bir logu okur.
`GET`	`/api/logs/attributes`	Bir filtrenin arayabileceği log özniteliği yollarını ve türlerini listeler.
`GET`	`/api/telemetry/issues`	Gruplanmış sorunları listeler.
`GET`	`/api/telemetry/issues/{issue_id}`	Gruplanmış tek bir sorunu okur.
`GET`	`/api/telemetry/issues/{issue_id}/events`	Gruplanmış tek bir sorunun oluşumlarını listeler.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Tek bir sorunun durumunu, önceliğini veya sorumlusunu günceller.
`POST`	`/api/telemetry/issues/bulk`	Bir projedeki 1 ile 100 arası sorunun durumunu, önceliğini veya sorumlusunu günceller.
`GET`	`/api/telemetry/issues/assignees`	Bir projede sorun atanabilecek hesapları ve ekipleri listeler.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	Tek bir sorunun önerilen sahiplerini listeler.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	Bir projenin sahiplik kurallarını ve CODEOWNERS metnini okur veya ayarlar.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	Tek bir sorunun değişiklik geçmişini okur.
`GET`	`/api/telemetry/issues/notifications`	Başkalarının size veya ekiplerinize atadığı sorunları listeler.
`POST`	`/api/telemetry/issues/notifications/read`	Sorun bildirimlerinizi okundu olarak işaretler.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	Bir sorun için önem düzeyi kuralını ayarlar.
`PUT`	`/api/logs/{log_id}/triage-rule`	Bir logla eşleşen loglar için önem düzeyi kuralını ve yok sayılma durumunu ayarlar.
`GET`	`/api/telemetry/traces`	Bir proje kapsamındaki izleri bulur.
`GET`	`/api/telemetry/traces/{trace_id}`	Tek bir izin span’lerini listeler.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	Tek bir izin sınırlı özetini okur.
`GET`	`/api/telemetry/actions`	Ürün aksiyonlarını listeler.
`GET`	`/api/telemetry/metrics`	Metrik örneklerini listeler.
`GET`	`/api/telemetry/metrics/series`	Tek bir metriği zaman dilimleri olarak okur.
`GET`	`/api/telemetry/releases`	Sürüm özetlerini listeler.
`GET`	`/api/telemetry/summary/volume`	Tek bir projenin sinyal sayılarını zaman dilimleri olarak okur.

Dağıtımlar

Yöntem	Yol	CLI komutu
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	Yok
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	Yok

Dağıtım başarılı veya başarısız olduktan sonra onu sürüm otomasyonundan kaydedin. PUT gövdesi project_id, release, environment, service_name, status (succeeded veya failed), started_at, finished_at ve isteğe bağlı bir commit_sha içerir. SDK’nızın gönderdiği release, environment ve service_name değerlerinin aynısını kullanın. Proje hesaba ait olmalıdır. deployment_id, dağıtım için sizin belirlediğiniz kimliktir. Aynı kimlik ve aynı gövdeyle yapılan yeniden deneme saklanan dağıtımı döndürür. Aynı kimlik farklı bir gövdeyle 409 ve idempotency_conflict ile başarısız olur. Farklı bir dağıtım için yeni bir kimlik kullanın.

İncelemeler

Her inceleme rotası tek bir konu için sınırlı bir kanıt paketi döndürür. CLI logbrew explain komutu bu rotaları okur ve yanıtı doğrular.

Yöntem	Yol	CLI komutu
`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`

Ürün analizleri

Yöntem	Yol	CLI komutu
`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`

POST analiz rotaları sorgu anahtarları değil, bir JSON gövdesi alır. Ürün analizleri sayfasına bakın.

Canlı akış

Yöntem	Yol	Amaç
`POST`	`/api/feed/ticket`	Hesap bearer tokenıyla kısa ömürlü bir canlı akış bileti oluşturur.
`GET`	`/api/feed/live?ticket=<ticket>`	Bu biletle bir WebSocket bağlantısı açar.

Hesap ve giriş

Kullanım, kota, abonelik ve çıkış rotaları Hesap API’si sayfasındadır.

Başarı durum kodları

İşlem	Başarı durumu
Veri alımı, okumalar, sorun güncellemeleri, kurallar, dağıtımlar, analizler ve akış biletleri	`200 OK`
Canlı akış bağlantısı	`101 Switching Protocols`, ardından WebSocket mesajları

200 yanıtı kanıtın eksiksiz olduğunu kanıtlamaz. Yanıttaki kapsama oranı, kısaltma ve durum alanlarını okuyun.

Sorgu filtreleri ve sayfalama

Her okuma rotası kendi sorgu anahtarlarını kabul eder. project, trace ve user gibi kolay takma adlar sorgu anahtarı değildir. Liste rotaları varsayılan olarak yalın bir dizi, pagination=cursor ile ise bir cursor zarfı döndürür. Dağıtım listesi her zaman bir sayfa nesnesi döndürür. Sorgu filtreleri sayfasına bakın.

Yanıtlar ve hatalar

Yanıt biçimleri her yanıt ailesi için bir örnek gösterir.
API hataları hata kodlarını ve kurtarma aksiyonlarını listeler.

İnsanlar için yazılmış mesajdan önce code değerini okuyun. Program davranışı için next_action, insanlara yönlendirme için next değerini kullanın. error veya next metninin ifadesini ayrıştırmayın.

Sorunları güncelleyin

Bu istekler hesap bearer tokenı kullanır. Bu token bilerek LOGBREW_INGEST_BEARER değerinden farklıdır. Hesabın, sorunun projesinde sorunları yönetme izni olmalıdır. İzin yoksa istek 403 ve forbidden ile başarısız olur. Aynı izin durum, öncelik ve sorumlu değişikliklerini, sorun ve log kurallarını kapsar. Her istek bu alanlardan 1 veya daha fazlasını ayarlar:

Alan	Değerler
`status`	`unresolved`, `resolved` veya `archived`. `ignored`, `archived` için eski bir addır.
`priority`	`high`, `medium` veya `low`.
`assignee`	Bir kullanıcı kimliği, giriş yapmış hesap için `me`, bir ekip için `team:<team_id>` veya sorumluyu kaldırmak için `none`.

Bu alanların hiçbirini içermeyen bir istek 422 ve validation_failed ile başarısız olur. Bir sorunun 0 veya 1 sorumlusu olur: bir hesap ya da bir ekip. Hesap projeyi okuyabilmeli, ekip de projenin organizasyonunda olmalıdır. Aksi hâlde istek 422 ve validation_failed ile başarısız olur ve LogBrew hiçbir şeyi değiştirmez. Atayabileceğiniz hesapları Sorumluları listeleyin bölümünden alın. Diğer her assignee değeri de 422 ve validation_failed ile başarısız olur. Ayarladığınız öncelik sabit kalır. Sizin ayarladığınız bir öncelik yoksa öncelik sorunun önem düzeyini izler: error ve critical için high, warning için medium, info için low olur. İstenen değere zaten sahip olan bir alan değişmez. Bir zaman aşımından sonra aynı isteği yeniden gönderebilirsiniz. Zaman aşımı, değişikliğin gerçekleşmediğini kanıtlamaz. Farklı bir değişiklik göndermeden önce sorunu yeniden okuyun.

Tek bir sorunu güncelleyin

Yanıtta archived durumunu, önceliği ve sorumluyu almak için response_version=4 ekleyin. Sürüm 4’te assignee değeri { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" } veya null olur. Sürüm 3, ekip sorumlusunu null olarak gösterir.

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" }'

Yanıt güncellenmiş sorundur. Sorun durumu yanıt örnekleri bölümüne bakın.

Sorunları toplu güncelleyin

project_id değerini ve o projeden 1 ile 100 arası farklı sorun kimliğini gönderin:

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>"
  }'

İstek aynı değişikliği her soruna uygular. Yanıt project_id ve results alanlarını içerir. results, istek sırasıyla her sorun kimliği için 1 sonuç içerir. Her sonuç issue_id, outcome ve issue alanlarını içerir. issue, yanıt sürümü 3’te güncel sorundur. not_found için null olur. Her sorunu yanıt sürümü 4’te almak için gövdeye "response_version": 2 ekleyin.

`outcome`	Anlamı
`updated`	LogBrew değişikliği uyguladı.
`unchanged`	Sorun istenen değerlere zaten sahipti.
`not_found`	Projede bu kimliğe sahip bir sorun yok. LogBrew bunun için hiçbir şeyi değiştirmedi.

Boş bir liste, 100’den fazla kimlik veya tekrarlanan bir kimlik 422 ve validation_failed ile başarısız olur. Daha büyük bir kümeyi birden fazla isteğe bölün. Hesap projeyi okuyamıyorsa istek 404 ve not_found ile başarısız olur.

Sorumluları listeleyin

O projede sorun atanabilecek tüm hesapları almak için proje kimliğini gönderin:

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

Liste projeyi okuyabilen her hesabı içerir. Her girdi user_id, name ve email alanlarını içerir. Hesabın adı yoksa name değeri null olur. teams listesini de almak için response_version=2 ekleyin. Bu liste, projenin organizasyonundaki her ekibi team_id, slug ve name ile verir. Sorumlu listesi yanıtı bölümüne bakın. Projeyi okuyabilen her hesap bu listeyi alabilir. Hesap projeyi okuyamıyorsa istek 404 ve not_found ile başarısız olur. Bir üye projeye erişimini kaybettiğinde o üyeye atanan sorunlar sorumlu göstermez. Üye erişimi yeniden alırsa sorunlar o üyeyi yeniden gösterir. Ancak bu arada biri sorumluyu değiştirdiyse veya kaldırdıysa bu olmaz.

Sahiplik ve önerilen sahipler

GET /api/telemetry/issues/ownership?project_id=<project-uuid> isteği rules, codeowners, updated_at ve unresolved_owners döndürür. Projeyi okuyabilen her hesap bunu okuyabilir. project_id ile birlikte rules, codeowners veya ikisini gönderen bir PUT isteği o metni değiştirir ve sorunları yönetme izni gerektirir. Göndermediğiniz bir alanın metni korunur, boş bir dize ise metni temizler. Her metin en fazla 128 KiB olabilir. Geçersiz metin 422 ile başarısız olur ve hatalı satırı belirtir. GET /api/telemetry/issues/{issue_id}/owners?response_version=2 isteği suggested_assignee, owners ve inputs döndürür. Her sahipte type (user veya team), source (ownership_rule, codeowners veya recent_activity), rule, line ve matched bulunur. Varsayılan sürüm 1 yalnızca hesapları listeler.

Sorun geçmişi

GET /api/telemetry/issues/{issue_id}/activity?response_version=2 isteği en yeniden başlayarak activity ve next_cursor döndürür. Her girdide type (status, priority, assigned, unassigned, severity_rule veya first_seen), value, actor_id, actor, assignee_id, assignee, team ve at bulunur. limit 1 ile 200 arasındadır, varsayılanı 50’dir. Sonraki sayfa için next_cursor içinden gelen cursor_time ve cursor_id değerlerini gönderin.

Bildirimler

GET /api/telemetry/issues/notifications isteği notifications, unread, read_at ve next_cursor döndürür. Her bildirim, başka bir hesabın bir sorunu size veya ekibinize atamasıdır. Boş bir JSON nesnesiyle ya da read_at ile gönderilen POST /api/telemetry/issues/notifications/read isteği okundu işaretinizi taşır. İşaret hiçbir zaman geri gitmez.

Sorun ve log kurallarını ayarlayın

Bir kural, LogBrew’ün eşleşen sinyalleri nasıl gösterdiğini değiştirir. Veri silmez. Yakalanan severity değeri değişmez. Yanıt kuralı triage içinde gösterir.

İstek	JSON gövdesi
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity değeri info, warning, error, critical veya source olur. source geçersiz kılmayı kaldırır ve yakalanan önem düzeyini yeniden gösterir. Log kuralında ignored: true, eşleşen logları varsayılan log listesinden gizler. Bu logları status=ignored veya status=all ile okuyun. Kural saklanan ve gelecekte eşleşecek sinyallere uygulanır. Başka bir değer 422 ve validation_failed ile başarısız olur.

Boş sürüm göndermeyin. LogBrew sürüm takibinin güvenilir kalması için bunları reddeder.

​Sınırlı bir istek gönderin

​Uç noktalar

​Veri alımı

​Telemetri okumaları

​Dağıtımlar

​İncelemeler

​Ürün analizleri

​Canlı akış

​Hesap ve giriş

​Başarı durum kodları

​Sorgu filtreleri ve sayfalama

​Yanıtlar ve hatalar

​Sorunları güncelleyin

​Tek bir sorunu güncelleyin

​Sorunları toplu güncelleyin

​Sorumluları listeleyin

​Sahiplik ve önerilen sahipler

​Sorun geçmişi

​Bildirimler

​Sorun ve log kurallarını ayarlayın

Sınırlı bir istek gönderin

Uç noktalar

Veri alımı

Telemetri okumaları

Dağıtımlar

İncelemeler

Ürün analizleri

Canlı akış

Hesap ve giriş

Başarı durum kodları

Sorgu filtreleri ve sayfalama

Yanıtlar ve hatalar

Sorunları güncelleyin

Tek bir sorunu güncelleyin

Sorunları toplu güncelleyin

Sorumluları listeleyin

Sahiplik ve önerilen sahipler

Sorun geçmişi

Bildirimler

Sorun ve log kurallarını ayarlayın