Skip to main content
Her okuma rotası kendi sorgu anahtarlarını kabul eder. Filtre tablosundaki bir rota, tablo aksini söylemedikçe bilinmeyen bir anahtarı veya yanlış türdeki bir değeri 422 ve validation_failed ile reddeder. project, trace ve user gibi kolay eş adlar sorgu anahtarı değildir. Bir filtreyi bir rotadan başka bir rotaya taşımayın.

Filtrelenmiş bir istek oluşturun

Sorgu dizesini yolun arkasına koyun. Ayrılmış karakterlerin güvenli kalması için --data-urlencode kullanın. Bu istek, bir projenin son 24 saatteki kritik loglarını okur:
Filtreleri şu sırayla ekleyin:
  1. Projeyi project_id veya project_ids ile seçin.
  2. since ve isteğe bağlı olarak until ile bir zaman aralığı ekleyin.
  3. Hizmet, sürüm, ortam, durum veya sinyale özgü filtreleri ekleyin.
  4. Daha küçük bir sayfa için limit ayarlayın.
  5. Cursor alanlarını yalnızca bir cursor yanıtı onları döndürdükten sonra ekleyin.
Dönen her satır, istekteki tüm filtrelerle eşleşir. Gönderilmeyen bir filtre rotanın varsayılanını kullanır. Örneğin GET /api/logs, status gönderilmediğinde status=active kullanır.

Filtre tablosu

“Zorunlu” sütunundaki anahtarlar istekte bulunmalıdır. Diğer tüm anahtarlar isteğe bağlıdır. Sorun incelemesinde selection değeri first, latest veya recommended olur. selection veya occurrence_id gönderin, ikisini birden göndermeyin. İkisi de 2 ile 13 arasında bir response_version gerektirir. Sürüm 2 veya sonrasında seçici gönderilmezse LogBrew recommended kullanır. occurrence_id değerini GET /api/telemetry/issues/{issue_id}/events rotasından alın. POST analiz rotaları bir JSON gövdesi alır. Bkz. Ürün analizleri.

Ortak ve sinyale özgü filtreler

service_name, release ve environment her telemetri listesini daraltır. SDK’nızın gönderdiği değerlerin aynısını kullanın. Bazı filtreler tek bir sinyale aittir:
  • Loglar search, trace_id, severity ve attribute_filters kabul eder.
  • Loglar status kabul eder: active (varsayılan), ignored veya all. ignored, bir log kuralının etkin görünümden gizlediği logları seçer.
  • Sorunlar sorun status değerini kabul eder: unresolved, resolved veya archived. ignored, archived için eski bir addır ve aynı sorunları seçer.
  • Sorunlar severity kabul eder: info, warning, error veya critical.
  • Sorunlar priority kabul eder: high, medium veya low.
  • Sorunlar assignee kabul eder: giriş yapmış hesaba atanmış sorunlar için me, sorumlusu olmayan sorunlar için none, ekiplerinizin sorunları için my_teams, bir kullanıcı kimliği veya team:<team_id>.
  • Aksiyonlar ve metrikler name kabul eder.
  • Aksiyonlar distinct_id kabul eder.
  • İzler iz status değerini ve min_duration_ms kabul eder.
  • Dağıtımlar status kabul eder: succeeded veya failed.
Log ve sorun severity filtreleri geçerli önem düzeyini karşılaştırır. Bir kural önem düzeyini değiştirdiyse filtre kuralın değerini kullanır. Bkz. Önem düzeyi değerleri.

Zaman aralığı

