> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.
# API yanıt biçimi ve JSON yanıt örnekleri
> Telemetri listeleri, cursor sayfaları, canlı olaylar, değişiklikler, başarı ve hata durumları için LogBrew API yanıtlarını okuyun.
Bu sayfa, [Telemetri API'sinin](/tr/reference/telemetry-api) her yanıt ailesi
için bir örnek gösterir. Tüm değerler yapaydır. Hata kodları ve kurtarma için
[API hataları](/tr/reference/api-errors) sayfasına bakın.
## Yanıtı okuyun
Her yanıtı şu sırayla okuyun:
1. HTTP durumunu okuyun.
2. Gövdenin, rotanın kendi yapısında olduğundan emin olun.
3. Her `project_id` değerinin istenen proje kapsamında olduğundan emin olun.
4. Standart enum değerlerini ve kimlikleri değiştirmeden koruyun.
5. `next_action` alanını yalnızca istemci onun `code` ve `target` değerlerini
destekliyorsa izleyin.
6. `null` değerini, gönderilmeyen bir alanı ve boş listeyi ayrı durumlar olarak
tutun.
`200 OK` yanıtı boş bir liste içerebilir. Boş bir log listesi, istekle eşleşen
log olmadığı anlamına gelir. Sorunların, izlerin veya aksiyonların da boş olduğu
anlamına gelmez. Sinyalleri zaman damgaları yakın diye birleştirmeyin. Bir ize
yalnızca yanıt onun tam `trace_id` değerini içeriyorsa geçin.
`404` ile boş liste farklı sonuçlardır. Bir liste rotası, eşleşen kayıt yoksa
`[]` döndürür. Bir ayrıntı rotası, okunabilir bir kayıt bulamazsa
`code: not_found` ile `404` döndürür. İki sonuç da veri alımının başarısız
olduğunu kanıtlamaz.
## Ne göndermelisiniz
Yanıtlar, gönderdiğiniz telemetri kadar işe yarar. Bu değerleri her zarfta
veya SDK kurulumunda gönderin:
* `release` ve `environment`.
* Hizmetler, aksiyonlar ve metrikler için sabit adlar.
* Loglar, span'ler, aksiyonlar ve sorunlar aynı isteğe aitse iz bağlamı.
* Standart önem düzeyi değerleri: `info`, `warning`, `error` ve `critical`.
* Hata ayıklamaya yardım eden, gizli bilgi veya gereksiz kişisel veri
içermeyen öznitelikler.
[SDK entegrasyonu](/tr/guides/sdk-ingestion) ve
[Yakalanan verileri denetleyin](/tr/guides/safe-capture) sayfalarına bakın.
## Veri alımı yanıtı
Herkese açık SDK'lar `POST /v1/events` yanıtını sizin yerinize okur. Uygulama
kodunun bu yanıtı ele alması gerekmez.
### SDK toplu gönderim yanıtı
Başarılı bir SDK toplu gönderimi, her akış için kabul edilen sayılarla
`200 OK` döndürür:
```json theme={null}
{
"issues": 1,
"logs": 2,
"trace_spans": 3,
"actions": 1,
"metrics": 1,
"already_accepted": 0,
"context_updated": true,
"next": "review accepted telemetry in logs, issues, traces, actions, metrics, or live feed",
"next_action": {
"code": "review_ingested_telemetry",
"target": "telemetry_reads"
}
}
```
| Alan | Anlamı |
| - | - |
| `issues`, `logs`, `trace_spans`, `actions`, `metrics` | LogBrew'ün bu toplu gönderimden kabul ettiği olaylar. |
| `already_accepted` | Kimliğini LogBrew'ün daha önce kabul ettiği olaylar. LogBrew bunları yeniden saklamaz. |
| `context_updated` | Toplu gönderim sürüm veya ortam bağlamını güncellediyse `true`. |
Sayılar yalnızca bu toplu gönderimi kapsar. LogBrew'ün daha önce kabul ettiği
bir toplu gönderimi yeniden denediğinizde her akış için `0` döner ve olay
sayısı `already_accepted` alanında yer alır. Yeniden denerken asıl olay
kimliklerini koruyun.
### Yerel zarf yanıtı
`POST /api/telemetry/ingest`, her akış için kabul edilen öğe sayılarıyla
`200 OK` döndürür:
```json theme={null}
{
"issues": 0,
"logs": 1,
"trace_spans": 0,
"actions": 1,
"already_accepted": 0,
"next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
"next_action": {
"code": "review_ingested_telemetry",
"target": "telemetry_reads"
}
}
```
Yerel yanıtta `metrics` veya `context_updated` alanı yoktur. Bunları
eklemeyin. `already_accepted`, `id` değerini LogBrew'ün bu proje için daha önce
kabul ettiği öğeleri sayar. [Doğrudan yerel zarf](/tr/guides/sdk-ingestion#required-envelope-fields)
bölümüne bakın.
### Veri alımı hataları
`code: ingest_key_invalid` ile `401`, alım bearer tokenının iptal edildiği,
süresinin dolduğu veya proje için geçerli olmadığı anlamına gelir.
`POST /v1/events` üzerinde bearer tokenı yoksa veya token bir alım anahtarı
değilse `code: unauthorized` ile `401` döner. Proje kapsamlı güncel alım bearer
tokenını kullanın. Hesap bearer tokenıyla yeniden denemeyin.
Reddedilen bir SDK toplu gönderimi `code: validation_failed` ile `422`
döndürür:
```json theme={null}
{
"error": "SDK event ids must be unique within a batch",
"code": "validation_failed",
"next": "send release/environment context plus issue, log, span, action, or metric events from a current LogBrew SDK",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
Diğer `error` değerleri arasında
`SDK event batch requires at least one event` ve
`SDK event type is not supported by this ingest route` bulunur. SDK sürümünü
ve aktarım yapılandırmasını kontrol edin. Boş bir toplu gönderim yapmayın.
Sırf doğrulamayı geçmek için olay türlerini veya kimliklerini değiştirmeyin.
`POST` dışında bir yöntemle yapılan istek `code: method_not_allowed` ile `405`
döndürür. Okunamayan bir JSON gövdesi `code: invalid_json` döndürür.
## Telemetri listesi yanıt biçimi
Liste rotaları varsayılan olarak yalın bir JSON dizisi döndürür. Başarılı boş
liste `[]` olur.
`pagination=cursor` ile rota bir zarf döndürür. Koleksiyon anahtarı sinyale
göre değişir:
| Rota | Koleksiyon anahtarı |
| - | - |
| `/api/logs` | `logs` |
| `/api/telemetry/issues` | `issues` |
| `/api/telemetry/issues/{issue_id}/events` | `events`, en üst düzeyde `issue_id` ile |
| `/api/telemetry/actions` | `actions` |
| `/api/telemetry/metrics` | `metrics` |
| `/api/telemetry/releases` | `releases` |
| `/api/telemetry/traces` | `traces`, en üst düzeyde `naming_quality` ile |
`next_cursor`, devam alanlarını içeren bir nesnedir. Son sayfada `null` olur.
Satırlar en yeniden eskiye sıralanır. [Cursor ile sayfalama](/tr/reference/telemetry-api-filters#cursor-pagination)
bölümüne bakın.
### Log yanıtı
`limit=1` ile bir log cursor sayfası:
```json theme={null}
{
"logs": [
{
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"level": "warning",
"severity": "warning",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": false
},
"source": "runtime",
"message": "checkout retry scheduled",
"attributes": { "route": "/checkout" },
"occurred_at": "2026-06-01T12:00:00Z",
"environment": "production",
"release": "api@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
],
"next_cursor": {
"time": "2026-06-01T12:00:00Z",
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d"
}
}
```
Loglarda uyumluluk için `level`, gösterim için `severity` bulunur. İkisi de
standart değeri tutar. `triage`, bir önem düzeyi kuralının sonucunu tutar.
[Önem düzeyi kuralı yanıtları](#severity-rule-responses) bölümüne bakın.
Logun iz bağlantısı yoksa `trace_id` ve `span_id` değerleri `null` olur. Bu
durumda `next_action`, `telemetry_logs` hedefiyle `inspect_related_logs` olur.
Loglar, sorunlar ve aksiyonlar aynı 2 `next_action` çiftini kullanır.
`GET /api/logs/{log_id}`, tek bir logu aynı yapıda döndürür.
### Sorun yanıtı
`GET /api/telemetry/issues/{issue_id}`, gruplanmış tek bir sorun döndürür.
Liste de aynı nesneleri döndürür. Bu örnek varsayılan yanıt sürümü 1'i
kullanır:
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"fingerprint": "payment-error",
"severity": "error",
"triage": {
"effective_severity": "error",
"ignored": false,
"rule_applied": false
},
"title": "PaymentError",
"message": "payment provider timed out",
"stack_trace": null,
"attributes": {},
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
},
"status": "unresolved",
"occurrence_count": 2,
"first_seen_at": "2026-07-13T07:00:00Z",
"last_seen_at": "2026-07-13T08:00:00Z"
}
```
Sürüm 1'de `status` değeri `unresolved`, `resolved` veya `ignored` olur.
Arşivlenmiş bir sorunda `triage.ignored` değeri `true` olur. `next_action`
çiftleri ve onları izleyen okumalar için
[Bir sorunu inceleyin](/tr/guides/investigate-an-issue) sayfasına bakın.
`first_seen_at` ve `last_seen_at`, ilk ve en son oluşumun zamanlarıdır. Durum
değiştiğinde değişmezler.
Bazı alanlar yalnızca LogBrew'de veri varsa görünür:
| Alan | Ne zaman görünür |
| - | - |
| `span_id` | Sorunun bir span bağlantısı varsa. Yoksa alan gönderilmez. |
| `diagnostics` | En son oluşumda bir istisna türü veya önceki adımlar (breadcrumbs) varsa. [Sorun oluşum geçmişi](#issue-occurrence-history) bölümüne bakın. |
| `symbolication` | Yalnızca `GET /api/telemetry/issues/{issue_id}` üzerinde, sorunun bir sürüm derleme dosyası kimliği varsa. [Source map'ler (kaynak eşlemesi)](/tr/guides/source-maps) sayfasına bakın. |
`symbolication.status` değeri `resolved`, `invalid_metadata`,
`artifact_not_found`, `source_not_resolved` veya `unavailable` olur. Liste,
durum değişiklikleri ve kural değişiklikleri `symbolication` döndürmez.
`response_version=2` ile sorun aynı alanları içerir. Şu değişiklikler olur:
| Alan | Sürüm 2 değeri |
| - | - |
| `status` | `unresolved`, `resolved` veya `archived`. Sürüm 1, `archived` değerini `ignored` olarak gösterir. |
| `priority` | `high`, `medium` veya `low`. |
| `priority_source` | Önceliği bir kişi ayarladıysa `manual`. Öncelik uygulanan önem düzeyini izliyorsa `derived`. |
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "archived",
"severity": "error",
"priority": "low",
"priority_source": "manual"
}
```
Bu örnek alanların yalnızca bir kısmını gösterir. Türetilen öncelik `error` ve
`critical` için `high`, `warning` için `medium`, `info` için `low` olur.
Öncelik `triage.effective_severity` değerini kullanır. Bu yüzden bir sorun
önem düzeyi kuralı onu değiştirebilir.
`response_version=3` ile sorun, sürüm 2'nin tüm alanlarını ve `assignee`
alanını içerir. Sorunun sorumlusu yoksa `assignee` değeri `null` olur:
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "unresolved",
"priority": "high",
"priority_source": "derived",
"assignee": {
"user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"name": "Ada Example",
"email": "ada@example.com"
}
}
```
| Alan | Anlamı |
| - | - |
| `assignee.user_id` | Sorumlunun kullanıcı kimliği. Bir filtrede veya değişiklikte `assignee` olarak gönderin. |
| `assignee.name` | Sorumlunun adı. Hesabın adı yoksa `null`. |
| `assignee.email` | Sorumlunun e-posta adresi. |
Atanan üye projeyi artık okuyamıyorsa sorunda sorumlu görünmez.
`response_version=4` ile `assignee` alanında `type` de bulunur. `user`
türündeki sorumluda, sürüm 3'teki gibi `user_id`, `name` ve `email` vardır.
`team` türündeki sorumluda `team_id`, `slug` ve `name` vardır. Sürüm 3,
sorumlu ekibi `null` olarak gösterir. CLI sürüm 4'ü ister:
```json theme={null}
{
"assignee": {
"type": "team",
"team_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"slug": "payments",
"name": "Payments"
}
}
```
Başka bir `response_version` değeri `code: validation_failed` ile `422`
döndürür. Bir cursor sayfası, `issues` içindeki her sorun için aynı sürümü
kullanır.
### Sorumlu listesi yanıtı
`GET /api/telemetry/issues/assignees?project_id=`, projede sorun
atanabilecek tüm hesapları döndürür:
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"assignees": [
{
"user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"name": "Ada Example",
"email": "ada@example.com"
},
{
"user_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"name": null,
"email": "sam@example.com"
}
]
}
```
`teams` alanını da almak için `response_version=2` ekleyin: projenin
organizasyonundaki her ekip `team_id`, `slug` ve `name` ile gelir.
Hesap projeyi okuyamıyorsa rota `code: not_found` ile `404` döndürür.
### Aksiyon yanıtı
```json theme={null}
{
"id": "d8ee3a6f-3918-440b-96cb-14166419399a",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "checkout_failed",
"distinct_id": "user_123",
"session_id": "session_456",
"occurred_at": "2026-06-01T12:00:00Z",
"properties": { "surface": "checkout" },
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
```
`distinct_id` tek bir aktörü veya oturumu izler. `distinct_id` ve
`session_id` değerlerini opak kimlikler olarak ele alın. `session_id` ve
`trace_id` eksikse `null` olur. `span_id` eksikse gönderilmez. Bir aksiyonun
önem düzeyi yoktur. [Ürün olaylarını yakalama](/tr/guides/product-events) sayfasına
bakın.
### Metrik yanıtı
```json theme={null}
{
"id": "6f1c2d3e-4a5b-4c6d-8e7f-901234567890",
"event_id": "metric-1",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "http.server.duration",
"kind": "histogram",
"value": 12.5,
"unit": "ms",
"temporality": "delta",
"attributes": {},
"occurred_at": "2026-07-13T08:00:00Z",
"environment": "production",
"release": "checkout@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
```
Her öğe tek bir ölçüm örneğidir. Örnek sayısını olay veya kullanıcı sayısı
olarak kullanmayın. `unit`, `temporality`, `trace_id` ve `span_id` eksikse
`null` olur. `null` değeri sıfır değildir.
### Sürüm yanıtı
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"release": "api@1.2.3",
"environment": "production",
"service_name": "checkout-api",
"issue_count": 3,
"log_count": 824,
"trace_span_count": 421,
"action_count": 19,
"metric_count": 87,
"first_seen_at": "2026-06-01T12:00:00Z",
"last_seen_at": "2026-06-01T12:15:00Z",
"trace_health": {
"status": "errors_observed",
"trace_count": 42,
"error_trace_count": 3,
"error_rate_basis_points": 714
},
"next_action": {
"code": "inspect_release_issues",
"target": "telemetry_issues"
}
}
```
Bir satır tek bir proje, sürüm, ortam ve hizmeti kapsar. Sayıları yalnızca o
satırı anlatır.
`trace_health.status`, satırda iz yoksa `unknown`, aksi hâlde
`no_errors_observed` veya `errors_observed` olur. `error_rate_basis_points`,
hata span'i olan izlerin `0` ile `10000` arasındaki payıdır. Tüm istekler için
bir hata oranı değildir.
`next_action`, veri içeren ilk sinyal türünü şu sırayla gösterir:
| `code` | `target` |
| - | - |
| `inspect_release_issues` | `telemetry_issues` |
| `inspect_release_traces` | `trace_explorer` |
| `inspect_release_logs` | `telemetry_logs` |
| `inspect_release_actions` | `telemetry_actions` |
| `inspect_release_metrics` | `telemetry_metrics` |
| `review_release_telemetry` | `telemetry_reads` |
[Sürümler](/tr/concepts/releases) sayfasına bakın.
### İz keşfi yanıtı
`GET /api/telemetry/traces?pagination=cursor`, her iz için bir satır ve dönen
sayfa için bir `naming_quality` kaydı döndürür:
```json theme={null}
{
"traces": [
{
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"project_ids": ["123e4567-e89b-12d3-a456-426614174000"],
"root_span_name": "POST /checkout",
"root_service_name": "checkout-api",
"root_operation": "http.server",
"span_count": 3,
"error_span_count": 1,
"service_count": 1,
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 45,
"services": ["checkout-api"],
"releases": ["checkout@1.2.3"],
"environments": ["production"],
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
],
"next_cursor": null,
"naming_quality": {
"evaluated_traces": 1,
"meaningful_name_traces": 1,
"generic_name_traces": 0,
"unmatched_route_traces": 0,
"generic_operation_traces": 0,
"truncated": false,
"next_action": null
}
}
```
`naming_quality` yalnızca dönen sayfayı kapsar. Hesabın tamamı için bir puan
değildir. `truncated: true`, başka bir sayfa olduğu anlamına gelir. Sayfada
genel bir ad, eşleşmeyen bir rota veya genel bir işlem varsa `next_action`,
`sdk_configuration` hedefiyle `improve_trace_naming` olur.
`pagination=cursor` olmadan rota, izlerden oluşan yalın bir dizi döndürür ve
`naming_quality` döndürmez.
`next_cursor`, `time` ve `trace_id` değerlerini tutar. Bunları `cursor_time`
ve `cursor_trace_id` olarak gönderin.
`GET /api/telemetry/traces/{trace_id}`, tek bir izin span'lerini döndürür.
`GET /api/telemetry/traces/{trace_id}/summary`; kök span'i, hata span'lerini,
hizmetleri, süreyi ve en yavaş yolu ham span öznitelikleri olmadan döndürür.
Özet rotasındaki `404`, kapsamın tamamıyla eşleşen bir iz olmadığı anlamına
gelir. Filtreleri kaldırıp yeniden denemeyin.
[İz span'leri ve özet yanıtları](#trace-spans-and-summary-responses)
bölümüne bakın.
### Boş listeler ve eksik kayıtlar
Bir liste okumasında hiç eşleşme olmayabilir. Ayrıntı okumasının sözleşmesi
farklıdır:
| İstek | Başarı | Okunabilir kayıt yok |
| - | - | - |
| `GET /api/logs/{log_id}` | Tek bir [log](#log-response) ile `200` | `code: not_found` ile `404` |
| `GET /api/telemetry/issues/{issue_id}` | Tek bir [sorun](#issue-response) ile `200` | `code: not_found` ile `404` |
| `GET /api/telemetry/issues/{issue_id}/events` | Oluşumlarla `200` | İlk sayfada `code: not_found` ile `404` |
| `GET /api/telemetry/traces/{trace_id}` | Span'lerle `200` | `[]` ile `200` |
| `GET /api/telemetry/traces/{trace_id}/summary` | Tek bir özetle `200` | `code: not_found` ile `404` |
Eksik bir log şu `404` yanıtını döndürür:
```json theme={null}
{
"error": "log not found",
"code": "not_found",
"next": "check the resource id or filters and retry",
"next_action": {
"code": "check_resource",
"target": "resource"
}
}
```
Eksik bir sorun `"error": "issue not found"` kullanır. Eksik bir iz özeti
`"error": "trace not found"` kullanır. Bilinmeyen bir kimlik ile hesabın
okuyamadığı bir kimlik aynı yanıtı döndürür.
Hesabın okuyamadığı tek bir `project_id` içeren liste, boş bir listeyle `200`
döndürür. Veri olmadığını bildirmeden önce proje kimliğini kontrol edin.
### Reddedilen proje seçimleri
Log, sorun, aksiyon, metrik, sürüm ve iz listeleri `project_id` ile tek bir
proje veya `project_ids` ile 2 ila 50 proje kabul eder. Log özniteliği
kataloğu aynı seçicileri kabul eder. Sorun oluşum geçmişi bunları kabul etmez.
Hem `project_id` hem `project_ids` içeren bir istek `422` döndürür:
```json theme={null}
{
"error": "project_id and project_ids are mutually exclusive",
"code": "validation_failed",
"next": "use project_id for one project, project_ids=uuid,uuid for two to fifty projects, or omit both for all readable projects",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
Geçersiz bir UUID, tekrarlanan bir kimlik ya da 2'den az veya 50'den fazla
kimlik içeren `project_ids` de `code: validation_failed` ile `422` döndürür.
Hesap bir `project_ids` kümesindeki projelerden birini okuyamıyorsa isteğin
tamamı `404` döndürür. Diğer projeleri kısmi sonuç olarak döndürmez:
```json theme={null}
{
"error": "project selection not found",
"code": "not_found",
"next": "refresh readable projects and retry with only project IDs you can read",
"next_action": {
"code": "check_resource",
"target": "resource"
}
}
```
Boş bir liste veya sıfır sayı yerine hatayı gösterin. Proje listesini yeniden
okuyun. Bir projeyi sessizce çıkarmayın ve tüm projelerde yeniden denemeyin.
MCP bağlantısı gibi devredilmiş bir kimlik bilgisi, bağlantısının dışındaki bir
proje için `code: forbidden` ile `403` döndürür.
[Proje kapsamı](/tr/reference/telemetry-api-filters#project-scope) bölümüne
bakın.
### Cursor hataları
Loglar, sorunlar, aksiyonlar, metrikler ve sorun oluşumları `cursor_time` ve
`cursor_id` kullanır. Reddedilen bir cursor `code: validation_failed` ile
`422` döndürür. Bu hatalar listenin boş olduğu anlamına gelmez.
| İstek | `error` |
| - | - |
| 2 cursor alanından yalnızca 1'iyle `pagination=cursor` | `cursor_time and cursor_id must be sent together` |
| RFC3339 zaman damgası olmayan `cursor_time` | `cursor_time must be an RFC3339 timestamp` |
| `pagination=cursor` olmadan veya başka bir `pagination` değeriyle cursor alanları | `pagination must be cursor when cursor pagination is requested` |
Örneğin:
```json theme={null}
{
"error": "cursor_time and cursor_id must be sent together",
"code": "validation_failed",
"next": "send pagination=cursor alone for the first page, then send cursor_time and cursor_id together from next_cursor",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
Önceki sayfadaki `next_cursor` nesnesini eksiksiz kopyalayın. `cursor_time`
yerine şimdiki zamanı koymayın. Cursor'ı kaybettiyseniz `pagination=cursor` ve
asıl filtrelerle yeniden başlayın. Bilinmeyen bir sorgu anahtarı veya yanlış
türde bir değer `"error": "invalid query parameters"` ile `422` döndürür.
### Sürüm cursor yanıtları
Sürüm cursor'ının 5 alanı vardır. Eşleşme olmayan başarılı bir istek `200`
döndürür:
```json theme={null}
{
"releases": [],
"next_cursor": null
}
```
`next_cursor` değeri `null` değilse 5 değerin tamamını sonraki istekte
gönderin:
| `next_cursor` alanı | Sorgu parametresi |
| - | - |
| `time` | `cursor_time` |
| `project_id` | `cursor_project_id` |
| `release` | `cursor_release` |
| `environment` | `cursor_environment` |
| `service_name` | `cursor_service_name` |
`cursor_project_id` bir konumu işaretler. `project_id` veya `project_ids`
yerine geçmez. Asıl proje ve filtre parametrelerini koruyun. Her değeri URL
kodlamasıyla gönderin.
`pagination=cursor` ile eksik bir cursor ya da boş bir sürüm, ortam veya hizmet
değeri `"error": "all release cursor fields must be sent together"` ile `422`
döndürür. Geçersiz bir `cursor_time` ve eksik bir `pagination=cursor`,
[diğer cursor'larla](#cursor-errors) aynı hataları döndürür.
### İz keşfi hataları
Bu hatalar `GET /api/telemetry/traces` için geçerlidir. Her biri
`code: validation_failed` ile `422` döndürür. Reddedilen bir istek boş bir
sonuç değildir.
| İstek | `error` |
| - | - |
| `error` veya `ok` dışında bir `status` | `trace status must be error or ok` |
| `0` altında bir `min_duration_ms` | `minimum trace duration must not be negative` |
| Yalnızca 1 cursor alanı veya boş bir `cursor_trace_id` | `cursor_time and cursor_trace_id must be sent together` |
| RFC3339 zaman damgası olmayan `cursor_time` | `cursor_time must be an RFC3339 timestamp` |
| `pagination=cursor` olmadan cursor alanları | `pagination must be cursor when cursor pagination is requested` |
İki iz durumunu birlikte almak için `status` göndermeyin. Sonraki sayfa için
`next_cursor.time` değerini `cursor_time` alanına, `next_cursor.trace_id`
değerini `cursor_trace_id` alanına kopyalayın. İz sayfası için `cursor_id`
göndermeyin. [İz filtreleri](/tr/reference/telemetry-api-filters#trace-filters)
bölümüne bakın.
### Sorun oluşum geçmişi
`GET /api/telemetry/issues/{issue_id}/events`, gruplanmış tek bir sorunun
oluşumlarını okur. Bir hesap bearer tokenı ve gruplanmış sorun kimliğini
kullanın. Rota yalnızca `pagination`, `cursor_time`, `cursor_id` ve `limit`
kabul eder. Proje, zaman, sürüm, ortam veya önem düzeyi filtrelerini kabul
etmez.
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/events" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "pagination=cursor" \
--data-urlencode "limit=1"
```
Tek bir oluşum ve devam cursor'ı içeren ilk sayfa:
```json theme={null}
{
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"events": [
{
"id": "db619770-1f7c-4bd5-8310-9f171df8af47",
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"severity": "error",
"title": "Checkout failed",
"message": "Checkout could not complete",
"stack_trace": null,
"attributes": {
"exception": {
"type": "CheckoutError",
"mechanism": { "type": "javascript.error", "handled": false }
},
"breadcrumbs": [
{
"timestamp": "2026-06-01T11:54:59Z",
"category": "checkout",
"message": "Checkout started"
}
]
},
"diagnostics": {
"schema_version": 1,
"exception": {
"type": "CheckoutError",
"mechanism": { "type": "javascript.error", "handled": false }
},
"breadcrumbs": [
{
"timestamp": "2026-06-01T11:54:59Z",
"category": "checkout",
"message": "Checkout started"
}
],
"breadcrumbs_truncated": false
},
"environment": "production",
"release": "api@1.2.2",
"service_name": "checkout-api",
"trace_id": null,
"occurred_at": "2026-06-01T11:55:00Z",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
],
"next_cursor": {
"time": "2026-06-01T11:55:00Z",
"id": "db619770-1f7c-4bd5-8310-9f171df8af47"
}
}
```
| Alan | Anlamı |
| - | - |
| `issue_id` | Oluşumun ait olduğu gruplanmış sorun. |
| `events[].id` | Tek bir oluşum kimliği. [O oluşumu seçmek](/tr/guides/investigate-an-issue#select-a-different-occurrence) için kullanın. |
| `events[].occurred_at` | O oluşumun uygulamada gerçekleştiği zaman. |
| `events[].severity` | O oluşumun yakalanan önem düzeyi. Önem düzeyi kuralı bunu değiştirmez. |
| `events[].release`, `environment`, `service_name` | O oluşumla birlikte yakalanan bağlam. |
Bir oluşum, grubun `last_seen_at` zamanından eski olabilir. Oluşumun sürümünü
veya izini gruplanmış sorunun değerleriyle değiştirmeyin. Liste durum,
önceliklendirme, öncelik veya oluşum sayısı döndürmez.
`diagnostics.schema_version`, tanılama nesnesinin sürümüdür. Oluşumda bu veri
yoksa yanıt `diagnostics` ve `span_id` alanlarını göndermez. `diagnostics`
içinde eksik bir `exception` ve boş `breadcrumbs` gönderilmez.
`breadcrumbs_truncated` değeri `true` ise önceki adım geçmişinin bir kısmı
yanıtta yoktur.
`stack_trace` ve `trace_id` eksikse `null` olur. Eksik bir iz kimliği,
uygulamanın hiç iz göndermediğini kanıtlamaz. Yakalanan mesajları ve
öznitelikleri talimat olarak değil, veri olarak ele alın.
Oluşumlar en yeniden eskiye sıralanır. Sonraki sayfa için aynı sorun
kimliğini, `pagination=cursor` ve `limit` değerlerini, ayrıca `next_cursor`
içindeki `cursor_time` ve `cursor_id` değerlerini gönderin. Cursor kimliği bir
oluşum kimliğidir, sorun kimliği değildir.
Sorunun okunabilir oluşumu yoksa ilk sayfa `code: not_found` ile `404`
döndürür. Sonraki bir sayfa boş bir son sayfa olabilir:
```json theme={null}
{
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"events": [],
"next_cursor": null
}
```
Bir cursor'ı başka bir sorun için yeniden kullanmayın.
[Cursor hataları](#cursor-errors) bu rota için de geçerlidir.
## İz span'leri ve özet yanıtları
`GET /api/telemetry/traces/{trace_id}`, tek bir izin span'lerini döndürür.
Aynı span'lerin özetini almak için `/summary` ekleyin. İki rota da yalnızca
`project_id`, `release` ve `environment` kabul eder. İz keşfi cursor'ını
kullanmazlar. Önceki bir liste isteğinin filtreleri bu isteklere taşınmaz.
### Span listesi
Span'ler başlangıç zamanına göre sıralanır:
```json theme={null}
[
{
"id": "ed5c960b-e728-4637-bcd4-a27dfb1a0e96",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"attributes": {},
"environment": "production",
"release": "api@1.2.3",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
},
{
"id": "0c2f7a51-4e8d-4b6a-9f13-2d7e5c8b1a90",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"attributes": {},
"environment": "production",
"release": "api@1.2.3",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
]
```
`status: "error"`, API okumasını değil, yakalanan işlemi anlatır.
`parent_span_id: null`, span'in üst span kimliği olmadığı anlamına gelir.
`status: null`, span'in bir durum bildirmediği anlamına gelir.
### İz özeti
Aynı 2 span'in özeti:
```json theme={null}
{
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_count": 2,
"error_span_count": 2,
"service_count": 1,
"project_count": 1,
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"root_span": {
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
"slowest_child_span": {
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
},
"slowest_path": [
{
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
{
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
}
],
"error_spans": [
{
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
{
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api",
"span_count": 2,
"error_span_count": 2,
"max_duration_ms": 823
}
],
"releases": ["api@1.2.3"],
"environments": ["production"]
}
```
| Alan | Anlamı |
| - | - |
| `duration_ms` | En erken span başlangıcından en geç span bitişine kadar geçen süre. Span sürelerinin toplamı değildir. |
| `root_span` | Üst span'i izde olmayan en erken span. Bir başlangıç noktasıdır, kanıtlanmış bir neden değildir. |
| `slowest_child_span` | Üst span kimliği olan en uzun span veya `null`. |
| `slowest_path` | Kökten `slowest_child_span` değerine kadar bilinen üst span zinciri. `slowest_child_span` değeri `null` ise `[]` olur. |
| `error_spans` | En uzun hata span'leri, en fazla 5 tane. `error_span_count` daha büyük olabilir. |
İki rota da cursor veya kısaltma alanı döndürmez. Yanıtta olmayan bir
`truncated` değeri eklemeyin.
### Eşleşen span yok
İz kimliği ve kapsamla eşleşen span yoksa span listesi `[]` ile `200`
döndürür. Özet, `"error": "trace not found"` ve `code: not_found` ile `404`
döndürür. İz kimliğini ve kapsamı kontrol edin. Sonuç görünsün diye
filtreleri kaldırmayın. İki sonuç da uygulamanın telemetri göndermediğini
kanıtlamaz.
## Canlı olay yanıt biçimi
Canlı akış yeni olayları gönderir. İstemcinin bağlantısı kopukken kaçırdığı
olayları yeniden göndermez. Mevcut kayıtları okumak için liste rotalarını
kullanın.
### Bilet oluşturun
Bir hesap bearer tokenıyla `POST /api/feed/ticket` gönderin. İsteğin gövdesi
yoktur.
```bash theme={null}
curl --request POST "https://api.logbrew.co/api/feed/ticket" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"
```
`200 OK` yanıtı bileti `ticket` alanında içerir:
```json theme={null}
{
"ticket": "",
"expires_in_seconds": 60,
"next": "connect with GET /api/feed/live?ticket= before the ticket expires",
"next_action": {
"code": "connect_live_feed",
"target": "live_feed"
}
}
```
Bilet kısa ömürlü bir kimlik bilgisidir. Onu loglamayın veya bir agent
promptuna koymayın. Bağlantıyı `expires_in_seconds` dolmadan açın. Bu süre,
bağlantının ne zamana kadar başlayabileceğini sınırlar. Bağlantının ne kadar
açık kalacağını sınırlamaz.
`401`, hesap girişinin geçerli olmadığı anlamına gelir. Bilet istemeden önce
yeniden giriş yapın. `POST` dışında bir yöntem `code: method_not_allowed` ile
`405` döndürür.
### Bağlantıyı açın
Bir WebSocket istemcisini
`wss://api.logbrew.co/api/feed/live?ticket=` adresine bağlayın.
Bileti URL kodlamasıyla gönderin. URL'ye hesap bearer tokenı veya alım bearer
tokenı koymayın. `401`, biletin veya hesap girişinin geçerli olmadığı anlamına
gelir. Yeniden giriş yaptıktan sonra yeni bir bilet oluşturun.
| Yanıt | Neden | Sonraki adım |
| - | - | - |
| `"error": "feed ticket is required"` ile `422` | `ticket` sorgu değeri eksik veya boş. | Bir bilet oluşturun ve onunla bağlanın. |
| `code: unauthorized` ile `401` | Biletin süresi dolmuş veya bilet geçerli değil. | Yeni bir bilet oluşturun. Aynı biletle yeniden denemeyin. |
| `code: invalid_websocket_upgrade` | İstek geçerli bir WebSocket yükseltmesi değil. | Bir WebSocket istemcisi kullanın. |
| `code: method_not_allowed` ile `405` | İstek `GET` kullanmıyor. | Bağlantı için `GET` kullanın. |
Bir hatadan sonra yeniden bağlanmadan önce bekleyin. Ara vermeden döngü
içinde yeniden bağlanmayın.
### Mesajları okuyun
Her mesaj bir `{ "type": "...", "data": ... }` zarfıdır. `data` alanını
ayrıştırmadan önce `type` alanını okuyun. İstemcinin desteklemediği türleri
atlayın.
| Olay türü | Veri yükü |
| - | - |
| `native_log` | [Log yanıtı](#log-response) yapısında log verisi. |
| `native_issue` | Sürüm 1 [sorun yanıtı](#issue-response) yapısında gruplanmış sorun verisi. |
| `native_trace_span` | [Span listesi](#span-list) öğesi yapısında tek bir span. |
| `native_action` | [Aksiyon yanıtı](#action-response) yapısında ürün aksiyonu verisi. |
| `project_created`, `project_updated`, `project_catalog_changed` | Proje verisi. Değiştiğinde proje listesini yeniden okuyun. |
| `usage_updated`, `usage_limit_warning`, `usage_limit_blocked` | [Hesap kullanımı](/tr/reference/account-api#account-usage) yapısında hesap kullanımı. |
```json theme={null}
{
"type": "native_log",
"data": {
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"level": "warning",
"severity": "warning",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": false
},
"source": "runtime",
"message": "checkout retry scheduled",
"attributes": { "route": "/checkout" },
"occurred_at": "2026-06-01T12:00:00Z",
"environment": "production",
"release": "api@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
}
```
`native_issue` olayı sorun yanıtı sürüm 1'i kullanır: arşivlenmiş bir sorun
`ignored` gösterir ve olayda öncelik yoktur. Metrikler ve sürümler canlı olay
türü değildir. Onları kendi liste rotalarıyla okuyun. Bilet bir proje seçmez.
Bir olayı proje görünümünde göstermeden önce `project_id` değerini kontrol
edin. `logbrew watch --json` bu akışı kullanır.
[CLI referansı](/tr/reference/cli) sayfasına bakın.
### Kapanan bağlantıyı ele alın
| Kapanış kodu | Neden | Sonraki adım |
| - | - | - |
| `1013` | `live feed fell behind; reconnect to resync` | Bekleyin, ardından yeni bir biletle yeniden bağlanın. Kaçırdığınız kayıtları almak için liste rotalarını yeniden okuyun. |
| `1008` | `live feed access changed; sign in again` | Yeniden bağlanmayı durdurun. Yeni bir bilet oluşturmadan önce yeniden giriş yapın. |
Diğer bağlantı kopmalarında LogBrew nedeni olmayabilir. Yeniden bağlandıktan
sonra liste rotalarını yeniden okuyun ve kayıtları kimliğe göre eşleştirin.
## Sorun durumu yanıt örnekleri
`{ "status": "resolved" }` ile `PATCH /api/telemetry/issues/{issue_id}`,
güncellenen gruplanmış sorunla birlikte `200 OK` döndürür. Yapı
[sorun yanıtı](#issue-response) ile aynıdır. Sürümü `response_version` sorgu
anahtarı seçer. Yanıt bir başarı işareti döndürmez.
Gövde `status`, `priority` ve `assignee` alanlarından en az 1'ini ayarlar.
`status`; `unresolved`, `resolved` veya `archived` kabul eder. `ignored`,
`archived` için eski bir addır.
[Tek bir sorunu güncelleyin](/tr/reference/telemetry-api#update-one-issue)
bölümüne bakın.
Başarıyı göstermeden önce dönen `id`, `status` ve `priority` değerlerini
kontrol edin. Sonucu gönderdiğiniz değerlerden oluşturmayın. Durum
değişikliği oluşumları silmez, `first_seen_at` ve `last_seen_at` değerlerini
değiştirmez. `severity` değerini veya bir önem düzeyi kuralını da değiştirmez.
Reddedilen bir değişiklik `code: validation_failed` ile `422` döndürür:
```json theme={null}
{
"error": "issue status must be unresolved, resolved, or archived",
"code": "validation_failed",
"next": "use status=unresolved, status=resolved, or status=archived",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
| Sonuç | Neden |
| - | - |
| `422`, `issue update requires status, priority, or assignee` | Gövdede 3 alandan hiçbiri yok. |
| `422`, `issue priority must be high, medium, or low` | Öncelik değeri desteklenmiyor. |
| `422`, `issue assignee must be me, none, a user ID, or team:` | Sorumlu değeri desteklenmiyor. |
| `422`, `issue assignee cannot read this project` | Sorumlunun projeye erişimi yok. LogBrew hiçbir şeyi değiştirmez. |
| `422`, `issue assignee team is not a team of this project's organization` | Ekip, projenin organizasyonunda değil. LogBrew hiçbir şeyi değiştirmez. |
| `code: forbidden` ile `403` | Hesap projedeki sorunları yönetemiyor. |
| `code: not_found` ile `404` | Hesap sorunu okuyamıyor veya sorun yok. |
İstenen değere zaten sahip olan bir alan değişmez. Zaman aşımından veya
kaybolan bir yanıttan sonra aynı isteği yeniden gönderin ya da önce sorunu
okuyun. Güncel durumu okumadan farklı bir değişiklik göndermeyin.
[Yazma işlemleri](/tr/reference/api-errors#writes) bölümüne bakın.
`POST /api/telemetry/issues/bulk`, istenen her sorun kimliği için 1 sonuçla
`200 OK` döndürür. Sonuçlar istekteki sırayla gelir. Bulunan her sorun sürüm
3 yapısını kullanır. `not_found` sonucunda `issue: null` olur:
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"results": [
{
"issue_id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"outcome": "updated",
"issue": {
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "archived",
"priority": "high",
"priority_source": "derived",
"assignee": null
}
},
{
"issue_id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"outcome": "not_found",
"issue": null
}
]
}
```
Bu örnek sorun alanlarının yalnızca bir kısmını gösterir. `outcome` değeri
`updated`, `unchanged` veya `not_found` olur. Tekrarlanan bir istek
`unchanged` döndürür ve hiçbir şeyi değiştirmez.
[Sorunları toplu güncelleyin](/tr/reference/telemetry-api#update-issues-in-bulk)
bölümüne bakın.
Toplu istek şu durumlarda bütünüyle başarısız olur:
| Sonuç | Neden |
| - | - |
| `422`, `issue_ids must name 1 to 100 issues` | Liste boş veya 100'den fazla kimlik içeriyor. |
| `422`, `issue_ids must not contain duplicates` | Bir kimlik birden fazla kez geçiyor. |
| `code: invalid_json` ile `422` | Gövdede bilinmeyen bir alan var. |
| `code: forbidden` ile `403` | Hesap projedeki sorunları yönetemiyor. |
| `404`, `project not found` | Hesap projeyi okuyamıyor. |
## Analiz isteği kapsamı
Analiz rotaları, metrik serisi rotası ve sinyal hacmi rotası tek bir projeyi
ve tek bir zaman aralığını okur. Her istek `project_id` ve `since` gerektirir.
`since`, `24h` veya `7d` gibi kısa bir süre ya da bir RFC3339 zaman damgası
kabul eder. `until` bir RFC3339 zaman damgası kabul eder. Varsayılan değeri
istek zamanıdır. Aralık `since` değerini içerir, `until` değerini içermez ve
31 günü aşamaz.
`service_name`, `release` ve `environment` isteğe bağlı tam eşleşme
filtreleridir. LogBrew boşlukları kırptıktan sonra her değer 1 ile 256
karakter arasında olmalıdır. Segment karşılaştırma rotası bu filtreleri en üst
düzeye değil, her segmentin içine koyar.
Hesap projeyi okuyamıyorsa bu rotalar sıfır sayılarla `200 OK` döndürür.
`404` döndürmezler. Boş bir sonuç proje erişimini doğrulamaz. `project_id`
değerini hesabın okuyabildiği projelerle karşılaştırın. Projeyi içermeyen bir
MCP bağlantısı üzerinden yapılan istek `403` ve `forbidden` döndürür.
| Rota | `response_version` değerleri | Varsayılan |
| - | - | - |
| `GET /api/telemetry/analytics/overview` | `1`, `2` veya `3` | `1` |
| `GET /api/telemetry/analytics/properties` | `1` veya `2` | `1` |
| `POST /api/telemetry/analytics/segments/compare` | `1` veya `2` | `1` |
| `POST /api/telemetry/analytics/retention` | `1` veya `2` | `1` |
| `POST /api/telemetry/analytics/lifecycle` | `1` veya `2` | `1` |
| `POST /api/telemetry/analytics/funnel` | Kabul edilmez | Şema `1` |
| `POST /api/telemetry/analytics/paths` | Kabul edilmez | Şema `1` |
| `GET /api/telemetry/metrics/series` | Kabul edilmez | Şema `1` |
| `GET /api/telemetry/summary/volume` | `1` | `1` |
Her yanıt `schema_version`, `query` ve `purpose` ile başlar. `query`, uygulanan
kapsamı geri yansıtır. Göndermediğiniz bir filtreyi içermez. `purpose`,
rotanın neyi yanıtladığını anlatan düz metindir.
Paydası sıfır olan bir oran gönderilmez. Gönderilmeyen oran `0` veya `null`
değildir. Bir orana güvenmeden önce `coverage` alanını okuyun.
### Ortak kapsam hataları
Bu hatalar HTTP `422` ve `validation_failed` kullanır:
| Neden | `error` |
| - | - |
| `project_id` yok | `product analytics project_id is required` |
| `since` yok | `product analytics since is required` |
| `since` bir süre veya RFC3339 zaman damgası değil | `invalid since value` |
| `until` bir RFC3339 zaman damgası değil | `product analytics until must be an RFC3339 timestamp` |
| `since`, `until` değerinden önce değil | `product analytics since must be earlier than until` |
| Aralık 31 günden uzun | `product analytics range must not exceed 31 days` |
| Boş bir filtre veya 256 karakterden uzun bir filtre | `product analytics context filters must be non-empty and at most 256 characters` |
Örneğin `project_id` içermeyen bir istek şunu döndürür:
```json theme={null}
{
"error": "product analytics project_id is required",
"code": "validation_failed",
"next": "choose one owned project and send its project_id",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Metrik serisi ve sinyal hacmi rotaları aynı kapsam kurallarını kendi `error`
metinleriyle kullanır. Bu hatalar aşağıda kendi bölümlerinde listelenir.
Bilinmeyen bir sorgu anahtarı
[geçersiz sorgu parametreleri](/tr/reference/api-errors#invalid-query-parameters)
yanıtıyla `422` döndürür. Bilinmeyen bir JSON alanı, eksik bir zorunlu JSON
alanı veya desteklenmeyen bir enum değeri `invalid_json` döndürür.
[Geçersiz JSON](/tr/reference/api-errors#invalid-json) bölümüne bakın. Yanlış
HTTP yöntemiyle yapılan istek `405` ve `method_not_allowed` döndürür. `next`
metni desteklenen yöntemi ve alanları adlandırır.
[Desteklenmeyen yöntem](/tr/reference/api-errors#unsupported-method)
bölümüne bakın.
## Ürün analizleri genel bakış yanıtı
`GET /api/telemetry/analytics/overview`, tek bir projedeki etkinliği gösterir:
aksiyon hacmi, kullanıcılar, oturumlar, bir zaman serisi, en sık aksiyonlar ve
sınıflandırılmış sayfa görüntülemeleri, ekran görüntülemeleri ve etkileşimler.
Diğer analiz rotaları için tam olay adlarını bulmak üzere bu rotayı kullanın.
`response_version=3` gönderin. Sürüm 1 ve 2 aynı sayıları döndürür, ancak
`estimation.method` alanında eski bir değer döndürür. Sürüm 1, tanımlı kullanıcıları
sayarken özne türünü kontrol etmez. Sürüm 2 ve 3 yalnızca `user` türündeki
özneleri sayar. Anonim özne sayılarını ve `subject_coverage` alanını da
ekler.
Bu istek bir saati beş dakikalık zaman dilimleriyle okur ve her en sık
listesinde iki satır döndürür:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "since=2026-06-01T11:00:00Z" \
--data-urlencode "until=2026-06-01T12:00:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "top_limit=2" \
--data-urlencode "response_version=3"
```
### Başarılı genel bakış
Bu yapay sonuçta projenin on iki zaman diliminden ikisinde 120 aksiyonu
vardır. Yirmi aksiyon anonim öznelerden gelir. Her aksiyonun bir oturum
kimliği vardır. Aksiyonların yarısında iz kimliği vardır.
```json theme={null}
{
"schema_version": 3,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "5m",
"interval_seconds": 300,
"top_limit": 2
},
"purpose": "Shows what people do in one project through action volume, active identified users, separately labeled anonymous subjects, explicit sessions, activity over time, top actions, and versioned page-view, screen-view, interaction, surface, and exact event-name breakdowns. Exact classified event names can be used as ordered funnel steps. It never infers people from anonymous events or relabels arbitrary unclassified telemetry as product behavior.",
"analysis_level": "user_and_session",
"summary": {
"actions": 120,
"active_identified_users": 18,
"active_anonymous_subjects": 7,
"sessions": 24,
"distinct_action_names": 3,
"actions_per_identified_user": 5.555555555555555,
"actions_per_session": 5.0
},
"coverage": {
"identified_actions": 100,
"anonymous_actions": 20,
"subject_coverage": {
"index_version": 1,
"identified_user_events": 100,
"anonymous_subject_events": 20,
"legacy_unknown_kind_events": 0,
"missing_subject_events": 0,
"historical_unindexed_events": 0
},
"sessionized_actions": 120,
"traced_actions": 60,
"identification_rate": 0.8333333333333334,
"sessionization_rate": 1.0,
"trace_link_rate": 0.5,
"expected_buckets": 12,
"returned_points": 2,
"returned_top_actions": 2,
"top_actions_truncated": true,
"first_seen_at": "2026-06-01T11:00:10Z",
"last_seen_at": "2026-06-01T11:09:50Z",
"limitations": [
"Typed anonymous subjects are counted separately and never contribute to active identified-user counts.",
"Actions without a trace ID cannot link product behavior directly to trace investigation."
]
},
"estimation": {
"unique_counts_are_approximate": true,
"method": "approximate_distinct",
"description": "Active identified-user, anonymous-subject, session, distinct action-name, distinct surface, and distinct exact event-name counts are approximate distinct counts. Event totals and capture-coverage counts are exact within the selected, fully evaluated query window."
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T11:05:00Z",
"actions": 50,
"active_identified_users": 8,
"sessions": 10,
"identified_actions": 40,
"sessionized_actions": 50,
"traced_actions": 25
},
{
"bucket_start": "2026-06-01T11:05:00Z",
"bucket_end": "2026-06-01T11:10:00Z",
"actions": 70,
"active_identified_users": 12,
"sessions": 14,
"identified_actions": 60,
"sessionized_actions": 70,
"traced_actions": 35
}
],
"top_actions": [
{
"name": "checkout_started",
"actions": 50,
"active_identified_users": 12,
"sessions": 14,
"share_of_actions": 0.4166666666666667
},
{
"name": "purchase_completed",
"actions": 40,
"active_identified_users": 9,
"sessions": 10,
"share_of_actions": 0.3333333333333333
}
],
"classified_activity": {
"summary": {
"events": 110,
"page_views": 50,
"screen_views": 20,
"interactions": 40,
"distinct_surfaces": 4,
"distinct_event_names": 5,
"active_identified_users": 17,
"active_anonymous_subjects": 6,
"sessions": 23
},
"coverage": {
"classified_actions": 60,
"unclassified_actions": 60,
"action_classification_rate": 0.5,
"surfaced_events": 110,
"named_events": 110,
"identified_events": 90,
"subject_coverage": {
"index_version": 1,
"identified_user_events": 90,
"anonymous_subject_events": 20,
"legacy_unknown_kind_events": 0,
"missing_subject_events": 0,
"historical_unindexed_events": 0
},
"sessionized_events": 110,
"traced_events": 55,
"surface_rate": 1.0,
"event_name_rate": 1.0,
"identification_rate": 0.8181818181818182,
"sessionization_rate": 1.0,
"trace_link_rate": 0.5,
"expected_buckets": 12,
"returned_points": 2,
"returned_top_surfaces": 2,
"returned_top_events": 2,
"top_surfaces_truncated": true,
"top_events_truncated": true,
"first_seen_at": "2026-06-01T11:00:20Z",
"last_seen_at": "2026-06-01T11:09:40Z",
"limitations": [
"Only events carrying supported version-1 analytics annotations appear in classified activity; arbitrary actions and technical spans are not relabeled.",
"Historical or unannotated actions contribute to the action summary but not to classified screen-view or interaction breakdowns.",
"Classified events with typed anonymous subjects are counted separately and never contribute to identified-user counts.",
"Classified events without a trace ID cannot link product behavior directly to trace investigation."
]
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T11:05:00Z",
"events": 45,
"page_views": 20,
"screen_views": 10,
"interactions": 15
},
{
"bucket_start": "2026-06-01T11:05:00Z",
"bucket_end": "2026-06-01T11:10:00Z",
"events": 65,
"page_views": 30,
"screen_views": 10,
"interactions": 25
}
],
"top_surfaces": [
{
"kind": "page_view",
"surface": "/checkout/:step",
"events": 40,
"active_identified_users": 12,
"sessions": 14,
"share_of_classified_events": 0.36363636363636365
},
{
"kind": "screen_view",
"surface": "Checkout",
"events": 20,
"active_identified_users": 9,
"sessions": 10,
"share_of_classified_events": 0.18181818181818182
}
],
"top_events": [
{
"kind": "page_view",
"event_name": "/checkout/:step",
"events": 40,
"active_identified_users": 12,
"sessions": 14,
"share_of_classified_events": 0.36363636363636365
},
{
"kind": "interaction",
"event_name": "checkout_started",
"events": 30,
"active_identified_users": 10,
"sessions": 12,
"share_of_classified_events": 0.2727272727272727
}
]
},
"next_action": {
"code": "build_product_funnel",
"target": "/api/telemetry/analytics/funnel",
"reason": "Use two through eight exact keys from classified_activity.top_events to measure ordered conversion and drop-off for explicit sessions or opaque identified users."
}
}
```
### Genel bakışı okuyun
Beş `subject_coverage` sayısının toplamı, bulundukları bölümün olay toplamına
eşittir. Yalnızca `identified_user_events` kullanıcılara sayılır.
`anonymous_actions`, `summary.actions` eksi `identified_actions` değeridir.
`series` yalnızca etkinlik olan zaman dilimlerini içerir. `expected_buckets`,
aralıktaki olası zaman dilimi sayısıdır. Grafiğiniz bu kuralı belirtmiyorsa
eksik bir zaman dilimini ölçülmüş sıfır olarak çizmeyin. Zaman dilimleri UTC
aralık sınırlarına hizalanır. Bir zaman diliminin içinde başlayan aralık, o
kısmi zaman dilimini de içerir.
`classified_activity`; sayfa görüntülemelerini, ekran görüntülemelerini ve
etkileşimleri sayar. Ekran görüntülemeleri ve etkileşimler aynı zamanda
aksiyondur. Sayfa görüntülemeleri aksiyon değildir. `summary.actions` değerini
`classified_activity.summary.events` değerine eklemeyin.
`classified_activity.top_events` içindeki `kind` ve `event_name` değerlerini
dönüşüm hunisi adımlarına, elde tutma seçicilerine, yaşam döngüsü
seçicilerine, yol çapalarına ve segment hedeflerine kopyalayın.
`top_events_truncated` alanındaki `true` değeri, daha az görülen adlar olduğu
anlamına gelir. Daha fazlasını görmek için `top_limit` değerini en fazla 20'ye
kadar artırın.
`analysis_level` değeri `no_data`, `event_only`, `user_level` veya
`user_and_session` olur. Projede aksiyon ve sınıflandırılmış olay yoksa
`next_action.code` değeri `capture_product_activity` olur.
[Ürün analizleri](/tr/concepts/product-analytics#use-the-analytics-api)
sayfasına bakın.
### Genel bakış hataları
Genel bakış, [ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu
değerler için `422` ve `validation_failed` döndürür:
| Değer | `error` |
| - | - |
| `1`, `2` veya `3` dışında bir `response_version` | `product analytics response_version must be 1, 2, or 3` |
| `1` ile `20` dışında bir `top_limit` | `product analytics top_limit must be between 1 and 20` |
| `auto`, `1m`, `5m`, `15m`, `1h`, `6h` veya `1d` dışında bir `interval` | `product analytics interval is not supported` |
| 500'den fazla zaman dilimi gerektiren açık bir `interval` | `product analytics interval would exceed 500 buckets` |
Varsayılan `interval` değeri `auto` olur. En fazla 300 zaman dilimi gerektiren
en küçük aralığı seçer. Varsayılan `top_limit` değeri `10` olur.
## Sıralı dönüşüm hunisi yanıtı
`POST /api/telemetry/analytics/funnel`, 2 ila 8 adım boyunca sıralı
tamamlanmayı ölçer. Her `kind` ve `event_name` değerini genel bakıştaki
`classified_activity.top_events` içinden tam olarak kopyalayın. Benzer bir
aksiyon adı eşleşme sayılmaz. Bu istek gövdesi, `/pricing` sayfasını
görüntüleyip ardından bir saat içinde kaydı tamamlayan oturumları sayar:
```json theme={null}
{
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"since": "2026-08-01T00:00:00Z",
"until": "2026-08-02T00:00:00Z",
"environment": "production",
"analysis_unit": "session",
"conversion_window_seconds": 3600,
"steps": [
{ "kind": "page_view", "event_name": "/pricing" },
{ "kind": "interaction", "event_name": "signup_completed" }
]
}
```
`analysis_unit` değeri `session` veya `identified_user` olur. Varsayılan
`session` olur. Adım `kind` değeri `page_view`, `screen_view` veya
`interaction` olur. Dönüşüm hunisi rotası `response_version` kabul etmez.
### Başarılı dönüşüm hunisi
`200 OK` yanıtı:
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"since": "2026-08-01T00:00:00Z",
"until": "2026-08-02T00:00:00Z",
"environment": "production",
"analysis_unit": "session",
"conversion_window_seconds": 3600
},
"purpose": "Shows where explicit sessions or typed opaque user subjects enter, progress, and drop off across two through eight versioned page-view, screen-view, or interaction events. Steps must occur in order with strictly increasing timestamps inside the selected conversion window; raw session and subject identifiers are never returned.",
"summary": {
"candidate_units": 60,
"entered_units": 50,
"completed_units": 15,
"entry_rate": 0.8333333333333334,
"overall_conversion_rate": 0.3
},
"coverage": {
"classified_events": 200,
"named_events": 180,
"unnamed_events": 20,
"unit_identified_events": 160,
"selected_step_events": 120,
"usable_selected_step_events": 100,
"excluded_selected_step_events": 20,
"event_name_rate": 0.9,
"selected_unit_coverage_rate": 0.8333333333333334,
"limitations": [
"Only supported version-1 classified events with exact derived names participate; arbitrary actions and technical spans are never relabeled.",
"A unit reaches later steps only when timestamps strictly increase and the final match remains inside conversion_window_seconds from its first match.",
"Historical or surface-less classified events without a derived event name cannot match exact funnel steps.",
"Requested-step events without an explicit session ID are excluded from ordered unit counts.",
"Session funnels count visits or app sessions, not unique people; use analysis_unit=identified_user only when typed user-subject coverage is sufficient."
]
},
"steps": [
{
"position": 1,
"kind": "page_view",
"event_name": "/pricing",
"units": 50,
"conversion_from_first": 1.0,
"drop_off_to_next_units": 35,
"drop_off_to_next_rate": 0.7
},
{
"position": 2,
"kind": "interaction",
"event_name": "signup_completed",
"units": 15,
"conversion_from_previous": 0.3,
"conversion_from_first": 0.3
}
],
"next_action": {
"code": "compare_funnel_contexts",
"target": "/api/telemetry/analytics/funnel",
"reason": "Compare the same exact steps across bounded releases, environments, or services to locate material conversion changes."
}
}
```
Oranlar 0 ile 1 arasında kesirlerdir. Bir orana güvenmeden önce `coverage`
alanını okuyun. `selected_unit_coverage_rate`, seçilen adım olaylarından
LogBrew'ün kullanabildiği paydır. Yanıt ham kimlikleri döndürmez.
[Ürün analizleri](/tr/concepts/product-analytics#measure-a-funnel) sayfasına
bakın.
### Dönüşümü ve kapsama oranını okuyun
`entry_rate`, `entered_units` bölü `candidate_units` değeridir: 60'ta 50.
`overall_conversion_rate`, `completed_units` bölü `entered_units` değeridir:
50'de 15, yani %30. 15'in tüm adaylara bölümü değildir. Bu sayılar birimlerin
neden durduğunu açıklamaz.
Kapsama oranı oturumları değil, olayları sayar. Burada 120 olay bir adımla
eşleşir ve bunların 20'sinde oturum kimliği yoktur. Sonuç bu 20 olayı oturum
sayılarının dışında tutar. Bunları başarısız 20 oturum olarak ele almayın.
İlk adımda `conversion_from_previous` yoktur. Son adımda
`drop_off_to_next_units` ve `drop_off_to_next_rate` yoktur.
Bir birim sonraki bir adıma yalnızca adım zamanları kesin olarak artıyorsa
ulaşır. Aynı zaman damgasına sahip olaylar art arda iki adımı karşılayamaz.
Son adım, ilk adımdan sonraki `conversion_window_seconds` içinde
gerçekleşmelidir.
Oturum modu kişileri değil, oturumları sayar. `identified_user` modunu
yalnızca `user` türünde opak bir özne kimliği taşıyan olaylar için kullanın.
Bu mod, dönüşüm süresi içindeki farklı oturumlardan gelen olayları
birleştirebilir. Sonuçları karşılaştırırken aynı birimi ve aynı adımları
koruyun.
Varsayılan `conversion_window_seconds` değeri 24 saat veya aralığın
uzunluğudur; hangisi daha kısaysa o geçerlidir. En büyük değer, tam saniyeye
yukarı yuvarlanmış aralık uzunluğudur.
### Boş dönüşüm hunisi sonuçları
Başarılı boş bir yanıt da istenen adımları sıfır `units` ile listeler. Aday
birim yoksa `summary` alanı `entry_rate` ve `overall_conversion_rate`
içermez. Rota, olay eşleşmedi diye `404` döndürmez.
Nedeni bulmak için `coverage` ve `next_action` alanlarını okuyun:
| `next_action.code` | Neden |
| - | - |
| `capture_product_activity` | Kapsamda sınıflandırılmış olay yok. |
| `choose_captured_funnel_steps` | İstenen bir adımla eşleşen olay yok. |
| `sessionize_product_activity` | Adım olayları var, ancak hiçbirinde oturum kimliği yok. |
| `identify_product_users` | Adım olayları var, ancak hiçbirinde `user` türünde özne yok. |
| `verify_funnel_entry` | 1. adımda hiçbir birim girmedi. |
| `investigate_funnel_drop_off` | Birimler girdi, ancak hiçbir birim tüm adımları tamamlamadı. |
| `compare_funnel_contexts` | En az bir birim dönüşüm hunisini tamamladı. |
### Reddedilen dönüşüm hunisi istekleri
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu istekler `422`
ve `validation_failed` döndürür. 2'den az veya 8'den fazla adım:
```json theme={null}
{
"error": "product analytics funnel requires two through eight ordered steps",
"code": "validation_failed",
"next": "send a steps array containing 2 through 8 exact classified event selectors",
"next_action": { "code": "fix_request", "target": "request" }
}
```
`0` olan veya aralık uzunluğunu aşan bir `conversion_window_seconds`:
```json theme={null}
{
"error": "product analytics funnel conversion window must fit inside the query range",
"code": "validation_failed",
"next": "use conversion_window_seconds from 1 through the selected range length",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Boş, 256 karakterden uzun veya kontrol karakteri içeren bir `event_name`
şunu döndürür:
`product analytics funnel event_name must be non-empty, control-free, and at most 256 characters`.
Bir `interaction` adımı geçerli bir aksiyon adı da olmalıdır. Değilse hata
`product analytics interaction event_name must be a bounded stable action name`
olur.
İsteği yeniden göndermeden önce düzeltin. Sırf boş olmayan bir sonuç almak
için adımları kaldırmayın veya analiz birimini değiştirmeyin.
## Tam olay ve otomatik analiz
Elde tutma ve yaşam döngüsü iki istek yapısı kabul eder. Sorunuza yanıt veren
yapıyı seçmek için `response_version` kullanın:
| Analiz | `response_version` | Olay seçicileri |
| - | - | - |
| Tam olaylar için elde tutma | `1` veya gönderilmez | Hem `start_event` hem `return_event` gönderin. |
| Tek bir tam olay için yaşam döngüsü | `1` veya gönderilmez | `event` gönderin. |
| Otomatik elde tutma veya yaşam döngüsü | `2` | Olay seçicisi göndermeyin. |
Tam seçici `kind` ve `event_name` içerir. `kind` değeri `page_view`,
`screen_view` veya `interaction` olur. `event_name` değerini
`classified_activity.top_events` içinden kopyalayın. Olay adını bir düğme
etiketinden tahmin etmeyin.
İki yapı da yalnızca kullanıcıları sayar: `user` türündeki opak özne
kimlikleri. Anonim özneler ve kullanılabilir özne kimliği olmayan olaylar
kullanıcı olarak sayılmaz. Yanıtlar hiçbir zaman özne kimliği döndürmez.
Sabit aralıklar `hour`, `day`, `week` ve `thirty_day` olur. Bunlar sabit
sürelerdir. `thirty_day` takvim ayı değil, 30 gündür. `interval`
göndermezseniz API 48 saat veya daha kısa bir aralık için `hour`, daha uzun
bir aralık için `day` kullanır.
### Tam olay elde tutma isteği
Bu gövdeyi `POST /api/telemetry/analytics/retention` adresine gönderin. İstek,
kullanıcıların aralıktaki ilk ödemelerinden sonra başka bir ödeme tamamlayıp
tamamlamadığını sorar:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 1,
"interval": "day",
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range",
"start_event": { "kind": "interaction", "event_name": "checkout_completed" },
"return_event": { "kind": "interaction", "event_name": "checkout_completed" }
}
```
Aralıktaki ilk eşleşen başlangıç olayı, her kullanıcının çıkış noktasıdır.
Geri dönüş bu noktadan kesin olarak sonra ve `until` zamanından önce
gerçekleşmelidir. İki seçici aynı olay olabilir.
| Alan | Değerler | Varsayılan |
| - | - | - |
| `interval_count` | `1` ile `31` arasında dönem | `10` |
| `mode` | `return_on`, her tam dönemin içindeki geri dönüşü sayar. `return_on_or_after`, her dönemin başlangıcında veya sonrasında olan geri dönüşü sayar. | `return_on` |
| `cohort_mode` | `first_in_range` | `first_in_range` |
### Başarılı tam olay elde tutma
Bu yapay örnekte iki kullanıcı ödemeyi tamamlar. İlk kullanıcı 1 Haziran'da
12:00'de ve tekrar 13:00'te ödemeyi tamamlar. İkinci kullanıcı 2 Haziran'da
12:00'de ödemeyi tamamlar. 2 Haziran'da 13:00'te ikinci kullanıcı bir sayfayı
görüntüler, ancak başka bir ödeme tamamlamaz.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"start_event": { "kind": "interaction", "event_name": "checkout_completed" },
"return_event": { "kind": "interaction", "event_name": "checkout_completed" },
"interval": "day",
"interval_seconds": 86400,
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
},
"purpose": "Measures whether typed opaque user subjects return after their first matching start event inside the selected half-open query range. Returns must occur strictly after each subject's anchor. return_on measures one fixed subject-relative period; return_on_or_after measures from that period's threshold through the exclusive query upper bound. Eligibility-aware denominators prevent immature subjects from being reported as churned, cohorts are fixed buckets aligned to since, and raw subject identifiers are never returned.",
"summary": {
"cohort_subjects": 2,
"subjects_returned_after_start": 1,
"return_rate_after_start": 0.5,
"non_empty_cohorts": 2,
"periods_with_eligible_subjects": 1,
"fully_observed_periods": 0
},
"coverage": {
"classified_events": 4,
"named_events": 4,
"unnamed_events": 0,
"identified_events": 4,
"start_events": 3,
"usable_start_events": 3,
"excluded_start_events": 0,
"return_events": 3,
"usable_return_events": 3,
"excluded_return_events": 0,
"event_name_rate": 1.0,
"start_identity_coverage_rate": 1.0,
"return_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"first_in_range anchors each subject at its first matching start inside the selected range; it does not prove that event was the subject's first-ever historical start.",
"Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returns must match the exact selected kind and derived event name, occur strictly after the subject anchor, and remain before the exclusive query upper bound.",
"This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
"return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
]
},
"curve": [
{
"period": 0,
"threshold_seconds": 0,
"window_end_seconds": 86400,
"eligible_subjects": 1,
"retained_subjects": 1,
"weighted_retention_rate": 1.0,
"fully_observed_cohorts": 1,
"fully_observed_cohort_average_rate": 1.0,
"all_subjects_eligible": false
}
],
"cohorts": [
{
"cohort": 0,
"started_at": "2026-06-01T00:00:00Z",
"ended_at": "2026-06-02T00:00:00Z",
"subjects": 1,
"subjects_returned_after_start": 1,
"periods": [
{
"period": 0,
"eligible_subjects": 1,
"retained_subjects": 1,
"retention_rate": 1.0,
"all_subjects_eligible": true
}
]
},
{
"cohort": 1,
"started_at": "2026-06-02T00:00:00Z",
"ended_at": "2026-06-03T00:00:00Z",
"subjects": 1,
"subjects_returned_after_start": 0,
"periods": [
{
"period": 0,
"eligible_subjects": 0,
"retained_subjects": 0,
"all_subjects_eligible": false
}
]
}
],
"next_action": {
"code": "extend_retention_observation_window",
"target": "/api/telemetry/analytics/retention",
"reason": "Move since earlier, until later, or request fewer periods when a fully observed long-term comparison is required."
}
}
```
### Elde tutmayı okuyun
Kapsama oranı sınıflandırılmış dört olayın tamamını sayar, ancak her ödeme
seçicisiyle yalnızca üçü eşleşir. Sayfa görüntüleme geri dönüş sayılmaz. İki
kullanıcıdan biri ödemeyi tekrarlar. Bu yüzden `return_rate_after_start`
değeri `0.5` olur.
Çıkış noktasından sonra tam bir günlük gözlemi olan yalnızca ilk
kullanıcıdır. Bu kullanıcı gün içinde geri döner. Bu yüzden eğrideki oran
`1.0` olur. İkinci kullanıcının yalnızca 12 saatlik gözlemi vardır. Bu
kullanıcı 0. dönem için uygun değildir. Bu yüzden ikinci kohortun hücresinde
`retention_rate` yoktur. Bu kullanıcıyı kaybedilmiş olarak saymayın.
`weighted_retention_rate`, elde tutulan tüm kullanıcıları tüm uygun
kullanıcılara böler. `fully_observed_cohort_average_rate`, her kullanıcısı
uygun olan kohortların oranlarının basit ortalamasıdır. Kohortlar `since`
zamanında başlayan sabit zaman dilimleridir. `cohorts` yalnızca kullanıcısı
olan kohortları içerir.
`mode: "return_on_or_after"` ile eğri `window_end_seconds` içermez.
### Otomatik elde tutma
`response_version: 2` gönderin ve `start_event` veya `return_event`
göndermeyin. Desteklenen her sayfa görüntüleme, ekran görüntüleme ve etkileşim
hem başlangıç hem geri dönüş sayılır. Bu sürüm bir olay kümesi seçer. Bir SDK
yakalama biçimi seçmez.
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 2,
"interval": "day",
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
}
```
Yanıtta tam olay yanıtıyla aynı `summary`, `curve`, `cohorts` ve
`next_action` yapıları bulunur. Bu alıntı değişen alanları gösterir. Bu
örnekte aynı iki kullanıcının üç olayı vardır ve sayfa görüntüleme yoktur:
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"activity_scope": "all_classified_activity",
"interval": "day",
"interval_seconds": 86400,
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
},
"purpose": "Measures whether typed opaque user subjects perform any later supported classified product activity after their first such activity inside the selected half-open range. It does not choose or infer a top event. Returns must occur strictly after the anchor, anonymous and unidentified subjects remain excluded from user counts, eligibility-aware denominators prevent immature subjects from being reported as churned, and raw identifiers are never returned.",
"coverage": {
"classified_events": 3,
"named_events": 3,
"unnamed_events": 0,
"identified_events": 3,
"start_events": 3,
"usable_start_events": 3,
"excluded_start_events": 0,
"return_events": 3,
"usable_return_events": 3,
"excluded_return_events": 0,
"event_name_rate": 1.0,
"start_identity_coverage_rate": 1.0,
"return_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"first_in_range anchors each subject at its first supported classified activity in the range; it does not prove that activity was the subject's first-ever product activity.",
"Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returns are any supported classified activity strictly after the subject anchor and before the exclusive query upper bound; no event is ranked, selected, or inferred.",
"This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
"return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
]
}
}
```
Otomatik modda `start_events` ve `return_events` değerlerinin ikisi de
`classified_events` değerine eşittir. Bu sayılar kullanıcı değil, olaydır.
### Uygun kullanıcı olmadan elde tutma
Başarılı bir sonuçta kohort kullanıcısı olmayabilir. Bu alıntı, kohortu
olmayan istenmiş tek bir dönemi gösterir:
```json theme={null}
{
"schema_version": 2,
"summary": {
"cohort_subjects": 0,
"subjects_returned_after_start": 0,
"non_empty_cohorts": 0,
"periods_with_eligible_subjects": 0,
"fully_observed_periods": 0
},
"curve": [
{
"period": 0,
"threshold_seconds": 0,
"window_end_seconds": 86400,
"eligible_subjects": 0,
"retained_subjects": 0,
"fully_observed_cohorts": 0,
"all_subjects_eligible": false
}
],
"cohorts": []
}
```
`coverage` ve `next_action` alanlarını okuyun. Bu alanlar sınıflandırılmış
olayı olmayan bir kapsamı (`capture_product_activity`) kullanıcısı olmayan
olaylardan (`identify_product_users` veya `identify_returning_users`) ayırır.
Eksik bir oran ölçülmüş bir sıfır değildir.
### Elde tutma hataları
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu istekler `422`
ve `validation_failed` döndürür:
| Neden | `error` |
| - | - |
| İki seçici olmadan sürüm 1, seçiciyle sürüm 2 veya başka bir sürüm | `product analytics retention activity selection is contradictory` |
| `1` ile `31` dışında bir `interval_count` | `product analytics retention interval_count must be between 1 and 31` |
| Kohort zaman dilimleri çarpı `interval_count` 500'den fazla | `product analytics retention interval and interval_count would exceed 500 cohort matrix cells` |
Hücre sınırı kullanıcı sayısını değil, aralığı ve dönemleri kullanır.
`interval: "hour"` ile 30 günlük bir aralıkta 720 kohort zaman dilimi olur.
`interval_count: 1` ile bu 720 hücre eder. Bu da 500'den fazladır:
```json theme={null}
{
"error": "product analytics retention interval and interval_count would exceed 500 cohort matrix cells",
"code": "validation_failed",
"next": "choose a wider interval, a shorter time range, or fewer retention periods",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Otomatik elde tutmayı kullanmak için iki seçiciyi de kaldırın. Bu okuma
isteğini düzeltmek için SDK'yı değiştirmeyin.
### Tam olay yaşam döngüsü isteği
Bu gövdeyi `POST /api/telemetry/analytics/lifecycle` adresine gönderin. İstek,
kullanıcıları projedeki tüm etkinliğe göre değil, tek bir olaya göre
sınıflandırır:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 1,
"interval": "day",
"history_period_count": 2,
"event": { "kind": "interaction", "event_name": "checkout_completed" }
}
```
`history_period_count`, LogBrew'ün geçmiş olarak okuduğu, `since` öncesindeki
tamamlanmış dönemleri belirler. `2` ile `31` arasında bir değer kabul eder.
Varsayılan `2` olur. Bir kullanıcı başka etkinlikler yaparken bu olay için
etkin olmayan durumda olabilir.
### Başarılı tam olay yaşam döngüsü
Bu yapay örnek iki günlük geçmiş ve iki analiz günü kullanır. Harfler yalnızca
örnek kullanıcıları belirtir. Yanıt kullanıcı kimliği döndürmez.
| Tarih, UTC | Ödemeyi tamamlayan kullanıcılar |
| - | - |
| 30 Mayıs, geçmiş | B |
| 31 Mayıs, geçmiş | A ve D |
| 1 Haziran, analiz | A, B ve C |
| 2 Haziran, analiz | A ve B |
C, 2 Haziran'da bir sayfayı da görüntüler. Bu olay ödeme seçicisiyle
eşleşmez.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"history_since": "2026-05-30T00:00:00Z",
"event": { "kind": "interaction", "event_name": "checkout_completed" },
"interval": "day",
"interval_seconds": 86400,
"history_period_count": 2,
"expected_buckets": 2
},
"purpose": "Classifies typed opaque user subjects for one exact product event in each fixed analysis period. new_within_observed_history means active now with no earlier matching event inside the bounded history window; returning means active now and in the immediately previous period; resurrected means active now, inactive in the previous period, and active earlier in observed history; dormant means active in the previous period but not now. These states are disjoint, incomplete buckets are marked, and raw subject identifiers are never returned.",
"summary": {
"observed_subjects": 4,
"analysis_active_subjects": 3,
"history_only_subjects": 1,
"returned_buckets": 2,
"fully_observed_buckets": 2,
"latest_fully_observed_period": 1,
"buckets_with_resurrection": 1,
"buckets_with_dormancy": 2
},
"coverage": {
"analysis_classified_events": 6,
"analysis_named_events": 6,
"analysis_unnamed_events": 0,
"analysis_identified_events": 6,
"selected_events": 5,
"usable_selected_events": 5,
"usable_selected_sessionized_events": 5,
"usable_selected_trace_linked_events": 5,
"excluded_selected_events": 0,
"history_selected_events": 3,
"usable_history_selected_events": 3,
"excluded_history_selected_events": 0,
"event_name_rate": 1.0,
"selected_identity_coverage_rate": 1.0,
"selected_sessionization_rate": 1.0,
"selected_trace_link_rate": 1.0,
"history_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"new_within_observed_history means no earlier selected event between history_since and the current bucket. It does not prove that a subject is a lifetime-new user.",
"Observed history contains exactly 2 complete fixed periods before since; activity before history_since is intentionally unknown.",
"Buckets are fixed-width and aligned to since. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returning, resurrected, and dormant compare only the selected exact kind and derived event name. They do not infer intent, identity merges, or causality.",
"This resource does not provide arbitrary property breakdowns, reusable cohorts, group lifecycle, lifetime first-event lookup, or per-subject lists."
]
},
"buckets": [
{
"period": 0,
"started_at": "2026-06-01T00:00:00Z",
"ended_at": "2026-06-02T00:00:00Z",
"fully_observed": true,
"active_subjects": 3,
"new_within_observed_history_subjects": 1,
"returning_subjects": 1,
"resurrected_subjects": 1,
"dormant_subjects": 1,
"previous_active_subjects": 2,
"new_share_of_active": 0.3333333333333333,
"returning_share_of_active": 0.3333333333333333,
"resurrected_share_of_active": 0.3333333333333333,
"dormant_share_of_previous_active": 0.5,
"net_active_change": 1
},
{
"period": 1,
"started_at": "2026-06-02T00:00:00Z",
"ended_at": "2026-06-03T00:00:00Z",
"fully_observed": true,
"active_subjects": 2,
"new_within_observed_history_subjects": 0,
"returning_subjects": 2,
"resurrected_subjects": 0,
"dormant_subjects": 1,
"previous_active_subjects": 3,
"new_share_of_active": 0.0,
"returning_share_of_active": 1.0,
"resurrected_share_of_active": 0.0,
"dormant_share_of_previous_active": 0.3333333333333333,
"net_active_change": -1
}
],
"next_action": {
"code": "investigate_lifecycle_loss",
"target": "/api/telemetry/analytics/paths",
"reason": "The latest complete bucket lost more prior active subjects than it added through new-within-observed-history and resurrected activity; compare bounded journeys around the selected event."
}
}
```
### Yaşam döngüsünü okuyun
1 Haziran'da A geri dönen, B yeniden etkinleşen, C yeni, D etkin olmayan
durumdadır. 2 Haziran'da A ve B geri dönendir. C ise sayfa görüntülemesine
rağmen ödeme için etkin olmayan durumdadır. 2 Haziran'daki net değişim
`2 - 3 = -1` olur.
Her zaman diliminde yeni, geri dönen ve yeniden etkinleşen kullanıcıların toplamı
`active_subjects` değerine eşittir. `returning_subjects` artı
`dormant_subjects`, `previous_active_subjects` değerine eşittir.
`net_active_change`, `active_subjects` eksi `previous_active_subjects`
değeridir.
Farklı kullanıcıları bulmak için günlük etkin sayıları toplamayın. Burada
günlük sayıların toplamı 5'tir, ancak `analysis_active_subjects` değeri 3'tür.
Geçmiş ve analiz boyunca dört farklı kullanıcı görünür.
`until` zamanından sonra biten son zaman diliminde `fully_observed` değeri
`false` olur. Dönemin tamamı gözlemlenebilir olduğunda sayıları değişebilir.
`next_action` bir inceleme önerir. Bir neden göstermez.
### Otomatik yaşam döngüsü
`response_version: 2` gönderin ve `event` seçicisi göndermeyin. Desteklenen
her sayfa görüntüleme, ekran görüntüleme ve etkileşim etkinlik sayılır:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 2,
"interval": "day",
"history_period_count": 2
}
```
Yanıtta tam olay yanıtıyla aynı `summary`, `buckets` ve `next_action`
yapıları bulunur. Bu alıntı değişen alanları gösterir:
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"history_since": "2026-05-30T00:00:00Z",
"activity_scope": "all_classified_activity",
"interval": "day",
"interval_seconds": 86400,
"history_period_count": 2,
"expected_buckets": 2
},
"purpose": "Classifies typed opaque user subjects by any supported classified product activity in each fixed period. It does not choose or infer a top event. new_within_observed_history, returning, resurrected, and dormant remain disjoint; anonymous and unidentified subjects are excluded from user counts, incomplete buckets are marked, and raw identifiers are never returned."
}
```
Otomatik modda `coverage.selected_events` değeri
`coverage.analysis_classified_events` değerine eşittir. Beşinci
`limitations` girdisi şudur:
`Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.`
### Kullanıcı olmadan yaşam döngüsü
Ne analiz aralığında ne de geçmişte kullanılabilir kullanıcı yoksa `buckets`
boş olur ve `summary` alanı `latest_fully_observed_period` içermez:
```json theme={null}
{
"schema_version": 2,
"summary": {
"observed_subjects": 0,
"analysis_active_subjects": 0,
"history_only_subjects": 0,
"returned_buckets": 0,
"fully_observed_buckets": 0,
"buckets_with_resurrection": 0,
"buckets_with_dormancy": 0
},
"buckets": []
}
```
Yalnızca geçmişte görünen kullanıcılar, analiz aralığında etkinlik olmasa da
etkin olmayan kullanıcılar içeren zaman dilimleri üretebilir.
### Yaşam döngüsü hataları
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu istekler `422`
ve `validation_failed` döndürür:
| Neden | `error` |
| - | - |
| `event` olmadan sürüm 1, `event` ile sürüm 2 veya başka bir sürüm | `product analytics lifecycle activity selection is contradictory` |
| `2` ile `31` dışında bir `history_period_count` | `product analytics lifecycle history_period_count must be between 2 and 31` |
| Toplamı 62 günden uzun geçmiş dönemleri | `product analytics lifecycle history must not exceed 62 days` |
| 100'den fazla analiz zaman dilimi | `product analytics lifecycle interval would exceed 100 analysis buckets` |
Örneğin on `week` geçmiş dönemi 70 gün gerektirir:
```json theme={null}
{
"error": "product analytics lifecycle history must not exceed 62 days",
"code": "validation_failed",
"next": "use fewer history periods or a narrower fixed interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
### Seçilen analiz kapsamını okuyun
Tam olay yanıtlarında `schema_version: 1` bulunur. Bu yanıtların `query`
alanı seçicileri geri yansıtır ve `activity_scope` içermez. Otomatik
yanıtlarda `schema_version: 2` ve `query.activity_scope: "all_classified_activity"`
bulunur. Bu yanıtlar seçicileri içermez. Farklı bir seçici, yakalanan
etkinlik hiç değişmeden sonucu değiştirebilir.
## Metrik serisi yanıtı
`GET /api/telemetry/metrics/series`, tek bir projedeki tek bir tam metrik
adını okur. Adı `GET /api/telemetry/metrics` yanıtından kopyalayın. Bu istek
bir delta sayacını hizmete göre gruplar:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "name=jobs.completed" \
--data-urlencode "since=2026-06-01T12:00:00Z" \
--data-urlencode "until=2026-06-01T12:15:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "group_by=service_name"
```
### Başarılı metrik serisi
Bu yapay yanıt tek bir delta sayacı serisi içerir. İlk zaman diliminde `2`,
`3` ve `5` değerli üç ölçüm örneği vardır. Son zaman diliminde `1` ve `4`
değerli iki ölçüm örneği vardır. Ortadaki zaman diliminde ölçüm örneği yoktur.
Bu yüzden yanıtta o dilim için nokta yoktur.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "jobs.completed",
"since": "2026-06-01T12:00:00Z",
"until": "2026-06-01T12:15:00Z",
"interval": "5m",
"interval_seconds": 300,
"group_by": "service_name",
"series_limit": 10
},
"purpose": "Shows how one metric changes over time without changing its meaning: gauges use sampled state, delta counters use change volume and rate, histograms use distributions, and cumulative streams stay raw when reset-safe change is ambiguous.",
"coverage": {
"samples": 5,
"series": 1,
"returned_series": 1,
"points": 2,
"expected_buckets_per_series": 3,
"first_seen_at": "2026-06-01T12:00:10Z",
"last_seen_at": "2026-06-01T12:14:50Z",
"truncated": false
},
"series": [
{
"identity": {
"kind": "counter",
"unit": "{job}",
"temporality": "delta",
"group_by": "service_name",
"group_value": "checkout-worker"
},
"status": "ready",
"aggregation": {
"code": "delta_sum",
"description": "Primary value is the sum of recorded changes in each bucket; rate_per_second normalizes that change by bucket width."
},
"sample_count": 5,
"points": [
{
"bucket_start": "2026-06-01T12:00:00Z",
"bucket_end": "2026-06-01T12:05:00Z",
"sample_count": 3,
"value": 10.0,
"last": 5.0,
"min": 2.0,
"max": 5.0,
"average": 3.3333333333333335,
"sum": 10.0,
"rate_per_second": 0.03333333333333333,
"trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
},
{
"bucket_start": "2026-06-01T12:10:00Z",
"bucket_end": "2026-06-01T12:15:00Z",
"sample_count": 2,
"value": 5.0,
"last": 4.0,
"min": 1.0,
"max": 4.0,
"average": 2.5,
"sum": 5.0,
"rate_per_second": 0.016666666666666666,
"trace_exemplars": []
}
]
}
],
"next_action": {
"code": "inspect_metric_change",
"target": "trace_summary",
"reason": "Open a trace exemplar from an unusual bucket to connect the metric change to spans, errors, logs, and release context."
}
}
```
### Metrik serisini okuyun
İlk nokta 10 ölçüm örneğini değil, tamamlanan 10 işi kaydeder.
`rate_per_second`, bu değişimi 300 saniyelik zaman dilimine böler. `last`
toplam değil, kaydedilen son değişimdir.
[Metrik toplama anlamları](/tr/concepts/telemetry#read-the-metric-value)
bölümüne bakın.
Bir serinin türü ve zamansallığı, onun `aggregation.code` değerini ve her
noktadaki istatistikleri seçer. Nokta, o seriye uygulanamayan bir istatistiği
içermez. Eksik bir istatistik sıfır değildir.
| Tür ve zamansallık | `status` | `aggregation.code` | `value` | Diğer istatistikler |
| - | - | - | - | - |
| `gauge`, `instant` | `ready` | `gauge_last` | Son ölçüm örneği | `last`, `min`, `max`, `average` |
| `counter`, `delta` | `ready` | `delta_sum` | Değişimlerin toplamı | `last`, `min`, `max`, `average`, `sum`, `rate_per_second` |
| `histogram`, `delta` | `ready` | `distribution_p95` | Yaklaşık p95 | `min`, `max`, `average`, `sum`, `p50`, `p95`, `p99` |
| Herhangi bir tür, `cumulative` | `limited` | `raw_cumulative_last` | Son ham ölçüm örneği | `last`, `min`, `max` |
| Diğer tüm çiftler | `limited` | `raw_last` | Son ham ölçüm örneği | `last`, `min`, `max` |
`limited` bir hata değil, başarılı bir yanıttır. LogBrew'ün neden yalnızca ham
değerleri gösterdiğini açıklayan `aggregation.limitation` alanını ekler.
`ready`, yakalamanın eksiksiz olduğunu kanıtlamaz.
Grafik çizmeden önce `coverage` alanını okuyun:
* `samples`, yanıtın döndürmediği seriler dâhil eşleşen tüm serilerin ölçüm
örneklerini sayar.
* `series` eşleşen serileri sayar. `returned_series` ve `points` dönen veriyi
sayar.
* `series_limit` daha düşük hacimli serileri çıkardıysa `truncated` değeri
`true` olur.
* `expected_buckets_per_series`, aralıktaki olası zaman dilimi sayısıdır.
Ölçüm örneği olmayan bir zaman dilimi için nokta eklemeyin. Sıfır eklemeyin
veya önceki değeri kopyalamayın. Her nokta en fazla 3 `trace_exemplars`
döndürür. İz örneği (trace exemplar), tek bir ölçüm örneğini bir ize bağlar.
Zaman dilimindeki her ölçüm örneğini açıklamaz. Hiçbir noktada iz örneği
yoksa `next_action.target` değeri `metric_samples` olur.
### Metrik serisi kapsamı ve hataları
`project_id`, `name` ve `since` zorunludur. `name` en fazla 200 karakter
olabilir. `interval` değeri `auto`, `1m`, `5m`, `15m`, `1h`, `6h` veya `1d`
olur. Varsayılan `auto` olur. Bu değer, en fazla 300 zaman dilimi gerektiren
en küçük aralığı seçer. Açıkça verilen bir aralık 500'den fazla zaman dilimi
gerektiremez.
`group_by` değeri `none`, `service_name`, `release` veya `environment` olur.
Varsayılan `none` olur. Gruplama olmadan farklı türler, birimler ve
zamansallıklar ayrı serilerde kalır. `series_limit`, `1` ile `20` arasında bir
değer kabul eder. Varsayılan `10` olur.
Boş bir sonuç `series: []` ve sıfır `samples` ile `200` döndürür. `coverage`
nesnesi `first_seen_at` ve `last_seen_at` içermez. Bu, uygulamanın metriği hiç
göndermediğini kanıtlamaz. Projeyi, metrik adını ve zaman aralığını kontrol
edin.
`name` gönderilmezse `422` döner:
```json theme={null}
{
"error": "metric series name is required",
"code": "validation_failed",
"next": "send the exact metric name returned by /api/telemetry/metrics",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Yedi gün boyunca bir dakikalık zaman dilimleri `422` döndürür:
```json theme={null}
{
"error": "metric series interval would exceed 500 buckets",
"code": "validation_failed",
"next": "use interval=auto or select a wider interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Diğer `422` hataları `metric series group_by is not supported`,
`metric series interval is not supported` ve
`metric series_limit must be between 1 and 20` olur.
## Yol analizi yanıtı
`POST /api/telemetry/analytics/paths`, aynı oturumda seçilen bir olaydan önceki
veya sonraki adlandırılmış olayları bulur. Seçilen olay çapadır. Çapanın
`kind` ve `event_name` değerlerini `classified_activity.top_events` içinden
kopyalayın. Rota `schema_version: 1` döndürür. `response_version` veya
`analysis_unit` kabul etmez.
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"direction": "following",
"anchor": { "kind": "page_view", "event_name": "/checkout" },
"depth": 2,
"collapse_repeated": true,
"path_limit": 2
}
```
`direction` ve `anchor` zorunludur.
### Başarılı yol analizi
Bu yapay sonuçta dört oturum çapayı içerir. Dönen iki yol bu oturumların
üçünü temsil eder. Daha alt sıradaki bir yol döndürülmez.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"direction": "following",
"anchor": { "kind": "page_view", "event_name": "/checkout" },
"depth": 2,
"collapse_repeated": true,
"path_limit": 2
},
"purpose": "Shows the highest-volume named product-event sequences immediately before or after one exact version-1 page view, screen view, or interaction inside explicit sessions. Following paths use the earliest matching anchor in each session; preceding paths use the latest. Optional exact property predicates classify only the anchor, while surrounding events preserve the real session journey. Results aggregate exact bounded sequences and never return raw session or subject identifiers.",
"summary": {
"anchored_sessions": 4,
"represented_sessions": 3,
"unrepresented_sessions": 1,
"returned_paths": 2,
"paths_truncated": true
},
"coverage": {
"classified_events": 12,
"named_events": 12,
"unnamed_events": 0,
"sessionized_events": 10,
"unsessionized_events": 2,
"anchor_events": 5,
"usable_anchor_events": 4,
"excluded_anchor_events": 1,
"traced_anchor_events": 1,
"event_name_rate": 1.0,
"sessionization_rate": 0.8333333333333334,
"anchor_session_coverage_rate": 0.8,
"anchor_trace_link_rate": 0.2,
"ordered_event_cap_per_session": 1024,
"limitations": [
"Paths include only supported version-1 classified events with exact derived names; arbitrary actions, technical spans, and raw identity values are excluded.",
"Paths stay inside application-supplied session boundaries and the selected half-open time range; activity beyond either boundary is not inferred.",
"Each session retains at most 1024 direction-nearest named events before anchoring, so exceptionally noisy sessions can be omitted or truncated.",
"Classified events without an explicit opaque session ID cannot participate in session paths.",
"Trace exemplars prove only that a matching anchor carried the same trace ID. They do not prove root cause, and deeper investigation depends on retained spans for that trace.",
"Some matching anchors lack trace IDs, so trace-linked path evidence covers only the reported traced_anchor_events population."
]
},
"paths": [
{
"rank": 1,
"sessions": 2,
"share_of_anchored_sessions": 0.5,
"traced_sessions": 1,
"trace_link_rate": 0.5,
"trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
"nodes": [
{ "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
{ "relative_position": 1, "kind": "interaction", "event_name": "checkout.submitted" },
{ "relative_position": 2, "kind": "interaction", "event_name": "checkout.completed" }
]
},
{
"rank": 2,
"sessions": 1,
"share_of_anchored_sessions": 0.25,
"traced_sessions": 0,
"trace_link_rate": 0.0,
"trace_exemplars": [],
"nodes": [
{ "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
{ "relative_position": 1, "kind": "interaction", "event_name": "checkout.failed" }
]
}
],
"next_action": {
"code": "inspect_path_trace",
"target": "/api/telemetry/traces/{trace_id}/investigation",
"reason": "Open an exemplar from the material path to connect the product journey to retained spans, issues, logs, actions, metrics, and release context as evidence rather than a root-cause claim."
}
}
```
### Yolları okuyun
`share_of_anchored_sessions`, bir yolun oturumlarını çapalı dört oturumun
tamamına böler. Paylar %67 ve %33 değil, %50 ve %25 olur.
`unrepresented_sessions`, dönen hiçbir yolun temsil etmediği çapalı oturumları
sayar. `paths_truncated: true`, sonucun eksik olduğu anlamına gelir.
Kapsama oranı oturumları değil, olayları sayar. Burada beş olay çapayla
eşleşir, ancak birinde oturum kimliği yoktur. Bu olay bir yola giremez. Her
yol en fazla 3 iz örneği döndürür. Kendi yanıtınızdaki bir iz kimliğini
kullanın. Bir iz bağlantısı, bir kullanıcı aksiyonuna veya bir hataya neyin
yol açtığını göstermez.
| Alan | Anlamı |
| - | - |
| `following` | Her oturumdaki en erken eşleşen çapada başlar. Çapanın konumu `0` olur. Sonraki düğümlerin konumları pozitiftir. |
| `preceding` | Her oturumdaki en geç eşleşen çapada biter. Önceki düğümlerin konumları negatiftir. Çapanın konumu `0` olur. |
| `depth` | Çapa sayılmadan, çapanın yanındaki düğüm sayısı. `1` ile `8` arası. Varsayılan `4` olur. Bir yolda daha az düğüm olabilir. |
| `collapse_repeated` | Aynı tür ve ada sahip art arda gelen düğümleri birleştirir. Varsayılan `true` olur. |
| `path_limit` | Oturum sayısına göre sıralanan en fazla dönen yol sayısı. `1` ile `20` arası. Varsayılan `10` olur. |
Düğümler iki yönde de zaman sırasındadır. Yol, oturumun tam bir yeniden
oynatması değildir. LogBrew çapayı seçmeden önce oturum başına en fazla 1024
adlandırılmış olay okur: `following` için en erken olayları, `preceding` için
en geç olayları. Bu sınırın dışındaki bir çapa sonuca girmeyebilir.
### Çapayı özelliğe göre filtreleyin
Her biri tek bir tam `key` ve `value` içeren en fazla dört `property_filters`
gönderin. Anahtarı [özellik kataloğundan](#analytics-property-catalog)
kopyalayın. Filtreler yalnızca çapaya uygulanır, çevresindeki olaylara
uygulanmaz. Değerler büyük/küçük harfe duyarlıdır. Filtreler varsa `query`
onları geri yansıtır ve `coverage.anchor_property_filters` şunları bildirir:
| Alan | Anlamı |
| - | - |
| `context_events` | Özellik filtrelerinden önce kapsamdaki çapa olayları. |
| `property_ready_events` | İstenen her anahtarı içeren çapa olayları. |
| `missing_property_events` | İstenen anahtarlardan bir veya daha fazlası eksik olan çapa olayları. |
| `matching_events` | Değerleri her filtreyle eşleşen çapa olayları. |
| `nonmatching_value_events` | Her anahtarı içeren ama farklı bir değere sahip çapa olayları. |
| `property_ready_rate` | `property_ready_events` bölü `context_events`. |
| `match_rate` | `matching_events` bölü `property_ready_events`. |
Eksik anahtarlar ve farklı değerler farklı düzeltmeler gerektirir. Bunları
toplamayın. İstekte özellik filtresi yoksa nesne gönderilmez.
### Boş yollar ve reddedilen istekler
Boş bir `paths` dizisi başarılı bir `200` yanıtı olabilir. `summary`,
`coverage` ve `next_action` alanlarını okuyun. Şu kodlar nedenleri ayırır:
`capture_product_activity`, `choose_captured_path_anchor`,
`capture_anchor_properties`, `improve_anchor_property_coverage`,
`verify_anchor_property_values`, `sessionize_product_activity` ve
`narrow_or_move_path_anchor`.
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu istekler `422`
ve `validation_failed` döndürür:
| Neden | `error` |
| - | - |
| `1` ile `8` dışında bir `depth` | `product analytics path depth must be between 1 and 8` |
| `1` ile `20` dışında bir `path_limit` | `product analytics path_limit must be between 1 and 20` |
| Dörtten fazla özellik filtresi | `product analytics paths accept at most four exact anchor property filters` |
| Özellik kataloğunda olmayan bir anahtar | `product analytics path property keys must be supported privacy-safe keys` |
| Aynı anahtar iki kez | `product analytics path property keys must be unique` |
| Boş bir değer, 256 karakterden uzun bir değer veya kontrol karakteri | `product analytics path property values must be non-empty, control-free, and at most 256 characters` |
Örneğin `depth: 0` şunu döndürür:
```json theme={null}
{
"error": "product analytics path depth must be between 1 and 8",
"code": "validation_failed",
"next": "use depth from 1 through 8 adjacent named events",
"next_action": { "code": "fix_request", "target": "request" }
}
```
## Analiz özellik kataloğu
`GET /api/telemetry/analytics/properties`, tek bir projedeki sınıflandırılmış
ürün olaylarının özellik anahtarlarını listeler. Anahtarları
[segment karşılaştırmalarında](#analytics-segment-comparison) ve yol çapası
filtrelerinde kullanın. Katalog anahtarları ve sayıları döndürür. Hiçbir
zaman özellik değerlerini veya kimlikleri döndürmez.
### Kullanılabilir özellik anahtarlarını okuyun
`project_id` ve `since` gönderin. `until`, `service_name`, `release`,
`environment`, `limit` ve `response_version` da gönderebilirsiniz. `limit`,
`1` ile `50` arasında anahtar kabul eder. Varsayılan `20` olur. Herkese açık
`estimation.method` değerini almak için `response_version=2` gönderin.
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "since=2026-06-01T00:00:00Z" \
--data-urlencode "until=2026-06-02T00:00:00Z" \
--data-urlencode "limit=20" \
--data-urlencode "response_version=2"
```
### Başarılı özellik kataloğu
Bu yapay sonuçta 100 sınıflandırılmış olay vardır. Bunların beşi güncel
özellik dizininden önce yakalanmıştır.
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-02T00:00:00Z",
"limit": 20
},
"purpose": "Discovers bounded privacy-safe runtime, framework, operating-system, device, application, and custom-tag keys captured on classified product events. It reports migration, capture, privacy-filtering, and per-key coverage without returning property values or identities, so humans and agents can build exact segment comparisons without guessing which dimensions exist.",
"summary": {
"classified_events": 100,
"available_property_keys": 3,
"returned_properties": 3
},
"coverage": {
"indexed_events": 95,
"unindexed_events": 5,
"complete_index_events": 95,
"incomplete_index_events": 0,
"privacy_filtered_events": 4,
"events_with_properties": 90,
"index_coverage_rate": 0.95,
"property_capture_rate": 0.9,
"properties_truncated": false,
"values_returned": false,
"limitations": [
"Property discovery returns keys and aggregate counts only; property values and identity columns are never returned.",
"Property filters use exact case-sensitive bounded string equality and combine with logical AND inside each segment.",
"Historical events written before the current property index are excluded from property descriptors and exact property filters.",
"Direct-identity, credential-like, and network-address custom tag keys were intentionally excluded from the analytics property index."
]
},
"estimation": {
"count_accuracy": "approximate",
"method": "approximate_distinct",
"description": "Available property-key and per-key distinct-value counts are approximate distinct counts. Classified-event, index-coverage, privacy-filtering, and per-key event counts are exact within the selected fully evaluated window."
},
"properties": [
{
"key": "resource.runtime.name",
"source": "standard_context",
"value_type": "string",
"events": 90,
"coverage_rate": 0.9,
"distinct_values": 2
},
{
"key": "resource.application.version",
"source": "standard_context",
"value_type": "string",
"events": 70,
"coverage_rate": 0.7,
"distinct_values": 4
},
{
"key": "tag.plan",
"source": "custom_tag",
"value_type": "string",
"events": 60,
"coverage_rate": 0.6,
"distinct_values": 3
}
],
"next_action": {
"code": "compare_property_segments",
"target": "/api/telemetry/analytics/segments/compare",
"reason": "Use exact returned keys with locally known values to compare behavior while preserving identity and property-value privacy."
}
}
```
### Kataloğu yorumlayın
`source`, `resource.runtime.name` gibi standart bir bağlam anahtarı için
`standard_context`, `tag.` ile başlayan bir anahtar için `custom_tag` olur.
`value_type` her zaman `string` olur. `properties`, `events` değerine göre en
yüksekten başlayarak sıralanır.
`tag.plan`, 100 sınıflandırılmış olayın 60'ında bulunur. Yaklaşık 3 farklı
değeri vardır. Anahtarın katalog kaydı bu değerleri göstermez. Uygulamanızdan
bildiğiniz değerleri kullanın. Bir sayıdan değer tahmin etmeyin. Bir olayda
birden fazla anahtar olabilir. Bu yüzden anahtar başına `events` sayılarını
toplamayın.
| Alan | Anlamı |
| - | - |
| `summary.classified_events` | Kapsamdaki sınıflandırılmış olaylar. Her `coverage_rate` değerinin paydasıdır. |
| `summary.available_property_keys` | Dönen satır sayısı değil, tahmini farklı anahtar sayısı. |
| `coverage.unindexed_events` | Güncel özellik dizininden önce yakalanan olaylar. Anahtar sağlayamazlar. |
| `coverage.incomplete_index_events` | Bağlamının bir kısmı bozuk veya kısaltılmış olaylar. Geçerli anahtarları yine sayılır. |
| `coverage.privacy_filtered_events` | LogBrew'ün hassas özel etiket anahtarlarını çıkardığı olaylar. Bir anahtar sayısı değildir. |
| `coverage.properties_truncated` | `limit` değerinden fazla anahtar varsa `true`. Kapsamı daraltın veya `limit` değerini en fazla 50'ye kadar artırın. |
| `coverage.values_returned` | Her zaman `false`. |
Boş bir `properties` dizisi, projede ürün olayı olmadığını kanıtlamaz.
`summary`, `coverage` ve `next_action` alanlarını okuyun.
### Özellik kataloğu hataları
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak `limit=0` veya
`limit=51`, `422` döndürür:
```json theme={null}
{
"error": "product analytics property limit must be between 1 and 50",
"code": "validation_failed",
"next": "use limit=1 through limit=50",
"next_action": { "code": "fix_request", "target": "request" }
}
```
`1` veya `2` dışında bir `response_version`
`product analytics response_version must be 1 or 2` döndürür. LogBrew
`response_version` değerini diğer değerlerden önce kontrol eder.
`POST` isteği `405` döndürür:
```json theme={null}
{
"error": "Method not allowed",
"code": "method_not_allowed",
"next": "send GET /api/telemetry/analytics/properties with required project_id and since plus optional until, service_name, release, environment, limit, or response_version query parameters",
"next_action": { "code": "use_supported_method", "target": "api_method" }
}
```
## Analiz segment karşılaştırması
`POST /api/telemetry/analytics/segments/compare`, tek bir projedeki 2 ila 4
segmentte oturumların veya kullanıcıların tek bir tam olaya ne sıklıkla
ulaştığını karşılaştırır. Bir segment olayları hizmete, sürüme, ortama ve
özellik değerlerine göre seçer. İlk segment temel segmenttir.
### Karşılaştırmayı tanımlayın
Bu JSON gövdesini hesap kimlik doğrulamasıyla ve
`Content-Type: application/json` ile gönderin. Buradaki `basic` ve `premium`,
LogBrew planları değil, örnek uygulamanın plan değerleridir:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "1h",
"analysis_unit": "session",
"response_version": 2,
"target": { "kind": "interaction", "event_name": "checkout_completed" },
"segments": [
{
"key": "basic",
"label": "Basic plan",
"service_name": "checkout-api",
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "basic" }]
},
{
"key": "premium",
"label": "Premium plan",
"service_name": "checkout-api",
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "premium" }]
}
]
}
```
`target` ve `segments` zorunludur. `analysis_unit` değeri `session` veya
`identified_user` olur. Varsayılan `session` olur. Bu değer kişileri değil,
oturumları sayar. `interval`, genel bakışla aynı değerleri kabul eder.
Varsayılan `auto` olur.
Her segmentin benzersiz bir `key`, bir `label` ve farklı bir filtre kümesi
olmalıdır:
* `key`: 1 ile 32 bayt arası. Küçük bir ASCII harfiyle veya bir rakamla
başlayın. Yalnızca küçük ASCII harfleri, rakamlar, `_` ve `-` kullanın.
* `label`: Kontrol karakteri içermeyen 1 ile 80 karakter arası.
* `service_name`, `release`, `environment`: İsteğe bağlı. Her değer kontrol
karakteri içermeyen 1 ile 256 karakter arasındadır.
* `property_filters`: 0 ile 4 arası filtre. Her anahtar bir segmentte bir kez
geçebilir. Bir olay segmentin tüm filtreleriyle eşleşmelidir. Değerler
büyük/küçük harfe duyarlıdır ve 1 ile 256 karakter arasındadır. LogBrew
baştaki ve sondaki boşlukları kırpar.
Filtresi olmayan bir segment, projedeki ve zaman aralığındaki tüm
sınıflandırılmış etkinliği seçer. Segmentler örtüşebilir. Farklı bir etiket
veya anahtar, birbirinin aynısı iki filtre kümesini geçerli yapmaz.
### Başarılı segment karşılaştırması
Bu yapay sonuçta temel segment 50 oturumun 10'unda ödemeye ulaşır. Premium
segmenti 60 oturumun 18'inde ulaşır.
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "1h",
"interval_seconds": 3600,
"analysis_unit": "session",
"target": { "kind": "interaction", "event_name": "checkout_completed" },
"segments": [
{
"key": "basic",
"label": "Basic plan",
"service_name": "checkout-api",
"release": null,
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "basic" }]
},
{
"key": "premium",
"label": "Premium plan",
"service_name": "checkout-api",
"release": null,
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "premium" }]
}
]
},
"purpose": "Compares how often explicit sessions or typed opaque user subjects reach one exact versioned page-view, screen-view, or interaction outcome across two through four named service, release, environment, and exact safe-property segments. It distinguishes missing property capture from nonmatching values, returns time trends and descriptive differences from the first segment, and never returns identities or claims causality or statistical significance.",
"summary": {
"segment_count": 2,
"baseline_segment_key": "basic",
"segments_with_eligible_units": 2,
"segments_with_target_events": 2,
"segments_with_reached_units": 2
},
"confidence": {
"interpretation": "descriptive_only",
"unique_count_accuracy": "approximate",
"estimation_method": "approximate_distinct",
"causal_inference": "not_established",
"statistical_significance": "not_tested",
"segment_overlap": "possible",
"limitations": [
"Unique session or typed user-subject counts use bounded cardinality estimates; event and capture-coverage totals are exact within the fully evaluated window.",
"Segments are evaluated independently and may overlap, so their totals must not be added or interpreted as a population partition.",
"Differences and relative lift are descriptive only. They do not control for exposure, assignment, seasonality, selection bias, or other confounders.",
"Bucket-level unique counts are recalculated inside each bucket and are not additive across the series.",
"Session analysis compares visits or app sessions, not unique people.",
"At least one segment has classified events without the selected unit ID; compare unit_coverage_rate before interpreting reach differences.",
"Property predicates are exact case-sensitive string matches. Events without the current property index or every requested key are excluded from segment results and reported separately as missing_property_events.",
"Direct-identity, credential-like, and network-address custom tag keys are excluded from the analytics property index and cannot be used for segmentation."
]
},
"segments": [
{
"key": "basic",
"label": "Basic plan",
"eligible_units": 50,
"reached_units": 10,
"reach_rate": 0.2,
"usable_target_events_per_reached_unit": 1.8,
"coverage": {
"classified_events": 200,
"unit_identified_events": 190,
"excluded_events": 10,
"unit_coverage_rate": 0.95,
"target_events": 20,
"usable_target_events": 18,
"excluded_target_events": 2,
"target_unit_coverage_rate": 0.9,
"traced_target_events": 10,
"target_trace_link_rate": 0.5,
"property_filters": {
"context_events": 500,
"property_ready_events": 480,
"missing_property_events": 20,
"property_ready_rate": 0.96,
"matching_events": 200,
"nonmatching_value_events": 280,
"match_rate": 0.4166666666666667
}
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T12:00:00Z",
"classified_events": 200,
"eligible_units": 50,
"target_events": 20,
"usable_target_events": 18,
"reached_units": 10,
"reach_rate": 0.2
}
]
},
{
"key": "premium",
"label": "Premium plan",
"eligible_units": 60,
"reached_units": 18,
"reach_rate": 0.3,
"usable_target_events_per_reached_unit": 1.8888888888888888,
"coverage": {
"classified_events": 240,
"unit_identified_events": 228,
"excluded_events": 12,
"unit_coverage_rate": 0.95,
"target_events": 36,
"usable_target_events": 34,
"excluded_target_events": 2,
"target_unit_coverage_rate": 0.9444444444444444,
"traced_target_events": 18,
"target_trace_link_rate": 0.5,
"property_filters": {
"context_events": 500,
"property_ready_events": 480,
"missing_property_events": 20,
"property_ready_rate": 0.96,
"matching_events": 240,
"nonmatching_value_events": 240,
"match_rate": 0.5
}
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T12:00:00Z",
"classified_events": 240,
"eligible_units": 60,
"target_events": 36,
"usable_target_events": 34,
"reached_units": 18,
"reach_rate": 0.3
}
],
"comparison_to_baseline": {
"eligible_units_difference": 10,
"reached_units_difference": 8,
"target_events_difference": 16,
"reach_rate_difference": 0.09999999999999998,
"relative_reach_rate_lift": 0.4999999999999998
}
}
],
"next_action": {
"code": "investigate_segment_paths",
"target": "/api/telemetry/analytics/paths",
"reason": "Inspect paths around the target in the weakest segment, then use correlated traces to explain a material behavioral difference."
}
}
```
### Oranları ve farkları okuyun
`eligible_units`, segmentte sınıflandırılmış etkinliği olan oturumları veya
kullanıcıları tahmin eder. `reached_units`, bunların kaçının hedefe ulaştığını
tahmin eder. `reach_rate`, `reached_units` bölü `eligible_units` değeridir.
Seçilen birim kimliği olmayan olaylar bu birimlere sayılmaz.
Temel oran %20'dir. Premium oranı %30'dur. Fark 10 yüzde puanıdır. Göreli
artış %10 değil, %50'dir. Küçük ondalık hataları kayan nokta aritmetiğinden
gelir. Oranları gösterim için yuvarlayın, ancak hesaplamayı dönen değerlerle
yapın. Temel segmentte `comparison_to_baseline` yoktur. Temel ulaşma oranı
sıfırsa göreli artış gönderilmez.
`query` içinde göndermediğiniz bir segment filtresi `null` olur. Boş bir
`property_filters` listesi gönderilmez.
`coverage.property_filters`,
[yol çapası filtresi kapsama oranı](#filter-the-anchor-by-property) ile aynı
alanlara sahiptir. Burada `matching_events`, `classified_events` değerine
eşittir. Eksik anahtarları ve farklı değerleri ayrı tutun. Segmentler
örtüşebilir ve bir oturum birden fazla zaman diliminde yer alabilir. Birim
sayılarını segmentler veya zaman dilimleri arasında toplamayın.
Karşılaştırma betimleyicidir. `confidence.causal_inference` değeri
`not_established`, `confidence.statistical_significance` değeri `not_tested`
olur. %20'ye karşı %30'luk bir oran, bir planın daha fazla ödemeye yol
açtığını göstermez.
### Segment karşılaştırma hataları
[Ortak kapsam hatalarına](#shared-scope-errors) ek olarak şu istekler `422`
ve `validation_failed` döndürür:
| Neden | `error` |
| - | - |
| 2'den az veya 4'ten fazla segment | `product analytics segment comparison requires two through four segments` |
| Aynı anahtara sahip iki segment | `product analytics segment keys must be unique` |
| Aynı filtrelere sahip iki segment | `product analytics segment filters must be unique` |
| İzin verilen 1 ile 32 bayt arasında olmayan bir anahtar | `product analytics segment keys must be 1 through 32 machine-safe bytes` |
| Boş, çok uzun veya kontrol karakteri içeren bir etiket | `product analytics segment labels must be non-empty, control-free, and at most 80 characters` |
| Kontrol karakteri içeren bir filtre değeri | `product analytics segment filters must be control-free` |
| Bir segmentte dörtten fazla özellik filtresi | `product analytics segments accept at most four exact property filters` |
| Özellik kataloğunda olmayan bir anahtar | `product analytics segment property keys must be supported privacy-safe keys` |
| Bir segmentte aynı özellik anahtarı iki kez | `product analytics segment property keys must be unique within each segment` |
| Boş, çok uzun veya kontrol karakteri içeren bir özellik değeri | `product analytics segment property values must be non-empty, control-free, and at most 256 characters` |
| `1` veya `2` dışında bir `response_version` | `product analytics response_version must be 1 or 2` |
`interval` hataları [genel bakış hatalarıyla](#overview-errors) aynıdır.
Örneğin anahtarları farklı, filtreleri aynı iki segment şunu döndürür:
```json theme={null}
{
"error": "product analytics segment filters must be unique",
"code": "validation_failed",
"next": "change at least one exact service_name, release, environment, or property filter",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Farklı bir etiket veya özellik filtrelerinin farklı sırası seçilen olayları
değiştirmez. Doğrulama hatası, hiçbir olayın eşleşmediğine dair kanıt
değildir.
`GET` isteği `405` döndürür:
```json theme={null}
{
"error": "Method not allowed",
"code": "method_not_allowed",
"next": "send POST /api/telemetry/analytics/segments/compare with project_id, since, one exact target, two through four named segments, and optional until, interval, analysis_unit, property_filters, or response_version JSON fields",
"next_action": { "code": "use_supported_method", "target": "api_method" }
}
```
## Sinyal hacmi yanıtı
`GET /api/telemetry/summary/volume`, tek bir proje ve zaman aralığı için
saklanan sinyalleri sayar. `project_id` ve `since` gerektirir. `project_ids`
kabul etmez.
`until` gelecekte olamaz. Göndermezseniz bitiş, istek zamanı olur. `24h` gibi
kısa bir `since`, `until` zamanından geriye doğru sayar. `interval` değeri
`auto`, `1m`, `5m`, `15m`, `1h`, `6h` veya `1d` olur. Varsayılan `auto`, en
fazla 120 zaman dilimi gerektiren en küçük aralığı seçer. Bir istek 500'den
fazla zaman dilimi gerektiremez. Tek `response_version` değeri `1` olur.
### Sinyal sayıları
Bu yapay yanıt bir dakikalık iki zaman dilimini kapsar. İstek, `until`
olmadan 12:02 UTC'de çalıştı. Hesabın saklama süresi 30 gündür. Dönen saklama
kuralını ve kesim zamanını okuyun. Bu değerlerin sizin hesabınız için de
geçerli olduğunu varsaymayın.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"requested_since": "2026-09-08T12:00:00Z",
"since": "2026-09-08T12:00:00Z",
"until": "2026-09-08T12:02:00Z",
"interval": "1m",
"interval_seconds": 60,
"bucket_alignment": "query_relative_utc_half_open",
"bucket_count": 2,
"service_name": "checkout-api",
"release": "api@1.2.3",
"environment": "production"
},
"purpose": "Compares retained issue occurrences, log events, unique traces, action events, and metric points over one exact project and time scope. Every lane is independently scalable, uses explicit zero-filled half-open buckets, returns no source telemetry rows, and qualifies retention and sampling so different signal volumes are not mistaken for equivalent impact.",
"series": [
{
"signal": "issues",
"count_unit": "issue_occurrences",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "logs",
"count_unit": "log_events",
"total": 3,
"peak": 2,
"non_empty_buckets": 2,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 2 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 1 }
]
},
{
"signal": "traces",
"count_unit": "unique_traces_by_first_observed_span",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "actions",
"count_unit": "action_events",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "metrics",
"count_unit": "metric_points",
"total": 2,
"peak": 2,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 0 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 2 }
]
}
],
"coverage": {
"storage_evaluation": "complete",
"output_truncation": "not_truncated",
"payload_shape": "aggregate_only",
"count_precision": "exact",
"integer_safety": "javascript_safe",
"javascript_safe_integer_max": 9007199254740991,
"returned_series": 5,
"returned_points": 10,
"max_buckets_per_series": 500,
"retention": {
"policy_days": 30,
"cutoff": "2026-08-09T12:02:00Z",
"window_clipped": false
},
"sampling": {
"server": "not_applied",
"upstream": "unknown"
},
"limitations": ["upstream_sampling_unknown", "release_volume_not_included"]
}
}
```
### Her sayıyı kendi biriminde okuyun
| Sinyal | `total` neyi sayar | Şu şekilde okumayın |
| - | - | - |
| `issues` | Saklanan sorun oluşumları | Gruplanmış sorunlar veya etkilenen kullanıcılar |
| `logs` | Saklanan log olayları | İstekler |
| `traces` | Bu aralıktaki ilk saklanan span'lerinde sayılan benzersiz iz kimlikleri | Span'ler veya izlerin tüm ömürleri boyunca başlama sayısı |
| `actions` | Saklanan aksiyon olayları | Kullanıcılar veya oturumlar |
| `metrics` | Saklanan metrik noktaları | Metrik değerlerinin toplamı |
`total`, serinin zaman dilimi sayılarının toplamıdır. `peak`, serinin en büyük
zaman dilimi sayısıdır. `non_empty_buckets`, sayısı sıfırdan büyük olan zaman
dilimlerini sayar. Beş seri her zaman bu sırayla gelir. Farklı sinyal
sayılarını tek bir etki puanında birleştirmeyin.
Zaman dilimleri `query.since` zamanında başlar. Bir zaman dilimi başlangıcını
içerir, bitişini içermez. Son zaman dilimi aralık süresinden kısa olabilir.
Yanıtta sürüm sayısı serisi yoktur. `release_volume_not_included` değerini
sıfır sürüm olarak okumayın.
### Boş ve kısalmış aralıklar
Hiçbir sinyal eşleşmezse beş serinin tamamı yine bulunur ve noktalarında açık
sıfır sayılar olur. Başarısız bir istek farklıdır. Bir hatayı sıfırlarla dolu
bir grafikle değiştirmeyin.
`query.requested_since` ile `query.since` değerlerini karşılaştırın. Saklama
süresi aralığı kısaltırsa `coverage.retention.window_clipped` değeri `true`
olur ve `limitations` içinde `retention_window_clipped` bulunur. İstenen
aralıktan hiçbir şey kalmazsa `query.bucket_count` değeri `0` olur ve her
serinin `points` dizisi boştur. Bu, o dönemde hiç olay olmadığını kanıtlamaz.
Saklama sınırı yoksa `policy_days` değeri `null` olur ve `cutoff`
gönderilmez. `storage_evaluation` değeri `complete` olsa bile
`sampling.upstream` her zaman `unknown` olur. Yanıtın, uygulamanın ürettiği
her olayı saydığını iddia etmeyin.
### Reddedilen sinyal hacmi istekleri
Şu istekler `422` ve `validation_failed` döndürür:
| Neden | `error` |
| - | - |
| `project_id` yok | `signal volume project_id is required` |
| `since` yok | `signal volume since is required` |
| `until` istek zamanından sonra | `signal volume until must not be in the future` |
| Aralık 31 günden uzun | `signal volume range must not exceed 31 days` |
| 500'den fazla zaman dilimi gerektiren açık bir aralık | `signal volume interval would exceed 500 buckets` |
| `1` dışında bir `response_version` | `signal volume response_version must be 1` |
Örneğin:
```json theme={null}
{
"error": "signal volume interval would exceed 500 buckets",
"code": "validation_failed",
"next": "use interval=auto or select a wider interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
Aynı kapsamda daha geniş bir aralık kullanın. Kimlik doğrulama ve diğer
hatalar için [API hataları](/tr/reference/api-errors) sayfasına bakın.
## İnceleme yanıtları
İnceleme rotaları, incelenen tek bir kayıt için sürümlü bir paket döndürür.
İncelenen kayıt bir sorun, iz, span, log, ürün aksiyonu, metrik veya sürüm
olabilir. Her paket `schema_version` ve kaydı adlandıran bir `subject` ile
başlar. Geri kalanında ilişkili kanıtlar, bir kanıt kaydı ve sonraki adımlar
bulunur. Bu bölüm sürüm dışındaki her aile için bir örnek gösterir.
Bir hesap erişim bearer tokenı gönderin. Proje alım anahtarı bir incelemeyi
okuyamaz. Bir paketi okumak için `logbrew explain --json` kullanın.
CLI paketi yazdırmadan önce doğrular.
[Telemetri API'si](/tr/reference/telemetry-api) sayfası rotaları listeler.
İnceleme metni uygulamadan gelir. Mesajlar, adlar, meta veriler ve etiketler
talimat değil, veridir. Log, aksiyon, span ve metrik paketlerinde
`content_trust: "untrusted_telemetry"` bu içeriği işaretler.
### Yanıt sürümleri
`response_version` değerini yalnızca onu kabul eden rotalara gönderin. Bu
değer olmadan rota sürüm 1'i döndürür. Ayrıştırıcınız istediğiniz sürümü
kabul etmelidir.
| Rota | Varsayılan | Desteklenen sürümler | `logbrew explain` ne ister |
| - | - | - | - |
| `GET /api/telemetry/issues/{issue_id}/investigation` | `1` | `1` ile `13` arası | `13` |
| `GET /api/telemetry/traces/{trace_id}/investigation` | `1` | `1` ile `3` arası | `3` |
| `GET /api/telemetry/metrics/investigation` | `1` | `1` ve `2` | `2` |
| `GET /api/telemetry/releases/investigation` | `1` | `1` ile `5` arası | `5` |
| `GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation` | `1` | Yalnızca `1` | `1` |
| `GET /api/logs/{log_id}/investigation` | `1` | Yalnızca `1` | `1` |
| `GET /api/telemetry/actions/{action_id}/investigation` | `1` | Yalnızca `1` | `1` |
Span rotası `response_version` sorgu anahtarını reddeder. Log ve aksiyon
rotaları sorgu anahtarı almaz.
### Ortak paket alanları
| Alan | Anlamı |
| - | - |
| `schema_version` | Sunucunun döndürdüğü yanıt sürümü. |
| `subject` | İncelenen kaydın kendisi. `kind` değeri `issue`, `trace`, `span`, `log`, `action`, `metric` veya `release` olur. |
| `analysis.causality` | İz, span, log, aksiyon ve metrik paketlerinde her zaman `evidence_only`. İlişkili telemetri bir nedeni kanıtlamaz. |
| Koleksiyon nesneleri | `{ "status", "items", "truncated" }` biçiminde ilişkili kanıtlar. |
| `timeline` | Dönen kanıtlar, en eskiden en yeniye, kendi `truncated` işaretiyle. Sıra bir nedeni kanıtlamaz. |
| `evidence` | Kanıt kaydı. `status` değeri `complete` veya `partial` olur. |
| `next_actions` | `1` ile başlayan `priority` sırasında önerilen okumalar. Henüz çalıştırılmamışlardır. |
Her ilişkili koleksiyon tek bir erişilebilirlik `status` değeri bildirir:
| Durum | Anlamı | İstemci davranışı |
| - | - | - |
| `available` | Okuma tamamlandı ve öğeler döndü. | Öğeleri ve `truncated` işaretini gösterin. |
| `not_linked` | Kayıtta bu bağlantı için iz kimliği gibi bir tanımlayıcı yok. | Eksik bağlantıyı açıklayın. Zaman damgalarından bağlantı oluşturmayın. |
| `not_found` | Okuma tamamlandı ve saklanan kanıt bulamadı. | Boş bir sonuç gösterin. |
| `unavailable` | İsteğe bağlı okuma başarısız oldu. Kayıt yine geçerlidir. | Kaydı görünür tutun. Daha sonra yeniden deneyin. Sonuç olarak sıfır öğe göstermeyin. |
Kanıt kaydında sabit alan adlarından oluşan dört sıralı liste vardır:
`captured_fields`, `missing_fields`, `redacted_fields` ve
`truncated_fields`. `status` yalnızca son üç liste boşsa `complete` olur.
Gizlenmiş veri eksik veri değildir. Kısaltılmış veri eksiksiz veri değildir.
Gizlenmiş veya kısaltılmış bir değeri doldurmayın.
### İnceleme sınırları
Bu sınırlar tek bir yanıtı sınırlar. Bir `truncated` işareti veya bir
`truncated_fields` girdisi, bir sınırın veriyi dışarıda bıraktığını gösterir.
| Kanıt | Sınır |
| - | - |
| Tek bir koleksiyondaki ilişkili öğeler | 20 |
| Tek bir iz için okunan saklanmış span'ler | 1,000 |
| Zaman çizelgesi öğeleri | Log, aksiyon ve span paketleri için 50. İz ve metrik paketleri için 100. |
| Yapılandırılmış öznitelikler, özellikler ve meta veriler | 64 skaler değer, 4 düzey nesne veya dizi, her dizide 16 öğe, her dizede 512 karakter |
| İlişki zaman aralığı | Bir logdan, aksiyondan veya seçilen sorun oluşumundan 5 dakika önce ve sonra. Bir iz veya span için başlangıçtan 5 dakika önce ve bitişten 5 dakika sonra, en fazla 24 saat. |
Her ailenin bölümü kendi sınırlarını listeler.
### Sorun incelemesi yanıtı
Gruplanmış bir sorunun tek bir oluşumuna ait kanıtları okumak için
`GET /api/telemetry/issues/{issue_id}/investigation` kullanın.
[Bir sorunu inceleyin](/tr/guides/investigate-an-issue) rehberi, kanıtların hangi
sırayla okunacağını gösterir. Sürüm 13'ü isteyin:
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/issues/$LOGBREW_ISSUE_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "response_version=13" \
--data-urlencode "selection=recommended"
```
Sorgu anahtarları `response_version`, `selection` ve `occurrence_id` olur.
`selection` değeri `recommended`, `first` veya `latest` olur. Değerler
büyük/küçük harfe duyarlıdır. Sürüm 2 ile 13 arasında seçici gönderilmezse
`recommended` kullanılır. Sürüm 1 saklanan en son oluşumu döndürür ve seçici
kabul etmez. Sorun listesi filtreleri bu okumaya uygulanmaz.
Bu yapay `200 OK` yanıtında, bağlı bir izi olan ve ele alınmış bir
`TypeError` oluşumu vardır. İstek, önceki adım, ilişkili log veya dağıtım
kanıtı yoktur. Bu yüzden `evidence.status` değeri `partial` olur.
```json theme={null}
{
"schema_version": 13,
"subject": {
"kind": "issue", "id": "11111111-1111-4111-8111-111111111111",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"fingerprint": "checkout-cart-total", "status": "unresolved", "severity": "error",
"title": "TypeError",
"message": "Cannot read properties of undefined (reading 'total')",
"occurrence_count": 1, "first_seen_at": "2026-08-03T11:05:00Z",
"last_seen_at": "2026-08-03T11:05:00Z"
},
"event": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": {
"schema_version": 1,
"resource": {
"service": null,
"deployment": null,
"runtime": {"name": "node", "version": "24.4.0"},
"framework": null,
"operating_system": {"name": "Linux", "version": "6.8", "build": null},
"device": {"family": null, "model": null, "architecture": "arm64"},
"application": null
},
"trace": {
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"parent_span_id": null, "sampled": true
},
"session": null,
"subject": null,
"tags": {}
},
"exception": {"type": "TypeError", "mechanism": {"type": "javascript.error", "handled": true}},
"exception_chain": {
"status": "captured",
"entries": [
{
"id": 0,
"parent_id": null,
"relationship": "reported",
"type": "TypeError",
"message": null,
"message_state": "redacted",
"module": null,
"mechanism": {"type": "javascript.error", "handled": true},
"stack_frames": [
{
"index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null, "source": "captured"
},
{
"index": 1, "module": null, "function": "handleCheckout",
"file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
"source": "captured"
}
],
"stack_frames_state": "captured"
}
],
"truncated": false
},
"stack_frames": [
{
"index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null, "source": "captured"
},
{
"index": 1, "module": null, "function": "handleCheckout",
"file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
"source": "captured"
}
],
"breadcrumbs": [],
"breadcrumbs_truncated": false
},
"occurrence_selection": {
"requested": "recommended",
"reason": "only_retained_occurrence",
"selected": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"first": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"latest": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"recommended": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"recommendation": {
"algorithm_version": 1, "candidate_count": 1, "candidate_limit": 50,
"candidate_window_truncated": false
}
},
"lifecycle": {
"persisted_status": "unresolved",
"effective_status": "unresolved",
"activity": {"status": "available", "changes": [], "truncated": false},
"regression": {
"status": "not_detected", "reason": "no_resolution_recorded",
"resolution_changed_at": null, "first_reappeared_occurrence": null
}
},
"occurrence_analysis": {
"status": "complete",
"coverage": {
"retained_occurrences": 1, "trend_occurrences": 1, "available_distribution_count": 4,
"expected_distribution_count": 4, "max_buckets": 30, "max_values_per_dimension": 10
},
"trend": {
"scope_start": "2026-08-03T11:05:00Z",
"scope_end": "2026-08-03T11:05:00Z",
"interval_seconds": 60,
"buckets": [
{
"bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:06:00Z",
"occurrence_count": 1
}
]
},
"distributions": [
{
"dimension": "release",
"distinct_value_count": 1,
"values": [
{
"value": "checkout@1.2.3", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "environment",
"distinct_value_count": 1,
"values": [
{
"value": "production", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "service",
"distinct_value_count": 1,
"values": [
{
"value": "checkout-api", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "sdk",
"distinct_value_count": 1,
"values": [
{
"value": "@logbrew/node", "version": "0.1.11", "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
}
],
"limitations": []
},
"grouping": {"strategy": "sdk_fingerprint", "components": ["sdk_fingerprint"], "stack": null},
"cause": {
"status": "evidence_only",
"summary": null,
"provenance": null,
"signals": ["handled_exception", "error_trace_span"]
},
"fix": {
"status": "observed_frame",
"location": {
"component": null, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null
},
"provenance": "backend_observed"
},
"source_locator": {
"status": "not_found",
"repository_provider": null,
"repository_full_name": null,
"component_path": null,
"revision": null,
"revision_source": null,
"repository_relative_file": null,
"evidence": {
"status": "partial",
"captured_fields": ["source.service"],
"missing_fields": ["source.component"],
"redacted_fields": [],
"truncated_fields": []
}
},
"reproduction": {
"status": "insufficient_evidence",
"baseline_occurrence_id": "22222222-2222-4222-8222-222222222222",
"evidence": {
"status": "partial",
"captured_fields": [
"reproduction.baseline_occurrence", "reproduction.code_location",
"reproduction.expected_failure"
],
"missing_fields": ["reproduction.trigger"],
"redacted_fields": [],
"truncated_fields": []
}
},
"impact": {
"occurrence_count": 1,
"first_seen_at": "2026-08-03T11:05:00Z",
"last_seen_at": "2026-08-03T11:05:00Z",
"affected_users": null,
"user_impact": {
"status": "not_captured",
"known_affected_users": null,
"count_method": "unavailable",
"coverage": {
"retained_occurrences": 1, "indexed_occurrences": 1,
"historical_unindexed_occurrences": 0, "identified_user_occurrences": 0,
"anonymous_subject_occurrences": 0, "missing_subject_occurrences": 1,
"privacy_filtered_subject_occurrences": 0, "index_coverage_basis_points": 10000,
"identified_user_coverage_basis_points": 0
},
"limitations": ["missing_subject_context"]
},
"reported": null
},
"correlations": {
"trace": {
"status": "available",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"summary": {
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_count": 1,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:04:59.950Z",
"duration_ms": 180,
"root_span": {
"span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "error",
"started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
"service_name": "checkout-api"
},
"slowest_child_span": null,
"slowest_path": [],
"error_spans": [
{
"span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "error",
"started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api", "span_count": 1, "error_span_count": 1,
"max_duration_ms": 180
}
],
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"truncated": false
},
"logs": {"status": "not_found", "items": [], "truncated": false},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false},
"related_issues": {"status": "not_found", "items": [], "truncated": false},
"release": {
"release": "checkout@1.2.3", "environment": "production",
"service_name": "checkout-api", "deployment_status": "not_found"
}
},
"evidence": {
"status": "partial",
"captured_fields": [
"context", "deployment.lookup", "exception", "exception.mechanism", "exception_chain",
"exception_chain.stack_frames", "grouping", "grouping.components",
"grouping.strategy", "grouping.strategy_details", "lifecycle.regression",
"lifecycle.status_history", "likely_fix_area", "occurrence.boundaries",
"occurrence.distribution.environment", "occurrence.distribution.release",
"occurrence.distribution.sdk", "occurrence.distribution.service",
"occurrence.recommendation", "occurrence.selection", "occurrence.trend", "release",
"sdk", "source_locator", "stack_frames", "trace"
],
"missing_fields": [
"affected_users", "breadcrumbs", "deployment", "impact", "likely_root_cause",
"related_actions", "related_issues", "related_logs", "related_metrics", "request",
"source_locator.complete"
],
"redacted_fields": ["exception_chain.messages"],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_code_location", "target": "source_code",
"reason": "likely_fix_location_available"
},
{
"priority": 2, "code": "inspect_trace", "target": "trace_summary",
"reason": "linked_trace_available"
},
{
"priority": 3, "code": "compare_release", "target": "release_summary",
"reason": "release_identity_available"
},
{
"priority": 4, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete"
}
]
}
```
| Alan | Sürüm | Anlamı |
| - | - | - |
| `subject` | 1 | Gruplanmış sorun. `first_seen_at`, `last_seen_at` ve `occurrence_count` grubu anlatır. |
| `event` | 1 | Seçilen oluşum: SDK, `context`, `exception`, `stack_frames` ve `breadcrumbs`. Sürüm 1'de en son oluşum okunamıyorsa `null`. |
| `cause` | 1 | `status` değeri `reported_hypothesis`, `evidence_only` veya `unknown` olur. `signals` gözlemlenen sinyalleri listeler. |
| `fix` | 1 | Bir kod konumu. `status` değeri `reported_location`, `observed_application_frame`, `observed_frame`, `observed_underlying_exception_frame` veya `unknown` olur. |
| `impact` | 1 | Oluşum sayıları ve `user_impact`. `reported`, uygulamanın bildirdiği etkiyi veya `null` değerini tutar. |
| `correlations` | 1 | `trace`, `logs`, `actions`, `metrics` ve `release`. |
| `occurrence_selection` | 2 | İstenen seçici, nedeni ve seçilen, ilk, en son ve önerilen oluşumların özetleri. |
| `lifecycle` | 3 | `persisted_status`, `effective_status`, durum etkinliği ve `regression`. `effective_status` değeri `regressed` olabilir. |
| `occurrence_analysis` | 4 | Oluşum eğilimi ile sürüm, ortam, hizmet ve SDK dağılımları. |
| `event.exception_chain` | 5 | En fazla 8 bağlı istisna. `relationship` değeri `reported`, `cause`, `context`, `aggregate_member` veya `suppressed` olur. |
| `event.request` | 6 | `method`, `route_template` ve `response_status_code`. İstek yakalanmadıysa anahtar yoktur. |
| `grouping` | 7 | Gruplama `strategy` değeri, onun `components` değeri ve yığın çerçevesi kullanımı. |
| `correlations.release.deployment_status` | 8 | Dağıtım aramasının durumu. `deployment`, `time_since_deployment_ms` ve `deployment_causality` yalnızca bir dağıtım bulunduysa görünür. |
| `correlations.related_issues` | 9 | Aynı izdeki diğer sorunlar. |
| `source_locator` | 10 | LogBrew bağlayabildiğinde depo, bileşen, revizyon ve depoya göre dosya yolu. |
| `reproduction` | 11 | `status` değeri `ready`, `partial` veya `insufficient_evidence` olur. |
| `next_actions` kodu `verify_correction` | 12 | `reproduction.status` değeri `ready` olduğunda görünür. |
| `impact.user_impact.count_method` | 13 | Yaklaşık farklı sayıyı `approximate_distinct` olarak bildirir. Önceki sürümler eski bir değer adı kullanır. `unavailable`, sayı olmadığı anlamına gelir. |
Sonraki bir sürümün anahtarları önceki bir sürümde yoktur. Eksik bir anahtarı
`null` olarak okumayın.
`subject.status` ve `lifecycle` durumları, arşivlenmiş bir sorunu `ignored`
olarak bildirir. Sorun listesi ve ayrıntı yanıtları, yanıt sürümü 2 ve
sonrasında `archived` kullanır.
Sorun sınırları: Öneri en fazla 50 saklanmış oluşum okur. Eğilimde en fazla
30 zaman dilimi olur. Her dağılım en fazla 10 değer döndürür. Bir yığında en
fazla 32 çerçeve olur.
#### Sorun incelemesi istek hataları
`selection` veya `occurrence_id` değerlerinden yalnızca birini kullanın. Aynı
oluşumu seçseler bile ikisini birlikte göndermeyin:
```json theme={null}
{
"error": "selection and occurrence_id are mutually exclusive",
"code": "validation_failed",
"next": "use response_version=2 through 13 with at most one of selection=first|latest|recommended or an exact occurrence_id copied from GET /api/telemetry/issues/{issue_id}/events",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
| HTTP | `error` | Neden | Kurtarma |
| - | - | - | - |
| `422` | `selection and occurrence_id are mutually exclusive` | İstekte iki seçici de var. | Tek bir seçici bırakın. |
| `422` | `issue occurrence selection requires response_version=2 through 13` | İstekte seçiciyle birlikte sürüm 1 var veya sürüm yok. | `response_version=13` gönderin. Seçiciyi koruyun. |
| `422` | `issue investigation response_version must be 1 through 13` | Sürüm aralığın dışında. | Desteklenen bir sürüm gönderin. |
| `422` | `invalid query parameters` | Bilinmeyen bir anahtar, geçersiz bir UUID, tam sayı olmayan bir sürüm veya bilinmeyen bir `selection` değeri. | [Sorguyu](/tr/reference/api-errors#invalid-query-parameters) düzeltin. |
| `404` | `issue occurrence not found` | Oluşum bu grubun saklanan geçmişinde yok. | Oluşum kimliğini bu sorunun olaylarından kopyalayın. Onay almadan yerine `latest` veya `recommended` kullanmayın. |
| `404` | `issue not found` | Okunabilir hiçbir projede bu sorun yok. | Hesabı ve sorun UUID'sini kontrol edin. Sorun kimliği olarak bir oluşum UUID'si göndermeyin. |
Eksik bir oluşum, sorunun eksik olduğu anlamına gelmez. `404`, başka bir
hesabın sorunu okuyup okuyamadığını göstermez.
### İz incelemesi yanıtı
Tek bir izi hata yolu, en yavaş yolu ve ilişkili sinyalleriyle okumak için
`GET /api/telemetry/traces/{trace_id}/investigation` kullanın. Sorgu
anahtarları `response_version`, `project_id`, `release` ve `environment`
olur. Hepsi isteğe bağlıdır. Sürüm 3'ü isteyin:
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "response_version=3"
```
Sürüm 2, ilişkili her soruna `cause` ve `fix` ekler. Sürüm 3, yakalandıysa
ilişkili sorunlara, aksiyonlara ve metriklere `span_id` ekler.
Bu yapay yanıtta bir kök sunucu span'i ve başarısız bir istemci span'i vardır.
Başarısız span aynı zamanda en yavaş alt span'dir. Span'lerin yapılandırılmış
bağlamı yoktur. Bu yüzden `spans.context` eksiktir.
```json theme={null}
{
"schema_version": 3,
"subject": {
"kind": "trace",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"analyzed_span_count": 2,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"analysis": {
"status": "errors_observed",
"causality": "evidence_only",
"root_span": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"first_error_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"first_error_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"bottleneck_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"bottleneck_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
]
},
"spans": {
"items": [
{
"id": "33333333-3333-4333-8333-333333333333",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"span_id": "b7ad6b7169203331",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "ok",
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"roles": ["root", "error_path", "bottleneck_path", "slow"]
},
{
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"span_id": "53995c3f42cd8ad8",
"parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-08-03T11:05:00.100Z",
"duration_ms": 900,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"roles": ["first_error", "error_path", "bottleneck", "bottleneck_path", "error", "slow"]
}
],
"truncated": false
},
"correlations": {
"window": {
"since": "2026-08-03T11:00:00Z",
"until": "2026-08-03T11:10:01.200Z",
"scopes": [
{
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"issues": {"status": "not_found", "items": [], "truncated": false},
"logs": {
"status": "available",
"items": [
{
"id": "55555555-5555-4555-8555-555555555555",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
"source": "payments", "message": "Charge request failed",
"occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false}
},
"timeline": {
"items": [
{
"id": "b7ad6b7169203331", "kind": "span", "occurred_at": "2026-08-03T11:05:00Z",
"name": "POST /checkout", "service_name": "checkout-api",
"span_id": "b7ad6b7169203331", "severity": null, "status": "ok",
"duration_ms": 1200
},
{
"id": "53995c3f42cd8ad8", "kind": "span", "occurred_at": "2026-08-03T11:05:00.100Z",
"name": "POST /v1/charges", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
"duration_ms": 900
},
{
"id": "55555555-5555-4555-8555-555555555555", "kind": "log",
"occurred_at": "2026-08-03T11:05:01Z", "name": "Charge request failed",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
"status": null, "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"correlations.window", "related_actions", "related_issues", "related_logs",
"related_metrics", "spans.sdk", "timeline", "trace.parentage", "trace.root",
"trace.spans"
],
"missing_fields": ["spans.context"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_first_error_span", "target": "trace_span",
"reason": "error_span_observed", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 2, "code": "review_related_logs", "target": "telemetry_logs",
"reason": "related_logs_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_summary",
"reason": "release_identity_available", "span_id": null, "issue_id": null
},
{
"priority": 4, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "span_id": null, "issue_id": null
}
]
}
```
| Alan | Anlamı |
| - | - |
| `subject` | Analiz edilen span'lerden iz toplamları. |
| `analysis.status` | `errors_observed`, `latency_focus` veya `no_error_observed`. |
| `analysis.first_error_path` | Kökten en erken hata span'ine kadar bilinen üst span zinciri. |
| `analysis.bottleneck_path` | En yavaş alt span'e kadar bilinen üst span zinciri. |
| `spans.items[].roles` | Span'in önizlemede neden yer aldığı: `root`, `first_error`, `error_path`, `bottleneck`, `bottleneck_path`, `error` veya `slow`. |
| `correlations.window` | İlişkili okumalar için kullanılan zaman aralığı ve dağıtım kapsamları. |
| `correlations.issues`, `logs`, `actions`, `metrics` | Aralıkta aynı iz kimliğine sahip sinyaller. |
Bir span, LogBrew'ün saklamadığı bir üst span'i adlandırıyorsa
`trace.parentage` eksik olur. Span önizlemesinde en fazla 64 span olur. Her
analiz yolunda en fazla 64 span olur. İlişkili okumalar en fazla 8 dağıtım
kapsamı kullanır.
`trace_span` hedefli bir sonraki aksiyon, bu paketten bir `span_id`
adlandırır. O span'i okumak için span rotasını span'in `project_id`,
`environment` ve `release` değerleriyle gönderin.
### Span incelemesi yanıtı
Bir izdeki tek bir işlemi okumak için
`GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`
kullanın. `project_id`, `environment` ve `release` gönderin. Üçü de
zorunludur. Bunları seçilen span'den kopyalayın. Span satırının `id` değerini
`span_id` olarak göndermeyin.
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/spans/$SPAN_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "project_id=$PROJECT_ID" \
--data-urlencode "environment=production" \
--data-urlencode "release=checkout@1.2.3"
```
Bu yapay yanıt, iz örneğindeki başarısız istemci span'ini anlatır. Bir hata
logu aynı span kimliğine sahiptir. Span, saklanan benzer
span'lerin yaklaşık 95. yüzdelik değerinden uzun sürmüştür.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "span",
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"span_id": "53995c3f42cd8ad8",
"parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-08-03T11:05:00.100Z",
"duration_ms": 900,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"content_trust": "untrusted_telemetry"
},
"context": null,
"payload": {
"metadata": {
"values": {"provider": "example-pay"},
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"events": [],
"links": [],
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "error_evidence",
"causality": "evidence_only",
"observations": ["subject_error", "exact_span_error_log", "subject_at_or_above_peer_p95"]
},
"topology": {
"status": "available",
"root": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"parent": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"ancestors": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
}
],
"children": [],
"descendant_count": 0,
"cross_service_edges": [],
"parent_chain_status": "complete",
"truncated": false
},
"baseline": {
"status": "available",
"since": "2026-08-02T11:05:00.100Z",
"until": "2026-08-03T11:05:00.100Z",
"dimensions": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
"release": "checkout@1.2.3", "service_name": "checkout-api",
"operation": "http.client", "name": "POST /v1/charges"
},
"retained_peer_count": 40,
"error_peer_count": 2,
"error_rate_basis_points": 500,
"p50_duration_ms": 310.0,
"p95_duration_ms": 620.0,
"p99_duration_ms": 940.0,
"subject_percentile_basis_points": 9500,
"method": "approximate_t_digest",
"limitations": [
"retained_telemetry_only", "sampling_may_apply", "approximate_percentiles",
"same_release_only"
]
},
"correlations": {
"trace": {
"status": "available",
"summary": {
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"span_count": 2,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"root_span": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"slowest_child_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"slowest_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok",
"started_at": "2026-08-03T11:05:00Z", "duration_ms": 1200,
"service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"error_spans": [
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api", "span_count": 2, "error_span_count": 1,
"max_duration_ms": 1200
}
],
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"truncated": false
},
"issues": {"status": "not_found", "items": [], "truncated": false},
"logs": {
"status": "available",
"items": [
{
"id": "55555555-5555-4555-8555-555555555555",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
"source": "payments", "message": "Charge request failed",
"occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "53995c3f42cd8ad8:start", "kind": "span_start",
"occurred_at": "2026-08-03T11:05:00.100Z", "offset_ms": 0,
"name": "POST /v1/charges", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
"duration_ms": 900
},
{
"id": "55555555-5555-4555-8555-555555555555", "kind": "log",
"occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "payments",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
"status": null, "duration_ms": null
},
{
"id": "53995c3f42cd8ad8:end", "kind": "span_end",
"occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "POST /v1/charges",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": null,
"status": "error", "duration_ms": 900
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"attributes.metadata.provider", "baseline", "correlations.actions",
"correlations.issues", "correlations.logs", "correlations.metrics",
"correlations.trace", "subject.content_trust", "subject.deployment",
"subject.identity", "subject.sdk", "subject.timing", "topology"
],
"missing_fields": ["context"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_parent_span", "target": "span_investigation",
"reason": "parent_context_available", "span_id": "b7ad6b7169203331", "issue_id": null
},
{
"priority": 2, "code": "review_exact_span_logs", "target": "telemetry_logs",
"reason": "exact_span_logs_available", "span_id": "53995c3f42cd8ad8",
"issue_id": null
},
{
"priority": 3, "code": "inspect_trace", "target": "trace_investigation",
"reason": "trace_context_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 4, "code": "compare_peer_baseline", "target": "peer_baseline",
"reason": "subject_latency_elevated", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 5, "code": "compare_release", "target": "release_investigation",
"reason": "exact_release_available", "span_id": null, "issue_id": null
},
{
"priority": 6, "code": "improve_capture", "target": "sdk_capture",
"reason": "capture_incomplete", "span_id": "53995c3f42cd8ad8", "issue_id": null
}
]
}
```
| Alan | Anlamı |
| - | - |
| `payload` | Span `metadata` değeri, en fazla 8 `events` ve en fazla 8 `links`. Hepsi tek bir 64 değerlik bütçeyi paylaşır. |
| `analysis.observations` | `subject_error`, `child_error`, `exact_span_error_log`, `related_issue`, `subject_at_or_above_peer_p95` veya `subject_at_or_above_peer_p99`. |
| `topology` | `root`, `parent`, `ancestors`, doğrudan `children`, `descendant_count` ve `cross_service_edges`. |
| `topology.parent_chain_status` | `root`, `complete`, `missing`, `cycle`, `truncated` veya `unavailable`. |
| `baseline` | Aynı proje, ortam, sürüm, hizmet, işlem ve ada sahip daha önceki span'ler. |
| `correlations.logs` | Aynı iz kimliğine ve span kimliğine sahip loglar. |
| `correlations.issues`, `actions`, `metrics` | Aynı proje, ortam ve sürümde aynı iz kimliğine sahip sinyaller. |
| `timeline[].offset_ms` | Span başlangıcından itibaren milisaniye. Negatif bir değer span'den öncedir. |
Temel karşılaştırma, span başlangıcından önceki 24 saati okur. `since`
dâhildir, `until` hariçtir. `error_rate_basis_points: 500`, %5 anlamına
gelir. `subject_percentile_basis_points: 9500`, saklanan benzer span'lerin
%95'inin bu span'den uzun sürmediği anlamına gelir. Yüzdelikler yaklaşıktır.
`baseline.limitations` değerini bu değerlerle birlikte tutun. `not_found`
olan bir temel karşılaştırmada saklanan benzer span yoktur. `unavailable`
olan bir temel karşılaştırma sıfır sayı değil, başarısız bir okumadır.
`parent_chain_status: "complete"`, saklanan zincirin bir köke ulaştığı
anlamına gelir. LogBrew'ün isteğin her span'ini sakladığını kanıtlamaz.
Topoloji en fazla 64 üst öğe, 50 doğrudan alt öğe ve hizmetler arası 50
bağlantı döndürür.
| HTTP | `error` | Kurtarma |
| - | - | - |
| `422` | `trace_id must be a non-zero 32-character hexadecimal value` | `trace_id` değerini bir LogBrew iz yanıtından kopyalayın. |
| `422` | `span_id must be a non-zero 16-character hexadecimal value` | `span_id` değerini bir LogBrew iz yanıtından kopyalayın. |
| `422` | `environment and release must be non-empty exact span scope values` | Kapsamı seçilen span'den kopyalayın. |
| `422` | `invalid query parameters` | `project_id`, `environment` ve `release` gönderin. Başka anahtar göndermeyin. |
| `404` | `span not found` | Kimlikleri, projeyi, ortamı ve sürümü kontrol edin. |
### Log incelemesi yanıtı
Tek bir logu ve ilişkili kanıtlarını okumak için
`GET /api/logs/{log_id}/investigation` kullanın. Bu rotanın sorgu anahtarı
yoktur. Log kimliğini bir log listesinden kopyalayın.
```bash theme={null}
curl --fail-with-body -sS \
"https://api.logbrew.co/api/logs/$LOG_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN"
```
Okuma, log listesinin filtreleri dışında kalan kanıtları da döndürebilir.
İlişkili okumalar logun projesini, ortamını ve sürümünü ve logdan 5 dakika
önce ve sonrasını kullanır. Yakındaki loglar aynı hizmeti de kullanır. Bunlar
için iz kimliği gerekmez. Tam iz okumaları logun iz kimliğini gerektirir ve
başka hizmetleri de içerebilir. İz özeti aynı iz kimliğini ve kapsamı, zaman
aralığı olmadan kullanır.
Bu yapay yanıtta iz bağlamı olmayan bir uyarı logu ve yakındaki bir log
vardır. Yanıt zaman damgalarından bir iz bağlantısı oluşturmaz.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "log",
"id": "66666666-6666-4666-8666-666666666666",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"severity": "warning",
"content_trust": "untrusted_telemetry",
"source": "inventory",
"message": "Inventory update delayed",
"occurred_at": "2026-08-03T12:00:00Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"}
},
"context": null,
"attributes": {
"values": {"retry_count": 2},
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "warning_evidence",
"causality": "evidence_only",
"observations": ["subject_warning"]
},
"correlations": {
"trace": {
"status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
"summary": null, "truncated": false
},
"issues": {"status": "not_linked", "items": [], "truncated": false},
"trace_logs": {"status": "not_linked", "items": [], "truncated": false},
"nearby_logs": {
"status": "available",
"items": [
{
"id": "77777777-7777-4777-8777-777777777777",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "info",
"source": "inventory", "message": "Inventory retry started",
"occurred_at": "2026-08-03T11:59:58Z", "service_name": "checkout-api",
"trace_id": null, "span_id": null, "environment": "production",
"release": "checkout@1.2.3", "relationship": "nearby_scope"
}
],
"truncated": false
},
"actions": {"status": "not_linked", "items": [], "truncated": false},
"metrics": {"status": "not_linked", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "77777777-7777-4777-8777-777777777777", "kind": "log",
"relationship": "nearby_scope", "occurred_at": "2026-08-03T11:59:58Z",
"name": "inventory", "message": "Inventory retry started",
"service_name": "checkout-api", "span_id": null, "severity": "info", "status": null,
"duration_ms": null
},
{
"id": "66666666-6666-4666-8666-666666666666", "kind": "log",
"relationship": "subject", "occurred_at": "2026-08-03T12:00:00Z",
"name": "inventory", "message": "Inventory update delayed",
"service_name": "checkout-api", "span_id": null, "severity": "warning",
"status": null, "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"attributes", "attributes.retry_count", "correlations.nearby_logs",
"correlations.release", "subject.content_trust", "subject.environment", "subject.id",
"subject.message", "subject.occurred_at", "subject.project_id", "subject.release",
"subject.sdk.name", "subject.sdk.version", "subject.service_name", "subject.severity",
"subject.source", "timeline"
],
"missing_fields": ["context", "correlations.trace.trace_id"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "review_nearby_logs", "target": "telemetry_logs",
"reason": "nearby_logs_available", "issue_id": null, "trace_id": null,
"span_id": null
},
{
"priority": 2, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_investigation",
"reason": "release_identity_available", "issue_id": null, "trace_id": null,
"span_id": null
}
]
}
```
| Alan | Anlamı |
| - | - |
| `attributes` | Sınırlandırılmış yapılandırılmış öznitelikler. `values`, en üst düzeydeki `context` alanında bulunan `context` değerini içermez. |
| `analysis.status` | `critical_evidence`, `error_evidence`, `warning_evidence` veya `no_failure_observed`. |
| `correlations.trace` | İz kimliği, span kimliği, `exact_span` ve iz `summary` değeri. |
| `correlations.trace_logs` | Aynı iz kimliğine sahip loglar. `relationship` değeri `exact_trace` olur. |
| `correlations.nearby_logs` | Aralıktaki aynı hizmete ait loglar. `relationship` değeri `nearby_scope` olur. İncelenen logu ve tam iz loglarını içermez. |
| `correlations.issues`, `actions`, `metrics` | Aynı iz kimliğine sahip sinyaller. |
| `correlations.release` | Sürüm incelemesi için sürüm kapsamı. Bir karşılaştırma içermez. |
| `timeline[].relationship` | `subject`, `exact_span`, `exact_trace` veya `nearby_scope`. |
İz durumu `not_found` veya `unavailable` olduğunda da iz kimliği bulunabilir.
Kullanılabilir bir iz özeti, `exact_span` olacağını garanti etmez.
### Aksiyon incelemesi yanıtı
Tek bir ürün aksiyonunu, bildirilen durumunu ve ilişkili kanıtlarını okumak
için `GET /api/telemetry/actions/{action_id}/investigation` kullanın. Bu
rotanın sorgu anahtarı yoktur. İlişkili okumalar, log incelemesiyle aynı
aralığı ve kapsamları kullanır.
```bash theme={null}
curl --fail-with-body -sS \
"https://api.logbrew.co/api/telemetry/actions/$ACTION_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN"
```
`correlations`, `timeline` ve `next_actions`, log incelemesinin yapılarını
kullanır. İlişkili aksiyonlar incelenen aksiyonu içermez.
Bu yapay yanıt, giriş yapmış bir kullanıcının başarısız bir ödeme aksiyonunu
anlatır. Aksiyonun iz kimliği yoktur.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "action",
"id": "14141414-1414-4141-8141-141414141414",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "checkout.submit",
"status": "failure",
"content_trust": "untrusted_telemetry",
"occurred_at": "2026-08-03T11:05:00Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"subject_classification": "user",
"session_captured": true
},
"context": null,
"properties": {
"values": {"plan": "team", "step": "payment"},
"included_leaf_count": 2,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "subject_failure",
"causality": "evidence_only",
"observations": ["subject_failure"]
},
"correlations": {
"trace": {
"status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
"summary": null, "truncated": false
},
"issues": {"status": "not_linked", "items": [], "truncated": false},
"trace_logs": {"status": "not_linked", "items": [], "truncated": false},
"nearby_logs": {"status": "not_found", "items": [], "truncated": false},
"actions": {"status": "not_linked", "items": [], "truncated": false},
"metrics": {"status": "not_linked", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "14141414-1414-4141-8141-141414141414", "kind": "action",
"relationship": "subject", "occurred_at": "2026-08-03T11:05:00Z",
"name": "checkout.submit", "message": null, "service_name": "checkout-api",
"span_id": null, "severity": null, "status": "failure", "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"correlations.nearby_logs", "correlations.release", "properties.metadata",
"properties.metadata.plan", "properties.metadata.step", "subject.content_trust",
"subject.environment", "subject.id", "subject.name", "subject.occurred_at",
"subject.project_id", "subject.release", "subject.sdk.name", "subject.sdk.version",
"subject.service_name", "subject.session_captured", "subject.status",
"subject.subject_classification", "timeline"
],
"missing_fields": ["context", "correlations.trace.trace_id"],
"redacted_fields": ["subject.distinct_id", "subject.session_id"],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_analytics_paths", "target": "analytics_paths",
"reason": "session_captured", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 2, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_investigation",
"reason": "release_identity_available", "issue_id": null, "trace_id": null,
"span_id": null
}
]
}
```
| Alan | Anlamı |
| - | - |
| `subject.status` | `queued`, `running`, `success`, `failure` veya desteklenen bir durum yakalanmadıysa `null`. |
| `subject.subject_classification` | `user`, `anonymous`, `legacy_unknown`, `missing`, `historical_unindexed` veya `unsupported`. |
| `subject.session_captured` | Aksiyonun bir oturumu olup olmadığı. Yanıt oturum kimliğini hiçbir zaman döndürmez. |
| `properties` | Aksiyonun sınırlandırılmış `metadata` nesnesi. |
| `analysis.status` | `subject_failure`, `correlated_failure_evidence`, `in_progress`, `success_observed` veya `status_not_captured`. |
Yanıt hiçbir zaman özne veya oturum tanımlayıcısı döndürmez. Kanıt kaydı
`subject.distinct_id` değerini her zaman gizlenmiş olarak listeler. Oturum
yakalandıysa `subject.session_id` değerini de listeler. Bu yüzden her aksiyon
paketi `partial` olur ve `improve_capture` içerir. Bunu karşılamak için
gizlilik denetimlerini kaldırmayın.
### Metrik incelemesi yanıtı
Tek bir projede ve zaman aralığında tek bir metrik adını okumak için
`GET /api/telemetry/metrics/investigation` kullanın. Yanıtta güncel seri, eşit
uzunluktaki önceki aralıkla bir karşılaştırma, en son ölçüm örneği, iz
örnekleri ve tamamlanmış dağıtımlar bulunur. Sürüm 2, saklanan en son ölçüm
örneğinden metrik açıklamasını ekler. Sürüm 1 her zaman
`description_status: "not_captured"` bildirir.
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/metrics/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "project_id=$PROJECT_ID" \
--data-urlencode "name=http.server.duration" \
--data-urlencode "since=2026-08-02T12:00:00Z" \
--data-urlencode "until=2026-08-03T12:00:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "group_by=service_name" \
--data-urlencode "environment=production" \
--data-urlencode "series_limit=12" \
--data-urlencode "response_version=2"
```
`project_id`, `name` ve `since` zorunludur. `since` dâhildir, `until`
hariçtir. `until` varsayılan olarak şimdiki zamandır. Karşılaştırma, eşit
uzunluktaki önceki aralığı da okur.
Bu yapay histogramda 5 dakikalık iki zaman diliminde 5 ölçüm örneği vardır.
En son zaman diliminin p95 değeri 48 ms'dir. Önceki aralığın en son zaman
diliminin p95 değeri 24 ms'dir.
```json theme={null}
{
"schema_version": 2,
"subject": {
"kind": "metric", "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "http.server.duration", "description_status": "captured",
"description": "Duration of one completed server request."
},
"query": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "name": "http.server.duration",
"since": "2026-08-02T12:00:00Z", "until": "2026-08-03T12:00:00Z", "interval": "5m",
"interval_seconds": 300, "group_by": "service_name", "environment": "production",
"series_limit": 12
},
"purpose": "Explains one metric's latest application-supplied description and bounded change, compares the immediately preceding equal window, exposes one privacy-bounded latest-sample capture context, exact trace/span exemplars, and nearby completed deployments, and keeps every correlation evidence-only rather than claiming an anomaly or root cause.",
"content_trust": "untrusted_telemetry",
"analysis": {
"status": "change_observed",
"causality": "evidence_only",
"focus": {
"comparison_index": 0, "selection": "largest_absolute_relative_change",
"direction": "increased", "absolute_change": 24.0, "relative_change_percent": 100.0
}
},
"coverage": {
"samples": 5, "series": 1, "returned_series": 1, "points": 2,
"expected_buckets_per_series": 288, "first_seen_at": "2026-08-03T11:00:10Z",
"last_seen_at": "2026-08-03T11:09:50Z", "truncated": false
},
"series": [
{
"identity": {
"kind": "histogram", "unit": "ms", "temporality": "delta",
"group_by": "service_name", "group_value": "checkout-api"
},
"status": "ready",
"aggregation": {
"code": "distribution_p95",
"description": "Primary value is the approximate p95 of raw observations in each bucket; p50, p99, range, average, count, and sum preserve distribution context."
},
"sample_count": 5,
"points": [
{
"bucket_start": "2026-08-03T11:00:00Z", "bucket_end": "2026-08-03T11:05:00Z",
"sample_count": 2, "value": 42.0, "min": 42.0, "max": 42.0, "average": 42.0,
"sum": 84.0, "p50": 42.0, "p95": 42.0, "p99": 42.0, "trace_exemplars": []
},
{
"bucket_start": "2026-08-03T11:05:00Z",
"bucket_end": "2026-08-03T11:10:00Z",
"sample_count": 3,
"value": 48.0,
"min": 48.0,
"max": 48.0,
"average": 48.0,
"sum": 144.0,
"p50": 48.0,
"p95": 48.0,
"p99": 48.0,
"trace_exemplars": ["4bf92f3577b34da6a3ce929d0e0e4736"]
}
]
}
],
"comparison": {
"status": "available",
"method": "adjacent_equal_window_latest_bucket",
"previous_since": "2026-08-01T12:00:00Z",
"previous_until": "2026-08-02T12:00:00Z",
"items": [
{
"identity": {
"kind": "histogram", "unit": "ms", "temporality": "delta",
"group_by": "service_name", "group_value": "checkout-api"
},
"aggregation": "distribution_p95",
"current": {
"bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:10:00Z",
"sample_count": 3, "value": 48.0
},
"previous": {
"bucket_start": "2026-08-02T11:55:00Z", "bucket_end": "2026-08-02T12:00:00Z",
"sample_count": 2, "value": 24.0
},
"direction": "increased",
"absolute_change": 24.0,
"relative_change_percent": 100.0
}
],
"truncated": false,
"limitation": "Each item compares the latest non-empty semantic bucket in adjacent equal-length windows. It is an observed value change, not seasonality-aware anomaly detection or evidence that a deployment caused the change."
},
"latest_sample": {
"status": "available",
"sample": {
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"kind": "histogram",
"value": 48.0,
"unit": "ms",
"temporality": "delta",
"occurred_at": "2026-08-03T11:09:50Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"metadata": {"values": {}, "included_leaf_count": 0, "redacted": false, "truncated": false}
}
},
"exemplars": {
"status": "available",
"coverage": {
"matching_samples": 5, "trace_linked_samples": 1, "span_linked_samples": 1,
"returned_exemplars": 1
},
"items": [
{
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"value": 48.0,
"occurred_at": "2026-08-03T11:09:50Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"}
}
],
"truncated": false
},
"deployments": {
"status": "available",
"items": [
{
"deployment_id": "deploy-123", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api", "status": "succeeded",
"started_at": "2026-08-03T11:02:00Z", "finished_at": "2026-08-03T11:03:00Z",
"commit_sha": "0123456789abcdef"
}
],
"truncated": false
},
"timeline": {
"items": [
{
"id": "deploy-123", "kind": "deployment_finished",
"occurred_at": "2026-08-03T11:03:00Z", "value": null, "trace_id": null,
"span_id": null, "release": "checkout@1.2.3", "service_name": "checkout-api"
},
{
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "kind": "metric_exemplar",
"occurred_at": "2026-08-03T11:09:50Z", "value": 48.0,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"release": "checkout@1.2.3", "service_name": "checkout-api"
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"metric.current_window_coverage", "metric.deployment_overlays", "metric.description",
"metric.identity", "metric.latest_sample", "metric.latest_sample.kind",
"metric.latest_sample.occurred_at", "metric.latest_sample.scope",
"metric.latest_sample.sdk.name", "metric.latest_sample.sdk.version",
"metric.latest_sample.span_id", "metric.latest_sample.trace_id",
"metric.latest_sample.value", "metric.prior_window_comparison", "metric.query_scope",
"metric.series_semantics", "metric.span_exemplars", "metric.trace_exemplars"
],
"missing_fields": ["metric.latest_sample.context", "metric.latest_sample.metadata"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1,
"code": "inspect_exact_span",
"target": "span_investigation",
"reason": "Inspect the exact span that emitted a retained metric exemplar, then review its failure, latency, log, issue, action, and trace evidence.",
"context": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"environment": "production", "release": "checkout@1.2.3",
"service_name": "checkout-api"
}
},
{
"priority": 2,
"code": "review_deployment",
"target": "release_investigation",
"reason": "Review release-scoped telemetry for a completed deployment inside the compared evidence window without treating temporal proximity as causality.",
"context": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "trace_id": null,
"span_id": null, "environment": "production", "release": "checkout@1.2.3",
"service_name": "checkout-api"
}
}
]
}
```
| Alan | Anlamı |
| - | - |
| `subject.description_status` | `captured`, `not_captured` veya `unavailable`. |
| `query` | Normalleştirilmiş sorgu. `service_name`, `release` ve `environment` yalnızca gönderildiyse görünür. |
| `analysis.status` | `no_samples`, `change_observed`, `no_change_observed`, `baseline_not_found` veya `comparison_unavailable`. |
| `analysis.focus` | Göreli değişimi en büyük olan karşılaştırma öğesi. Göreli değişim yoksa mutlak değişimi en büyük olan öğe. Karşılaştırılabilir öğe yoksa `null`. |
| `series[].aggregation.code` | `gauge_last`, `delta_sum`, `distribution_p95`, `raw_cumulative_last` veya `raw_last`. |
| `comparison.status` | `available`, `partial`, `not_found`, `unavailable` veya `no_current_samples`. |
| `comparison.items[]` | Aynı seri kimliği için her aralığın en son boş olmayan zaman dilimi. |
| `latest_sample` | SDK, `context`, `metadata` ve iz bağlantısıyla birlikte en son ham ölçüm örneği. |
| `exemplars` | İz kimliği olan ham ölçüm örnekleri. `coverage` bağlı ölçüm örneklerini sayar. |
| `deployments` | Önceki aralığın başlangıcından `until` zamanına kadar tamamlanan dağıtımlar. |
| `next_actions[]` | `code`, `target`, düz metin bir `reason` ve sonraki okuma için bir `context` kapsamı. |
`relative_change_percent`, `(current - previous) / abs(previous) * 100`
değeridir. Önceki değer sıfır veya eksikse `null` olur.
`expected_buckets_per_series` veri içeren zaman dilimlerini değil, olası zaman
dilimlerini sayar. Boş zaman dilimlerini sıfır olarak çizmeyin. Bir değişikliğe
yakın bir dağıtım, değişikliğe o dağıtımın yol açtığını kanıtlamaz.
Hesabın okuyamadığı bir proje `404` değil,
`analysis.status: "no_samples"` ile `200 OK` döndürür. Boş bir sonuç diğer
sinyal türleri hakkında bilgi vermez.
Metrik sınırları: Aralık en fazla 31 gündür. Her seride en fazla 500 zaman
dilimi olur. `series_limit` 1 ile 20 arasındadır, varsayılan 10'dur. Yanıt en
fazla 20 iz örneği ve 20 dağıtım döndürür.
| HTTP | `error` | Kurtarma |
| - | - | - |
| `422` | `metric investigation response_version must be 1 or 2` | `response_version` göndermeyin veya `2` gönderin. |
| `422` | `metric series project_id is required` | Okunabilir tek bir proje kimliği gönderin. |
| `422` | `metric series name is required` | Adı metrik listesinden kopyalayın. |
| `422` | `metric series since is required` | `24h` gibi bir değer veya bir RFC 3339 zaman damgası gönderin. |
| `422` | `metric series range must not exceed 31 days` | Daha kısa bir aralık kullanın. |
| `422` | `metric series interval would exceed 500 buckets` | `interval=auto` veya daha geniş bir aralık kullanın. |
| `422` | `metric series_limit must be between 1 and 20` | 1 ile 20 arasında bir değer gönderin. |
`interval` değeri `auto`, `1m`, `5m`, `15m`, `1h`, `6h` veya `1d` olur.
`group_by` değeri `none`, `service_name`, `release` veya `environment` olur.
Diğer değerler `422` döndürür.
### İnceleme hataları
| HTTP | Rota | `error` |
| - | - | - |
| `404` | Log | `log not found` |
| `404` | Aksiyon | `action not found` |
| `404` | İz | `trace not found` |
| `422` | İz | `trace investigation response_version must be 1, 2, or 3` |
| `400` | Log, aksiyon, sorun | Yol kimliği bir UUID değilse `invalid URL path parameters` |
| `422` | Sorun, iz, span, metrik | Bilinmeyen bir anahtar veya yanlış türde bir değer için `invalid query parameters` |
`404`, okunabilir hiçbir projede kaydın olmadığı anlamına gelir. Her rota
geçerli kimlik doğrulama olmadan `401`, `GET` dışındaki bir yöntem için `405`
de döndürür.
[Bulunamadı](/tr/reference/api-errors#resource-not-found),
[yol](/tr/reference/api-errors#invalid-path-value),
[kimlik doğrulama](/tr/reference/api-errors#authentication-failure) ve
[yöntem](/tr/reference/api-errors#unsupported-method) yanıtları için
[API hataları](/tr/reference/api-errors) sayfasına bakın.
İsteğe bağlı bir kanıt okuması `200 OK` yanıtının içinde başarısız olabilir.
Bu durumda koleksiyon `unavailable` bildirir. Bunu `not_found` veya sıfır
kayıt olarak göstermeyin.
## Önem düzeyi değerleri
Kullanıcıya gösterilen önem düzeyi değerleri `info`, `warning`, `error` ve
`critical` olur. SDK'lar ve çalışma ortamları `trace`, `debug`, `warn` veya
`fatal` gibi yaygın eş adlar gönderebilir. REST ve canlı yanıtlar her zaman
standart değeri döndürür. Örneğin LogBrew girdi olarak `warn` kabul eder ve
`warning` döndürür. Veri alımı bilinmeyen önem düzeyi değerlerini reddeder.
| Eş ad | Standart değer |
| - | - |
| `trace`, `debug` | `info` |
| `warn` | `warning` |
| `fatal` | `critical` |
## Önem düzeyi kuralı yanıtları
Önem düzeyi kuralı, LogBrew'ün bir logu veya sorunu nasıl gösterdiğini
değiştirir. Uygulamanın yakaladığı önem düzeyini değiştirmez. Loglar ve
sorunlar bir `triage` nesnesi döndürür:
| Alan | Anlamı |
| - | - |
| `effective_severity` | Gösterilecek önem düzeyi. Kural yoksa `severity` değerine eşittir. |
| `ignored` | Bir log kuralı logu yok sayıyorsa veya sorun arşivlenmişse `true`. |
| `rule_applied` | Bir önem düzeyi kuralı veya yok sayılma durumu uygulanıyorsa `true`. `false` varsayılandır, eksik veri değildir. |
Gösterim için `triage.effective_severity` kullanın. `severity` değerini
yakalanan değer olarak koruyun. Log listesi varsayılan olarak yok sayılan
logları içermez. Onları da almak için `GET /api/logs` üzerinde
`status=ignored` veya `status=all` gönderin.
Hesabın projedeki sorunları yönetme izni olmalıdır. Okuma erişimi yeterli
değildir. Bu izin olmadan kural değişikliği `code: forbidden` ile `403`
döndürür.
### Log kuralını değiştirin
`PUT /api/logs/{log_id}/triage-rule`, kuralı bu log ve aynı imzaya sahip
sonraki loglar için ayarlar. Gövdede hem `severity` hem `ignored`
bulunmalıdır:
```bash theme={null}
curl --request PUT "https://api.logbrew.co/api/logs/$LOG_ID/triage-rule" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--header "Content-Type: application/json" \
--data '{ "severity": "info", "ignored": true }'
```
`200 OK` yanıtı [logun](#log-response) tamamını içerir. Logun `severity`
değeri `warning` olarak kalır. `triage` alanı kuralı gösterir:
```json theme={null}
{
"severity": "warning",
"triage": {
"effective_severity": "info",
"ignored": true,
"rule_applied": true
}
}
```
Bu alıntı yalnızca değişen alanları gösterir. İstekteki `severity` değeri
`source`, `info`, `warning`, `error` veya `critical` olur. `source`,
yakalanan önem düzeyini geri getirir. Yok sayılan bir logu etkin yapmaz. Logu
yeniden göstermek için `"ignored": false` gönderin.
### Sorun kuralını değiştirin
`PUT /api/telemetry/issues/{issue_id}/triage-rule`, gruplanmış bir sorunun ve
sonraki oluşumlarının gösterilen önem düzeyini ayarlar. Gövde yalnızca
`severity` kabul eder:
```bash theme={null}
curl --request PUT "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/triage-rule" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--header "Content-Type: application/json" \
--data '{ "severity": "warning" }'
```
`200 OK` yanıtı, sürüm 1'deki [sorunun](#issue-response) tamamını içerir.
Yakalanan `severity` ve `status` değerleri değişmez:
```json theme={null}
{
"severity": "error",
"status": "unresolved",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": true
}
}
```
Bu alıntı alanların yalnızca bir kısmını gösterir. Kural bir sorunu çözmez,
arşivlemez veya yeniden açmaz. Bunun için
[durum değişikliğini](#issue-status-response-examples) kullanın. Türetilen
öncelik yeni uygulanan önem düzeyini izler. Görmek için sorunu
`response_version=2` veya `3` ile okuyun.
Desteklenmeyen bir önem düzeyi `422` döndürür:
```json theme={null}
{
"error": "triage severity must be source, info, warning, error, or critical",
"code": "validation_failed",
"next": "use source to restore captured severity, or choose info, warning, error, or critical",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
Bir sorun kuralındaki `status` gibi bilinmeyen bir gövde alanı
`code: invalid_json` ile `422` döndürür. Eksik veya okunamayan bir log ya da
sorun `code: not_found` ile `404` döndürür. Yanıt kaybolursa kuralı yeniden
göndermeden önce logu veya sorunu yeniden okuyun.
## Hata yanıt biçimi
LogBrew API hataları bir JSON zarfı döndürür. Bu örnek reddedilen bir isteği
gösterir. `error` ve `next` metni soruna göre değişir:
```json theme={null}
{
"error": "",
"code": "validation_failed",
"next": "",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
Program dalları için `code`, otomasyon için `next_action` kullanın. `error` ve
`next` değerlerini kişilere düz metin olarak gösterin. İfadelerini
ayrıştırmayın. Bazı hatalar `limit`, `reset_at` veya `retry_after_seconds`
gibi alanlar ekler. JSON gövdesi olmayan bir yanıtta LogBrew `code` değeri
yoktur. Tüm kodlar için [API hataları](/tr/reference/api-errors) sayfasına
bakın.
## CLI ile veri okuyun
CLI aynı rotaları okur ve `--json` ile aynı JSON'u döndürür. Geniş başlayın,
ardından daraltın:
```bash theme={null}
logbrew read releases --environment production --json
logbrew read issues --release api@1.2.3 --status unresolved --json
logbrew read logs --release api@1.2.3 --since 24h --json
logbrew read actions --name checkout_failed --since 24h --json
logbrew read traces --status error --since 24h --json
logbrew read trace --json
```
Cursor zarfını almak için `--pagination cursor` ekleyin. CLI sorun yanıtı
sürüm 4'ü ister. [Sonraki sayfayı okuyun](/tr/reference/cli#read-the-next-page)
ve [Canlı izleme](/tr/reference/cli#live-watch) bölümlerine bakın.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.