API yanıt biçimi ve JSON yanıt örnekleri

Bu sayfa, Telemetri API’sinin her yanıt ailesi için bir örnek gösterir. Tüm değerler yapaydır. Hata kodları ve kurtarma için API hataları sayfasına bakın.

Yanıtı okuyun

Her yanıtı şu sırayla okuyun:

HTTP durumunu okuyun.
Gövdenin, rotanın kendi yapısında olduğundan emin olun.
Her project_id değerinin istenen proje kapsamında olduğundan emin olun.
Standart enum değerlerini ve kimlikleri değiştirmeden koruyun.
next_action alanını yalnızca istemci onun code ve target değerlerini destekliyorsa izleyin.
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 ve Yakalanan verileri denetleyin 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:

{
  "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:

{
  "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 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:

{
  "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 bölümüne bakın.

Log yanıtı

limit=1 ile bir log cursor sayfası:

{
  "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ı 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:

{
  "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 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 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) 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`.

{
  "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:

{
  "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:

{
  "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=<project_id>, projede sorun atanabilecek tüm hesapları döndürür:

{
  "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ı

{
  "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 sayfasına bakın.

Metrik yanıtı

{
  "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ı

{
  "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 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:

{
  "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ı 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 ile `200`	`code: not_found` ile `404`
`GET /api/telemetry/issues/{issue_id}`	Tek bir sorun 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:

{
  "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:

{
  "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:

{
  "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ı 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:

{
  "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:

{
  "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 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 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.

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:

{
  "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 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:

{
  "issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
  "events": [],
  "next_cursor": null
}

Bir cursor’ı başka bir sorun için yeniden kullanmayın. Cursor hataları 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:

[
  {
    "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:

{
  "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.

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:

{
  "ticket": "<feed-ticket>",
  "expires_in_seconds": 60,
  "next": "connect with GET /api/feed/live?ticket=<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=<feed-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ı yapısında log verisi.
`native_issue`	Sürüm 1 sorun yanıtı yapısında gruplanmış sorun verisi.
`native_trace_span`	Span listesi öğesi yapısında tek bir span.
`native_action`	Aksiyon yanıtı 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ı yapısında hesap kullanımı.

{
  "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ı 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ı 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 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:

{
  "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:<team_id>`	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 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:

{
  "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 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:

{
  "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 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 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 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:

curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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.

{
  "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 sayfasına bakın.

Genel bakış hataları

Genel bakış, ortak kapsam hatalarına 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:

{
  "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ı:

{
  "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 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 ek olarak şu istekler 422 ve validation_failed döndürür. 2’den az veya 8’den fazla adım:

{
  "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:

{
  "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:

{
  "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.

{
  "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.

{
  "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:

{
  "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:

{
  "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 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:

{
  "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:

{
  "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.

{
  "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:

{
  "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:

{
  "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:

{
  "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 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:

{
  "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:

curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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.

{
  "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ı 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:

{
  "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:

{
  "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.

{
  "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.

{
  "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 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 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:

{
  "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 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.

curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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.

{
  "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 ek olarak limit=0 veya limit=51, 422 döndürür:

{
  "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:

{
  "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:

{
  "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.

{
  "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ı 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 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 aynıdır. Örneğin anahtarları farklı, filtreleri aynı iki segment şunu döndürür:

{
  "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:

{
  "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.

{
  "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:

{
  "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ı 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 <subject> --json kullanın. CLI paketi yazdırmadan önce doğrular. Telemetri API’si 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 rehberi, kanıtların hangi sırayla okunacağını gösterir. Sürüm 13’ü isteyin:

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.

Sürüm 13 sorun incelemesi örneği

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.

{
  "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:

{
  "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 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:

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.

Sürüm 3 iz incelemesi örneği

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.

{
  "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.

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"

Span incelemesi örneği

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.

{
  "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.

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.

Log incelemesi örneği

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.

{
  "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.

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.

Aksiyon incelemesi örneği

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.

{
  "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.

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.

Sürüm 2 metrik incelemesi örneği

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.

{
  "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ı, yol, kimlik doğrulama ve yöntem yanıtları için API hataları 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:

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 tamamını içerir. Logun severity değeri warning olarak kalır. triage alanı kuralı gösterir:

{
  "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:

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 tamamını içerir. Yakalanan severity ve status değerleri değişmez:

{
  "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 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:

{
  "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:

{
  "error": "<what is wrong>",
  "code": "validation_failed",
  "next": "<how to fix it>",
  "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ı 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:

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 <trace_id> --json

Cursor zarfını almak için --pagination cursor ekleyin. CLI sorun yanıtı sürüm 4’ü ister. Sonraki sayfayı okuyun ve Canlı izleme bölümlerine bakın.

​Yanıtı okuyun

​Ne göndermelisiniz

​Veri alımı yanıtı

​SDK toplu gönderim yanıtı

​Yerel zarf yanıtı

​Veri alımı hataları

​Telemetri listesi yanıt biçimi

​Log yanıtı

​Sorun yanıtı

​Sorumlu listesi yanıtı

​Aksiyon yanıtı

​Metrik yanıtı

​Sürüm yanıtı

​İz keşfi yanıtı

​Boş listeler ve eksik kayıtlar

​Reddedilen proje seçimleri

​Cursor hataları

​Sürüm cursor yanıtları

​İz keşfi hataları

​Sorun oluşum geçmişi

​İz span’leri ve özet yanıtları

​Span listesi

​İz özeti

​Eşleşen span yok

​Canlı olay yanıt biçimi

​Bilet oluşturun

​Bağlantıyı açın

​Mesajları okuyun

​Kapanan bağlantıyı ele alın

​Sorun durumu yanıt örnekleri

​Analiz isteği kapsamı

​Ortak kapsam hataları

​Ürün analizleri genel bakış yanıtı

​Başarılı genel bakış

​Genel bakışı okuyun

​Genel bakış hataları

​Sıralı dönüşüm hunisi yanıtı

​Başarılı dönüşüm hunisi

​Dönüşümü ve kapsama oranını okuyun

​Boş dönüşüm hunisi sonuçları

​Reddedilen dönüşüm hunisi istekleri

​Tam olay ve otomatik analiz

​Tam olay elde tutma isteği

​Başarılı tam olay elde tutma

​Elde tutmayı okuyun

​Otomatik elde tutma

​Uygun kullanıcı olmadan elde tutma

​Elde tutma hataları

​Tam olay yaşam döngüsü isteği

​Başarılı tam olay yaşam döngüsü

​Yaşam döngüsünü okuyun

​Otomatik yaşam döngüsü

​Kullanıcı olmadan yaşam döngüsü

​Yaşam döngüsü hataları

​Seçilen analiz kapsamını okuyun

​Metrik serisi yanıtı

​Başarılı metrik serisi

​Metrik serisini okuyun

​Metrik serisi kapsamı ve hataları

​Yol analizi yanıtı

​Başarılı yol analizi

​Yolları okuyun

​Çapayı özelliğe göre filtreleyin

​Boş yollar ve reddedilen istekler

​Analiz özellik kataloğu

​Kullanılabilir özellik anahtarlarını okuyun

​Başarılı özellik kataloğu

​Kataloğu yorumlayın

​Özellik kataloğu hataları

​Analiz segment karşılaştırması

​Karşılaştırmayı tanımlayın

​Başarılı segment karşılaştırması

​Oranları ve farkları okuyun

​Segment karşılaştırma hataları

​Sinyal hacmi yanıtı

​Sinyal sayıları

​Her sayıyı kendi biriminde okuyun

​Boş ve kısalmış aralıklar

​Reddedilen sinyal hacmi istekleri

​İnceleme yanıtları

Yanıtı okuyun

Ne göndermelisiniz

Veri alımı yanıtı

SDK toplu gönderim yanıtı

Yerel zarf yanıtı

Veri alımı hataları

Telemetri listesi yanıt biçimi

Log yanıtı

Sorun yanıtı

Sorumlu listesi yanıtı

Aksiyon yanıtı

Metrik yanıtı

Sürüm yanıtı

İz keşfi yanıtı

Boş listeler ve eksik kayıtlar

Reddedilen proje seçimleri

Cursor hataları

Sürüm cursor yanıtları

İz keşfi hataları

Sorun oluşum geçmişi

İz span’leri ve özet yanıtları

Span listesi

İz özeti

Eşleşen span yok

Canlı olay yanıt biçimi

Bilet oluşturun

Bağlantıyı açın

Mesajları okuyun

Kapanan bağlantıyı ele alın

Sorun durumu yanıt örnekleri

Analiz isteği kapsamı

Ortak kapsam hataları

Ürün analizleri genel bakış yanıtı

Başarılı genel bakış

Genel bakışı okuyun

Genel bakış hataları

Sıralı dönüşüm hunisi yanıtı

Başarılı dönüşüm hunisi

Dönüşümü ve kapsama oranını okuyun

Boş dönüşüm hunisi sonuçları

Reddedilen dönüşüm hunisi istekleri

Tam olay ve otomatik analiz

Tam olay elde tutma isteği

Başarılı tam olay elde tutma

Elde tutmayı okuyun

Otomatik elde tutma

Uygun kullanıcı olmadan elde tutma

Elde tutma hataları

Tam olay yaşam döngüsü isteği

Başarılı tam olay yaşam döngüsü

Yaşam döngüsünü okuyun

Otomatik yaşam döngüsü

Kullanıcı olmadan yaşam döngüsü

Yaşam döngüsü hataları

Seçilen analiz kapsamını okuyun

Metrik serisi yanıtı

Başarılı metrik serisi

Metrik serisini okuyun

Metrik serisi kapsamı ve hataları

Yol analizi yanıtı

Başarılı yol analizi

Yolları okuyun

Çapayı özelliğe göre filtreleyin

Boş yollar ve reddedilen istekler

Analiz özellik kataloğu

Kullanılabilir özellik anahtarlarını okuyun

Başarılı özellik kataloğu

Kataloğu yorumlayın

Özellik kataloğu hataları

Analiz segment karşılaştırması

Karşılaştırmayı tanımlayın

Başarılı segment karşılaştırması

Oranları ve farkları okuyun

Segment karşılaştırma hataları

Sinyal hacmi yanıtı

Sinyal sayıları

Her sayıyı kendi biriminde okuyun

Boş ve kısalmış aralıklar

Reddedilen sinyal hacmi istekleri

İnceleme yanıtları