since, 24h veya 7d gibi pozitif bir tam saat veya gün sayısı ya da bir RFC3339 zaman damgası kabul eder. Kısa süre biçimi, her isteğin zamanına göre hesaplanır. until yalnızca RFC3339 zaman damgası kabul eder. Bitiş zamanı aralığa dâhil değildir: tam olarak until anındaki bir satır sonuçta yer almaz. since dâhildir. Örneğin since=2026-10-01T00:00:00Z ve until=2026-10-02T00:00:00Z tam 1 günü seçer. LogBrew zamanları milisaniye hassasiyetinde karşılaştırır. until, since değerinden sonra olmalıdır. Değilse veya until bir RFC3339 zaman damgası değilse istek 422 ve validation_failed ile başarısız olur. Birden fazla sayfalık bir okumada tek bir RFC3339 başlangıç zamanı seçin ve her sayfada onu kullanın. Her sayfada aynı until değerini de koruyun. Bu istek 1 günün hata loglarını okur:
Dağıtım listesi farklı zaman kuralları kullanır. since ve until yalnızca RFC3339 zaman damgası kabul eder ve ikisi de dâhildir. Dağıtımın bittiği zamanı karşılaştırırlar.

Sorun yanıt sürümü

Sorun listesi ve sorun ayrıntısı response_version=1, response_version=2, response_version=3 veya response_version=4 kabul eder. Varsayılan sürüm 1’dir. Başka bir değer 422 ve validation_failed ile başarısız olur.
  • Sürüm 1 arşivlenmiş durumu ignored olarak gösterir. Önceliği göstermez.
  • Sürüm 2 arşivlenmiş durumu archived olarak gösterir. priority ve priority_source alanlarını ekler.
  • Sürüm 3, sürüm 2’nin tüm alanlarını içerir. assignee alanını ekler.
  • Sürüm 4, sürüm 3’ün tüm alanlarını içerir. assignee alanında type bulunur: user veya team.
Her sürüm status=archived, priority ve assignee kabul eder. Bkz. Sorun yanıtı.

Önem düzeyi filtresi

GET /api/logs üzerinde severity=info|warning|error|critical kullanın. Eski level anahtarı uyumluluk için bir eş addır. İki anahtar da standart değerleri ve trace, debug, warn ve fatal eş adlarını kabul eder. LogBrew karşılaştırmadan önce bir eş adı standart değerine çevirir. Bir istek hem severity hem level gönderirse LogBrew önce ikisini de standart hâle getirir. Çelişen değerler şu yanıtla reddedilir:

İz filtreleri

İz keşfinde status değeri error veya ok olur. İkisini de dâhil etmek için göndermeyin. min_duration_ms sıfır veya daha büyük olmalıdır. Yalnızca iz keşfine uygulanır. Bu istek en az 500 milisaniye süren hatalı izleri bulur:
İz ayrıntısı ve özeti için trace_id değerini yol parçası olarak yüzde kodlamasıyla gönderin. Sorgu anahtarı olarak göndermeyin.

Proje kapsamı

Tek bir projeyi okumak için project_id=<project-uuid> kullanın. Tabloda project_ids listeleyen rotalarda, 2 ile 50 arasındaki kesin bir proje kümesi için project_ids=<uuid>,<uuid> kullanın. Bu rotalarda hesabın okuyabildiği her projeyi okumak için iki anahtarı da göndermeyin. project_id gerektiren bir rota yalnızca 1 proje kabul eder.
LogBrew şu seçimleri 422 ve validation_failed ile reddeder:
  • Hem project_id hem project_ids içeren bir istek.
  • 2’den az veya 50’den fazla kimlik içeren bir project_ids değeri.
  • Yinelenen bir kimlik veya UUID olmayan bir kimlik.
project_ids içindeki bir kimlik hesabın okuyamadığı bir projeyse istek 404 ve not_found ile başarısız olur. O kimliği çıkarıp devam etmeyin. Kullanıcıdan yeni bir küme seçmesini isteyin. Her cursor sayfasında aynı proje kapsamını koruyun. Boş bir sonuçtan sonra proje filtresini kaldırmayın. Bu, farklı bir soru sormak olur.

Zaman dilimli seriler

GET /api/telemetry/metrics/series, bir metriği zaman dilimleri olarak döndürür. GET /api/telemetry/summary/volume, sinyal sayılarını zaman dilimleri olarak döndürür. İki rota da şu kuralları kullanır:
  • since zorunludur. until isteğe bağlıdır ve varsayılanı istek zamanıdır.
  • since ile until arasındaki aralık en fazla 31 gündür.
  • interval değeri auto, 1m, 5m, 15m, 1h, 6h veya 1d olur. Varsayılan auto değeridir. 500’den fazla zaman dilimi oluşturan bir aralık başarısız olur.
  • service_name, release ve environment kesin eşleşme filtreleridir.
Metrik serilerinde name, GET /api/telemetry/metrics rotasından alınan kesin metrik adıdır. group_by değeri none, service_name, release veya environment olur. series_limit 1 ile 20 arasındadır. Sinyal hacminde until gelecekte olamaz ve response_version yalnızca 1 olabilir.

Log özniteliklerini filtreleyin

Arayabileceğiniz öznitelik yollarını ve türlerini bulmak için GET /api/logs/attributes kullanın. Ardından GET /api/logs rotasına attribute_filters gönderin. İki istek de since gerektirir.

Öznitelik kataloğunu okuyun

Bu istek, bir projede status içeren sayısal yolları bulur:
Yanıt düz bir dizi değil, bir nesnedir. Bu yapay örnekte 2 öznitelik ve bir sonraki sayfa vardır:
type değeri string, number veya boolean olur. observed_count, aralıkta bu yola ve türe sahip log sayısıdır. last_seen_at, bunların en sonuncusunun zamanıdır. Bir log birçok yola sahip olabilir. Log sayısını bulmak için bu sayıları toplamayın. coverage, bir öznitelik filtresinin hangi logları arayabileceğini bildirir: Bu 3 grubun toplamı total_logs değerine eşittir. Kataloğun type, search ve cursor değerleri kapsama oranını değiştirmez. Boş bir attributes listesi, total_logs değerinin sıfır olduğu anlamına gelmez. Kataloğun status anahtarı yoktur. Önem düzeyi filtresi geçerli önem düzeyini değil, yakalanan önem düzeyini karşılaştırır. search, kontrol karakteri içermeyen, 1 ile 128 bayt arasında bir yol alt dizesidir. limit, bir sayfadaki öznitelik sayısını belirler.

Kataloğa devam edin

Katalog pagination=cursor kullanmaz. Her filtreyi tekrarlayın ve next_cursor içindeki 3 alanın tamamını kopyalayın: next_cursor değeri null olduğunda durun.

Türü belirtilmiş bir filtre uygulayın

Yolu ve türü katalogdan kopyalayın. Yollar noktalı anahtarlar değil, JSON Pointer söz dizimini kullanır. Yoldaki ~0 veya ~1 kaçış dizilerini değiştirmeyin. Bu istek, sayısal yanıt durumu 500 veya daha büyük olan logları okur:
attribute_filters, 1 ile 4 arasında filtre içeren bir JSON dizisidir. Bir log her filtreyle eşleşmelidir. Her filtrede path, type, operator ve value bulunur. value değerinin JSON türü type ile eşleşmelidir: 500 sayısı "500" dizesiyle aynı değildir. ne yalnızca bu yola sahip loglarla eşleşir. Yolu olmayan bir log ne ile eşleşmez. string için case_sensitive isteğe bağlıdır ve varsayılanı false değeridir. LogBrew, number ve boolean için "case_sensitive": true değerini reddeder. Şu sınırlar geçerlidir:
  • JSON dizisi en fazla 4.096 bayttır.
  • Bir dize değeri en fazla 1.024 bayttır.
  • contains ve starts_with boş olmayan bir dize gerektirir.
  • Bir sayı sonlu olmalı ve -9.007.199.254.740.992 ile 9.007.199.254.740.992 arasında olmalıdır.
Dizinin arayamadığı bir log hiçbir filtreyle eşleşmez. Bu log, attribute_filters içermeyen bir istekte yine görünebilir. Log yanıtı için Log yanıtı bölümüne bakın.

Öznitelik hatalarını düzeltin

Aşağıdaki her hata 422 ve validation_failed döndürür: Yeniden denemeden önce isteği düzeltin. Bir filtreyi kaldırmayın. Bu, sonucu değiştirir.

Cursor ile sayfalama

Cursor modu isteğe bağlıdır. Bu mod olmadan liste rotaları düz bir dizi döndürür. İlk sayfa için cursor alanları olmadan pagination=cursor gönderin. Sonraki her sayfa için her filtreyi tekrarlayın ve cursor alanlarının tamamını gönderin: Dönen next_cursor alanlarını sonraki isteğe şöyle aktarın:
  • next_cursor.time değeri cursor_time olur.
  • next_cursor.id değeri cursor_id olur.
  • İzlerde next_cursor.trace_id değeri cursor_trace_id olur.
  • Sürümlerde dönen her alan adının başına cursor_ ekleyin; örneğin next_cursor.release değeri cursor_release olur.
next_cursor değeri null olduğunda durun. Cursor’ı son satırdan hesaplamayın. Sürüm cursor’ı seçilen projeleri değiştirmez. Özgün project_id veya project_ids değerini koruyun.
limit sayfa boyutunu belirler. Bir sayfa daha az satır içerebilir. Bu rotalar page veya page_number kabul etmez. Çoğu rotada LogBrew, en fazla değerin üzerindeki bir limit değerini en fazla değere düşürür. Dağıtım listesi 1 ile 100 dışındaki bir limit değerini 422 ile reddeder. Dağıtım listesi pagination=cursor olmadan da her zaman next_cursor içeren bir sayfa nesnesi döndürür. LogBrew şu istekleri 422 ve validation_failed ile reddeder:
  • cursor dışında bir pagination değeri.
  • pagination=cursor olmadan gönderilen cursor alanları.
  • Eksik bir cursor alanı kümesi.
  • RFC3339 zaman damgası olmayan bir cursor_time.
Cursor bir konumu işaretler; veriyi dondurmaz. Güncel bir görünüme ihtiyacınız olduğunda yeni bir ilk sayfayla başlayın. CLI aynı alanları kullanır:

Boş bir sonucu teşhis edin

Boş bir liste, hiçbir satırın tüm filtrelerle eşleşmediği anlamına gelir. Diğer sinyaller hakkında hiçbir şey söylemez. İsteği şu sırayla kontrol edin:
  1. Proje kimliğini doğrulayın.
  2. İsteğe bağlı filtreleri birer birer kaldırın.
  3. Beklenen olay daha eskiyse since değerini genişletin. Beklenen olay daha yeniyse until değerini kaldırın veya daha ileri bir zamana alın.
  4. service_name, release ve environment değerlerini SDK’nızın gönderdiği değerlerle karşılaştırın.
  5. Loglarda, bir log kuralı beklenen logu gizleyebiliyorsa status=all ekleyin.
  6. Rotanın her filtreyi kabul ettiğini doğrulayın.

Reddedilen bir sorgudan sonra kurtarma

Reddedilen bir sorgu standart hata zarfını döndürür. Bilinmeyen bir anahtar veya yanlış türdeki bir değer 422 döndürür:
Yaygın düzeltmeler:
  • Kolay bir eş adı filtre tablosundaki anahtarla değiştirin.
  • Rotanın gerektirdiği tüm devam cursor alanlarını gönderin.
  • İlk sayfa isteğinden cursor alanlarını kaldırın.
  • Yalnızca bir proje seçici kullanın.
  • Desteklenmeyen bir önem düzeyini veya iz durumunu standart bir değerle değiştirin.
Hata kodları ve kurtarma için API hataları sayfasına bakın. Yanıt gövdeleri için Yanıt biçimleri sayfasına bakın.