API-responseformaat en voorbeelden van JSON-responses

Deze pagina toont één voorbeeld voor elk type response van de Telemetrie-API. Alle waarden zijn fictief. Zie API-fouten voor foutcodes en herstel.

Een response lezen

Lees elke response in deze volgorde:

Lees de HTTP-status.
Controleer of de body de vorm heeft die bij de route hoort.
Controleer of elk project_id binnen de gevraagde projectscope valt.
Laat canonieke enumwaarden en ID’s ongewijzigd.
Volg next_action alleen als de client de bijbehorende code en target ondersteunt.
Behandel null, een weggelaten veld en een lege lijst als verschillende toestanden.

Een 200 OK kan een lege lijst bevatten. Een lege loglijst betekent dat geen enkele log bij het request paste. Dat betekent niet dat issues, traces of acties ook leeg zijn. Koppel signalen niet omdat hun tijdstempels dicht bij elkaar liggen. Volg een trace alleen als de response het exacte trace_id ervan bevat. Een 404 en een lege lijst zijn verschillende resultaten. Een lijstroute geeft [] terug als geen enkel record overeenkomt. Een detailroute geeft 404 met code: not_found terug als die geen leesbaar record vindt. Geen van beide resultaten bewijst dat de opname is mislukt.

Wat je verstuurt

Een response is maar zo nuttig als de telemetrie die je verstuurt. Stuur deze waarden mee in elke envelop of SDK-installatie:

release en environment.
Vaste namen voor services, acties en metrics.
Tracecontext als logs, spans, acties en issues bij hetzelfde request horen.
Canonieke ernstwaarden: info, warning, error en critical.
Attributen die helpen bij debuggen, zonder geheimen of onnodige persoonsgegevens.

Zie SDK-integratie en Vastgelegde gegevens beheren.

Response van de ingest-API

De openbare SDK’s lezen de response van POST /v1/events voor je. Je applicatiecode hoeft die niet af te handelen.

Response op een SDK-batch

Een geslaagde SDK-batch geeft 200 OK terug met de geaccepteerde aantallen per stroom:

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

Veld	Betekenis
`issues`, `logs`, `trace_spans`, `actions`, `metrics`	Events uit deze batch die LogBrew heeft geaccepteerd.
`already_accepted`	Events waarvan LogBrew het ID eerder al accepteerde. LogBrew slaat ze niet opnieuw op.
`context_updated`	`true` als de batch de release- of omgevingscontext heeft bijgewerkt.

De aantallen gelden alleen voor deze batch. Stuur je een batch opnieuw die LogBrew al accepteerde, dan krijg je 0 voor elke stroom en het aantal events in already_accepted. Houd de oorspronkelijke event-ID’s aan als je het opnieuw probeert.

Response op een native envelop

POST /api/telemetry/ingest geeft 200 OK terug met het aantal geaccepteerde items per stroom:

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

De native response heeft geen veld metrics of context_updated. Voeg ze niet toe. already_accepted telt items waarvan LogBrew de id eerder al voor het project accepteerde. Zie de directe native envelop.

Opnamefouten

Een 401 met code: ingest_key_invalid betekent dat de ingest-bearer is ingetrokken, verlopen of niet geldig is voor het project. Op POST /v1/events geeft een ontbrekende bearer, of een bearer die geen ingest-sleutel is, 401 met code: unauthorized. Gebruik de huidige projectgebonden ingest-bearer. Probeer het niet opnieuw met een account-bearer. Een geweigerde SDK-batch geeft 422 met code: validation_failed:

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

Andere waarden van error zijn onder meer SDK event batch requires at least one event en SDK event type is not supported by this ingest route. Controleer de SDK-versie en de transportconfiguratie. Stuur geen lege batch. Wijzig geen eventtypes of ID’s alleen om een batch door de validatie te krijgen. Een request met een andere methode dan POST geeft 405 met code: method_not_allowed. Een onleesbare JSON-body geeft code: invalid_json.

Responseformaat van telemetrielijsten

Lijstroutes geven standaard een gewone JSON-array terug. Een geslaagde lege lijst is []. Met pagination=cursor geeft de route een envelop terug. De collectiesleutel hoort bij het signaal:

Route	Collectiesleutel
`/api/logs`	`logs`
`/api/telemetry/issues`	`issues`
`/api/telemetry/issues/{issue_id}/events`	`events`, met een `issue_id` op het hoogste niveau
`/api/telemetry/actions`	`actions`
`/api/telemetry/metrics`	`metrics`
`/api/telemetry/releases`	`releases`
`/api/telemetry/traces`	`traces`, met een `naming_quality` op het hoogste niveau

next_cursor is een object met de velden om verder te lezen, of null op de laatste pagina. Rijen staan van nieuw naar oud. Zie cursorpaginering.

Logresponse

Een cursorpagina met logs en limit=1:

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

Logs bevatten level voor compatibiliteit en severity voor weergave. Beide bevatten de canonieke waarde. triage bevat het resultaat van een ernstregel. Zie responses van ernstregels. trace_id en span_id zijn null als de log geen tracekoppeling heeft. Dan is next_action gelijk aan inspect_related_logs met als doel telemetry_logs. Logs, issues en acties gebruiken dezelfde 2 paren voor next_action. GET /api/logs/{log_id} geeft één log terug in dezelfde vorm.

Issueresponse

GET /api/telemetry/issues/{issue_id} geeft één gegroepeerd issue terug. De lijst geeft dezelfde objecten terug. Dit voorbeeld gebruikt de standaardversie 1 van de response:

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

In versie 1 is status gelijk aan unresolved, resolved of ignored. Voor een gearchiveerd issue is triage.ignored gelijk aan true. Zie Een issue onderzoeken voor de paren van next_action en de leesacties die erop volgen. first_seen_at en last_seen_at zijn de tijdstippen van het eerste en het meest recente voorval. Ze veranderen niet als de status verandert. Sommige velden verschijnen alleen als LogBrew de gegevens heeft:

Veld	Wanneer het verschijnt
`span_id`	Het issue heeft een spankoppeling. Anders laat de response het veld weg.
`diagnostics`	Het laatste voorval heeft een exceptiontype of breadcrumbs. Zie voorvalgeschiedenis van een issue.
`symbolication`	Alleen op `GET /api/telemetry/issues/{issue_id}`, als het issue de identiteit van een release-artefact heeft. Zie Source maps voor JavaScript.

symbolication.status is resolved, invalid_metadata, artifact_not_found, source_not_resolved of unavailable. De lijst, statuswijzigingen en regelwijzigingen geven geen symbolication terug. Met response_version=2 heeft het issue dezelfde velden, met deze wijzigingen:

Veld	Waarde in versie 2
`status`	`unresolved`, `resolved` of `archived`. Versie 1 toont `archived` als `ignored`.
`priority`	`high`, `medium` of `low`.
`priority_source`	`manual` als iemand de prioriteit heeft ingesteld. `derived` als de prioriteit de effectieve ernst volgt.

{
  "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
  "status": "archived",
  "severity": "error",
  "priority": "low",
  "priority_source": "manual"
}

Dit voorbeeld toont maar een deel van de velden. Een afgeleide prioriteit is high voor error en critical, medium voor warning en low voor info. Die prioriteit gebruikt triage.effective_severity, dus een ernstregel voor het issue kan die veranderen. Met response_version=3 heeft het issue alle velden van versie 2 en assignee. assignee is null als het issue aan niemand is toegewezen:

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

Veld	Betekenis
`assignee.user_id`	Gebruikers-ID van het toegewezen account. Stuur het als `assignee` in een filter of een wijziging.
`assignee.name`	Naam van dat account, of `null` als het account geen naam heeft.
`assignee.email`	E-mailadres van dat account.

Een issue toont geen toewijzing als het toegewezen lid het project niet meer kan lezen. Met response_version=4 heeft assignee ook type. Een toewijzing aan een account (user) heeft user_id, name en email, zoals in versie 3. Een toewijzing aan een team (team) heeft team_id, slug en name. Versie 3 toont een toewijzing aan een team als null. De CLI vraagt versie 4 op:

{
  "assignee": {
    "type": "team",
    "team_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "slug": "payments",
    "name": "Payments"
  }
}

Elke andere response_version geeft 422 met code: validation_failed. Een cursorpagina gebruikt dezelfde versie voor elk issue in issues.

Response met toewijsbare accounts en teams

GET /api/telemetry/issues/assignees?project_id=<project_id> geeft elk account terug waaraan je issues in het project kunt toewijzen:

{
  "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"
    }
  ]
}

Voeg response_version=2 toe om ook teams te krijgen: elk team van de organisatie van het project, met team_id, slug en name. Als het account het project niet kan lezen, geeft de route 404 met code: not_found.

Actieresponse

{
  "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 volgt één actor of sessie. Behandel distinct_id en session_id als ondoorzichtige ID’s. session_id en trace_id zijn null als ze ontbreken. span_id ontbreekt als er geen waarde is. Een actie heeft geen ernst. Zie Productevents vastleggen.

Metricresponse

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

Elk item is één meting. Gebruik het aantal metingen niet als aantal events of gebruikers. unit, temporality, trace_id en span_id zijn null als ze ontbreken. Een waarde null is geen nul.

Releaseresponse

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

Eén rij gaat over één project, release, omgeving en service. De aantallen beschrijven alleen die rij. trace_health.status is unknown als de rij geen traces heeft, en anders no_errors_observed of errors_observed. error_rate_basis_points is het aandeel traces met een foutspan, van 0 tot 10000. Het is geen foutpercentage voor alle requests. next_action wijst naar het eerste signaaltype met gegevens, in deze volgorde:

`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`

Zie Releases.

Response bij het zoeken naar traces

GET /api/telemetry/traces?pagination=cursor geeft één rij per trace terug, plus een overzicht in naming_quality voor de teruggegeven pagina:

{
  "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 gaat alleen over de teruggegeven pagina. Het is geen score voor het hele account. truncated: true betekent dat er nog een pagina is. Als de pagina een generieke naam, een niet-herkende route of een generieke bewerking bevat, is next_action gelijk aan improve_trace_naming met als doel sdk_configuration. Zonder pagination=cursor geeft de route een gewone array van traces terug, zonder naming_quality. next_cursor bevat time en trace_id. Stuur ze als cursor_time en cursor_trace_id. GET /api/telemetry/traces/{trace_id} geeft de spans van één trace terug. GET /api/telemetry/traces/{trace_id}/summary geeft de rootspan, de foutspans, de services, de duur en het traagste pad terug, zonder ruwe spanattributen. Een 404 op de samenvatting betekent dat geen enkele trace bij de volledige scope paste. Probeer het niet opnieuw zonder de filters. Zie responses voor trace-spans en samenvattingen.

Lege lijsten en ontbrekende records

Een lijst lezen kan nul resultaten opleveren. Voor het lezen van één record geldt een ander contract:

Request	Gelukt	Geen leesbaar record
`GET /api/logs/{log_id}`	`200` met één log	`404` met `code: not_found`
`GET /api/telemetry/issues/{issue_id}`	`200` met één issue	`404` met `code: not_found`
`GET /api/telemetry/issues/{issue_id}/events`	`200` met voorvallen	`404` met `code: not_found` op de eerste pagina
`GET /api/telemetry/traces/{trace_id}`	`200` met spans	`200` met `[]`
`GET /api/telemetry/traces/{trace_id}/summary`	`200` met één samenvatting	`404` met `code: not_found`

Een ontbrekende log geeft deze 404:

{
  "error": "log not found",
  "code": "not_found",
  "next": "check the resource id or filters and retry",
  "next_action": {
    "code": "check_resource",
    "target": "resource"
  }
}

Een ontbrekend issue gebruikt "error": "issue not found". Een ontbrekende tracesamenvatting gebruikt "error": "trace not found". Een onbekend ID en een ID dat het account niet kan lezen, geven dezelfde response. Een lijstrequest met één project_id dat het account niet kan lezen, geeft 200 met een lege lijst. Controleer het project-ID voordat je meldt dat er geen gegevens zijn.

Geweigerde projectselecties

De lijsten voor logs, issues, acties, metrics, releases en traces accepteren één project met project_id of 2 tot 50 projecten met project_ids. De catalogus met logattributen accepteert dezelfde selectors. De voorvalgeschiedenis van een issue accepteert ze niet. Een request met zowel project_id als project_ids geeft 422:

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

project_ids met een ongeldige UUID, een dubbel ID, of minder dan 2 of meer dan 50 ID’s geeft ook 422 met code: validation_failed. Als het account één project in een set project_ids niet kan lezen, geeft het hele request 404. Het geeft de andere projecten niet terug als gedeeltelijk resultaat:

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

Toon de fout, geen lege lijst of een aantal van nul. Lees de projectlijst opnieuw. Verwijder niet stilletjes een project en probeer het niet opnieuw over alle projecten. Gedelegeerde toegangsgegevens, zoals een MCP-verbinding, geven 403 met code: forbidden voor een project buiten die verbinding. Zie projectscope.

Cursorfouten

Logs, issues, acties, metrics en voorvallen van issues gebruiken cursor_time en cursor_id. Een geweigerde cursor geeft 422 met code: validation_failed. Deze fouten betekenen niet dat de lijst leeg is.

Request	`error`
`pagination=cursor` met maar 1 van de 2 cursorvelden	`cursor_time and cursor_id must be sent together`
`cursor_time` dat geen RFC3339-tijdstempel is	`cursor_time must be an RFC3339 timestamp`
Cursorvelden zonder `pagination=cursor`, of een andere waarde voor `pagination`	`pagination must be cursor when cursor pagination is requested`

Bijvoorbeeld:

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

Kopieer de volledige next_cursor van de vorige pagina. Vervang cursor_time niet door de huidige tijd. Ben je de cursor kwijt? Begin dan opnieuw met pagination=cursor en de oorspronkelijke filters. Een onbekende queryparameter of een waarde van het verkeerde type geeft 422 met "error": "invalid query parameters".

Responses van de releasecursor

Een releasecursor heeft 5 velden. Een geslaagd request zonder resultaten geeft 200:

{
  "releases": [],
  "next_cursor": null
}

Als next_cursor niet null is, stuur je alle 5 waarden mee met het volgende request:

Veld in `next_cursor`	Queryparameter
`time`	`cursor_time`
`project_id`	`cursor_project_id`
`release`	`cursor_release`
`environment`	`cursor_environment`
`service_name`	`cursor_service_name`

cursor_project_id markeert een positie. Het vervangt project_id of project_ids niet. Houd de oorspronkelijke project- en filterparameters aan. URL-codeer elke waarde. Met pagination=cursor geeft een onvolledige cursor, of een lege waarde voor release, omgeving of service, 422 met "error": "all release cursor fields must be sent together". Een ongeldige cursor_time en een ontbrekende pagination=cursor geven dezelfde fouten als de andere cursors.

Fouten bij het zoeken naar traces

Deze fouten gelden voor GET /api/telemetry/traces. Elke fout geeft 422 met code: validation_failed. Een geweigerd request is geen leeg resultaat.

Request	`error`
`status` anders dan `error` of `ok`	`trace status must be error or ok`
`min_duration_ms` onder `0`	`minimum trace duration must not be negative`
Maar 1 cursorveld, of een lege `cursor_trace_id`	`cursor_time and cursor_trace_id must be sent together`
`cursor_time` dat geen RFC3339-tijdstempel is	`cursor_time must be an RFC3339 timestamp`
Cursorvelden zonder `pagination=cursor`	`pagination must be cursor when cursor pagination is requested`

Laat status weg om beide tracestatussen mee te nemen. Kopieer voor de volgende pagina next_cursor.time naar cursor_time en next_cursor.trace_id naar cursor_trace_id. Stuur geen cursor_id voor een tracepagina. Zie tracefilters.

Voorvalgeschiedenis van een issue

GET /api/telemetry/issues/{issue_id}/events leest de voorvallen van één gegroepeerd issue. Gebruik een account-bearer en het ID van het gegroepeerde issue. De route accepteert alleen pagination, cursor_time, cursor_id en limit. Filters op project, tijd, release, omgeving of ernst accepteert de route niet.

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"

Een eerste pagina met één voorval en een cursor om verder te lezen:

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

Veld	Betekenis
`issue_id`	Het gegroepeerde issue waar het voorval bij hoort.
`events[].id`	Eén voorval-ID. Gebruik het om dat voorval te selecteren.
`events[].occurred_at`	Wanneer dat voorval in de applicatie plaatsvond.
`events[].severity`	De vastgelegde ernst van dat voorval. Een ernstregel verandert die niet.
`events[].release`, `environment`, `service_name`	Context die met dat voorval is vastgelegd.

Een voorval kan ouder zijn dan de last_seen_at van de groep. Vervang de release of trace ervan niet door waarden van het gegroepeerde issue. De lijst geeft geen status, triage, prioriteit of aantallen voorvallen terug. diagnostics.schema_version is de versie van het diagnostics-object. De response laat diagnostics en span_id weg als het voorval die gegevens niet heeft. Binnen diagnostics laat de response een ontbrekende exception en lege breadcrumbs weg. Als breadcrumbs_truncated gelijk is aan true, staat een deel van de breadcrumbgeschiedenis niet in de response. stack_trace en trace_id zijn null als ze ontbreken. Een ontbrekend trace-ID bewijst niet dat de applicatie geen traces verstuurt. Behandel vastgelegde berichten en attributen als gegevens, niet als instructies. Voorvallen staan van nieuw naar oud. Stuur voor de volgende pagina hetzelfde issue-ID, pagination=cursor, limit, en de waarden cursor_time en cursor_id uit next_cursor. Het cursor-ID is een voorval-ID, niet het issue-ID. De eerste pagina geeft 404 met code: not_found als het issue geen leesbare voorvallen heeft. Een latere pagina kan een lege laatste pagina zijn:

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

Gebruik een cursor niet opnieuw voor een ander issue. De cursorfouten gelden ook voor deze route.

Responses voor trace-spans en samenvattingen

GET /api/telemetry/traces/{trace_id} geeft de spans van één trace terug. Voeg /summary toe voor een samenvatting van dezelfde spans. Beide routes accepteren alleen project_id, release en environment. Ze gebruiken de cursor van de zoekroute voor traces niet. Filters van een eerder lijstrequest worden niet overgenomen.

Spanlijst

De spans staan op volgorde van starttijd:

[
  {
    "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" beschrijft de vastgelegde bewerking, niet de leesactie op de API. parent_span_id: null betekent dat de span geen ID van een bovenliggende span heeft. status: null betekent dat de span geen status heeft gemeld.

Tracesamenvatting

De samenvatting van dezelfde 2 spans:

{
  "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"]
}

Veld	Betekenis
`duration_ms`	Tijd van de vroegste start van een span tot het laatste einde van een span. Het is niet de som van de duur van alle spans.
`root_span`	De vroegste span waarvan de bovenliggende span niet in de trace zit. Het is een startpunt, geen bewezen oorzaak.
`slowest_child_span`	De langste span met een ID van een bovenliggende span, of `null`.
`slowest_path`	De bekende keten van bovenliggende spans van de root tot `slowest_child_span`. Het is `[]` als `slowest_child_span` gelijk is aan `null`.
`error_spans`	De langste foutspans, hoogstens 5. `error_span_count` kan groter zijn.

Geen van beide routes geeft een cursor of een afkapveld terug. Voeg geen waarde truncated toe die niet in de response staat.

Geen overeenkomende spans

Als geen enkele span bij het trace-ID en de scope past, geeft de spanlijst 200 met []. De samenvatting geeft 404 met "error": "trace not found" en code: not_found. Controleer het trace-ID en de scope. Verwijder de filters niet om toch een resultaat te krijgen. Geen van beide resultaten bewijst dat de applicatie geen telemetrie heeft verstuurd.

Responseformaat van live-events

De livefeed stuurt nieuwe events. Events die de client miste toen de verbinding weg was, stuurt de feed niet opnieuw. Gebruik de lijstroutes om bestaande records te lezen.

Een ticket aanmaken

Stuur POST /api/feed/ticket met een account-bearer. Het request heeft geen body.

curl --request POST "https://api.logbrew.co/api/feed/ticket" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

Een response 200 OK bevat het ticket in het veld ticket:

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

Het ticket is een toegangsbewijs dat snel verloopt. Log het niet en zet het niet in een prompt voor een agent. Open de verbinding voordat expires_in_seconds voorbij is. De vervaltijd bepaalt wanneer de verbinding kan starten, niet hoe lang die openblijft. Een 401 betekent dat de inlogsessie van het account niet geldig is. Log opnieuw in voordat je een ticket aanvraagt. Een andere methode dan POST geeft 405 met code: method_not_allowed.

De verbinding openen

Verbind een WebSocket-client met wss://api.logbrew.co/api/feed/live?ticket=<feed-ticket>. URL-codeer het ticket. Zet geen account-bearer en geen ingest-bearer in de URL. Een 401 betekent dat het ticket of de inlogsessie van het account niet geldig is. Maak een nieuw ticket aan nadat je opnieuw bent ingelogd.

Response	Oorzaak	Volgende stap
`422` met `"error": "feed ticket is required"`	De querywaarde `ticket` ontbreekt of is leeg.	Maak een ticket aan en verbind daarmee.
`401` met `code: unauthorized`	Het ticket is verlopen of niet geldig.	Maak een nieuw ticket aan. Probeer hetzelfde ticket niet opnieuw.
`code: invalid_websocket_upgrade`	Het request is geen geldige WebSocket-upgrade.	Gebruik een WebSocket-client.
`405` met `code: method_not_allowed`	Het request gebruikt geen `GET`.	Gebruik `GET` voor de verbinding.

Wacht na een fout voordat je opnieuw verbindt. Verbind niet opnieuw in een snelle lus.

De berichten lezen

Elk bericht is een envelop { "type": "...", "data": ... }. Lees type voordat je data parset. Sla types over die de client niet ondersteunt.

Eventtype	Payload
`native_log`	Loggegevens, in de vorm van de logresponse.
`native_issue`	Gegevens van een gegroepeerd issue, in de vorm van versie 1 van de issueresponse.
`native_trace_span`	Eén span, in de vorm van een item uit de spanlijst.
`native_action`	Gegevens van een productactie, in de vorm van de actieresponse.
`project_created`, `project_updated`, `project_catalog_changed`	Projectgegevens. Lees de projectlijst opnieuw als die verandert.
`usage_updated`, `usage_limit_warning`, `usage_limit_blocked`	Accountgebruik, in de vorm van accountgebruik.

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

Een event native_issue gebruikt versie 1 van de issueresponse: een gearchiveerd issue toont ignored, en het event heeft geen prioriteit. Metrics en releases zijn geen live-eventtypes. Lees ze via hun lijstroutes. Het ticket selecteert geen project. Controleer de project_id van elk event voordat je het in een projectweergave toont. logbrew watch --json gebruikt deze feed. Zie de CLI-referentie.

Een gesloten verbinding afhandelen

Sluitcode	Reden	Volgende stap
`1013`	`live feed fell behind; reconnect to resync`	Wacht en verbind daarna opnieuw met een nieuw ticket. Lees de lijstroutes opnieuw om de gemiste records op te halen.
`1008`	`live feed access changed; sign in again`	Stop met opnieuw verbinden. Log opnieuw in voordat je een nieuw ticket aanmaakt.

Bij andere verbroken verbindingen geeft LogBrew soms geen reden. Lees na het opnieuw verbinden de lijstroutes opnieuw en koppel records op ID.

Responsevoorbeelden voor de issuestatus

PATCH /api/telemetry/issues/{issue_id} met { "status": "resolved" } geeft 200 OK terug met het bijgewerkte gegroepeerde issue, in dezelfde vorm als de issueresponse. De queryparameter response_version kiest de versie. De route geeft geen succesvlag terug. De body stelt 1 of meer van status, priority en assignee in. status accepteert unresolved, resolved of archived. ignored is een oudere naam voor archived. Zie Eén issue bijwerken. Controleer de teruggegeven id, status en priority voordat je toont dat het gelukt is. Bouw het resultaat niet op uit de verstuurde waarden. Een statuswijziging verwijdert geen voorvallen en verandert first_seen_at en last_seen_at niet. Ze verandert ook severity of een ernstregel niet. Een geweigerde wijziging geeft 422 met code: validation_failed:

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

Resultaat	Oorzaak
`422`, `issue update requires status, priority, or assignee`	De body heeft geen van de 3 velden.
`422`, `issue priority must be high, medium, or low`	De waarde voor de prioriteit wordt niet ondersteund.
`422`, `issue assignee must be me, none, a user ID, or team:<team_id>`	De waarde voor `assignee` wordt niet ondersteund.
`422`, `issue assignee cannot read this project`	Het toegewezen account heeft geen toegang tot het project. LogBrew wijzigt niets.
`422`, `issue assignee team is not a team of this project's organization`	Het team hoort niet bij de organisatie van het project. LogBrew wijzigt niets.
`403` met `code: forbidden`	Het account kan geen issues beheren in het project.
`404` met `code: not_found`	Het account kan het issue niet lezen, of het issue bestaat niet.

Een veld dat al de gevraagde waarde heeft, verandert niet. Stuur na een time-out of een verloren response hetzelfde request opnieuw, of lees eerst het issue. Stuur geen andere wijziging voordat je de huidige toestand hebt gelezen. Zie Schrijfacties. POST /api/telemetry/issues/bulk geeft 200 OK terug met 1 resultaat per gevraagd issue-ID, in de volgorde van het request. Elk gevonden issue gebruikt de vorm van versie 3. Een resultaat not_found heeft issue: null:

{
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "results": [
    {
      "issue_id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
      "outcome": "updated",
      "issue": {
        "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
        "status": "archived",
        "priority": "high",
        "priority_source": "derived",
        "assignee": null
      }
    },
    {
      "issue_id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "outcome": "not_found",
      "issue": null
    }
  ]
}

Dit voorbeeld toont maar een deel van de issuevelden. outcome is updated, unchanged of not_found. Een herhaald request geeft unchanged en wijzigt niets. Zie Issues in bulk bijwerken. Een bulkrequest mislukt in deze gevallen in zijn geheel:

Resultaat	Oorzaak
`422`, `issue_ids must name 1 to 100 issues`	De lijst is leeg of heeft meer dan 100 ID’s.
`422`, `issue_ids must not contain duplicates`	Een ID komt vaker dan één keer voor.
`422` met `code: invalid_json`	De body heeft een onbekend veld.
`403` met `code: forbidden`	Het account kan geen issues beheren in het project.
`404`, `project not found`	Het account kan het project niet lezen.

Scope van analyserequests

De analyseroutes, de route voor metric-tijdreeksen en de route voor signaalvolume lezen één project en één tijdsbereik. Elk request heeft project_id en since nodig. since accepteert een korte duur zoals 24h of 7d, of een RFC3339-tijdstempel. until accepteert een RFC3339-tijdstempel en is standaard het tijdstip van het request. Het bereik bevat since, bevat until niet en mag niet langer zijn dan 31 dagen. service_name, release en environment zijn optionele exacte filters. Elke waarde moet 1 tot 256 tekens hebben nadat LogBrew de spaties aan begin en eind heeft verwijderd. De route voor segmentvergelijking zet deze filters in elk segment, niet op het hoogste niveau. Als het account het project niet kan lezen, geven deze routes 200 OK met aantallen van nul. Ze geven geen 404. Een leeg resultaat bevestigt dus niet dat je toegang hebt tot het project. Vergelijk project_id met de projecten die het account kan lezen. Een request via een MCP-verbinding die het project niet bevat, geeft 403 en forbidden.

Route	Waarden voor `response_version`	Standaard
`GET /api/telemetry/analytics/overview`	`1`, `2` of `3`	`1`
`GET /api/telemetry/analytics/properties`	`1` of `2`	`1`
`POST /api/telemetry/analytics/segments/compare`	`1` of `2`	`1`
`POST /api/telemetry/analytics/retention`	`1` of `2`	`1`
`POST /api/telemetry/analytics/lifecycle`	`1` of `2`	`1`
`POST /api/telemetry/analytics/funnel`	Niet geaccepteerd	Schema `1`
`POST /api/telemetry/analytics/paths`	Niet geaccepteerd	Schema `1`
`GET /api/telemetry/metrics/series`	Niet geaccepteerd	Schema `1`
`GET /api/telemetry/summary/volume`	`1`	`1`

Elke response begint met schema_version, query en purpose. query herhaalt de effectieve scope. Een filter dat je niet hebt gestuurd, staat er niet in. purpose is platte tekst die uitlegt op welke vraag de route antwoord geeft. Een ratio ontbreekt als de noemer nul is. Een weggelaten ratio is niet 0 en niet null. Lees coverage voordat je op een ratio vertrouwt.

Gedeelde scopefouten

Deze fouten gebruiken HTTP 422 en validation_failed:

Oorzaak	`error`
Geen `project_id`	`product analytics project_id is required`
Geen `since`	`product analytics since is required`
`since` is geen duur of RFC3339-tijdstempel	`invalid since value`
`until` is geen RFC3339-tijdstempel	`product analytics until must be an RFC3339 timestamp`
`since` ligt niet vóór `until`	`product analytics since must be earlier than until`
Het bereik is langer dan 31 dagen	`product analytics range must not exceed 31 days`
Een leeg filter, of een filter langer dan 256 tekens	`product analytics context filters must be non-empty and at most 256 characters`

Een request zonder project_id geeft bijvoorbeeld:

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

De routes voor metric-tijdreeksen en signaalvolume gebruiken dezelfde scoperegels, met hun eigen tekst in error. Hun secties hieronder noemen die fouten. Een onbekende queryparameter geeft 422 met de response voor ongeldige queryparameters. Een onbekend JSON-veld, een ontbrekend verplicht JSON-veld of een niet-ondersteunde enumwaarde geeft invalid_json. Zie Ongeldige JSON. Een request met de verkeerde HTTP-methode geeft 405 en method_not_allowed. De tekst in next noemt de ondersteunde methode en velden. Zie Niet-ondersteunde methode.

Response van het overzicht voor productanalyse

GET /api/telemetry/analytics/overview toont de activiteit in één project: actievolume, gebruikers, sessies, een tijdreeks, topacties, en geclassificeerde paginaweergaven, schermweergaven en interacties. Gebruik het overzicht om de exacte eventnamen voor de andere analyseroutes te vinden. Stuur response_version=3. Versies 1 en 2 geven dezelfde aantallen, maar hun waarde voor estimation.method is een ouder token. Versie 1 controleert het soort subject niet als ze geïdentificeerde gebruikers telt. Versies 2 en 3 tellen alleen subjecten van het soort user, en voegen aantallen voor anonieme subjecten en subject_coverage toe. Dit request leest één uur in tijdsintervallen van vijf minuten en geeft twee rijen in elke toplijst:

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"

Geslaagd overzicht

In dit fictieve resultaat heeft het project 120 acties in twee van de twaalf tijdsintervallen. Twintig acties komen van anonieme subjecten. Elke actie heeft een sessie-ID. De helft van de acties heeft een trace-ID.

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

Het overzicht lezen

De vijf aantallen in subject_coverage tellen op tot het eventtotaal van hun sectie. Alleen identified_user_events telt mee voor gebruikers. anonymous_actions is summary.actions min identified_actions. series bevat alleen tijdsintervallen met activiteit. expected_buckets is het aantal mogelijke tijdsintervallen in het bereik. Teken een ontbrekend tijdsinterval niet als een gemeten nul, tenzij je grafiek die regel vermeldt. Tijdsintervallen vallen samen met de intervalgrenzen in UTC. Een bereik dat midden in een tijdsinterval begint, bevat dat onvolledige tijdsinterval. classified_activity telt paginaweergaven, schermweergaven en interacties. Schermweergaven en interacties zijn ook acties. Paginaweergaven niet. Tel summary.actions niet op bij classified_activity.summary.events. Kopieer kind en event_name uit classified_activity.top_events naar trechterstappen, retentieselectors, levenscyclusselectors, padankers en segmentdoelen. De waarde true in top_events_truncated betekent dat er namen met minder volume zijn. Verhoog top_limit tot maximaal 20 om meer te zien. analysis_level is no_data, event_only, user_level of user_and_session. Als het project geen acties en geen geclassificeerde events heeft, is next_action.code gelijk aan capture_product_activity. Zie Productanalyse.

Fouten in het overzicht

Naast de gedeelde scopefouten geeft het overzicht 422 en validation_failed voor deze waarden:

Waarde	`error`
`response_version` anders dan `1`, `2` of `3`	`product analytics response_version must be 1, 2, or 3`
`top_limit` buiten `1` tot `20`	`product analytics top_limit must be between 1 and 20`
`interval` anders dan `auto`, `1m`, `5m`, `15m`, `1h`, `6h` of `1d`	`product analytics interval is not supported`
Een expliciet `interval` dat meer dan 500 tijdsintervallen nodig heeft	`product analytics interval would exceed 500 buckets`

Standaard is interval gelijk aan auto. Dat kiest het kleinste interval waarvoor hoogstens 300 tijdsintervallen nodig zijn. Standaard is top_limit gelijk aan 10.

Response van een geordende trechter

POST /api/telemetry/analytics/funnel meet of 2 tot 8 stappen op volgorde worden doorlopen. Kopieer elke exacte kind en event_name uit classified_activity.top_events in het overzicht. Een actienaam die erop lijkt, is geen match. Deze requestbody telt sessies die /pricing bekijken en daarna binnen één uur de aanmelding afronden:

{
  "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 is session of identified_user. Standaard is dat session. De kind van een stap is page_view, screen_view of interaction. De trechterroute accepteert geen response_version.

Geslaagde trechter

Een response 200 OK:

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

Ratio’s zijn breuken van 0 tot 1. Lees coverage voordat je op een ratio vertrouwt. selected_unit_coverage_rate is het aandeel van de geselecteerde stapevents dat LogBrew kon gebruiken. De response geeft geen ruwe identiteiten terug. Zie Productanalyse.

Conversie en dekking lezen

entry_rate is entered_units gedeeld door candidate_units: 50 van 60. overall_conversion_rate is completed_units gedeeld door entered_units: 15 van 50, dus 30%. Het is niet 15 gedeeld door alle kandidaten. Deze aantallen verklaren niet waarom eenheden stopten. Dekking telt events, geen sessies. Hier passen 120 events bij een stap, en 20 daarvan hebben geen sessie-ID. Het resultaat laat die 20 events buiten de sessieaantallen. Behandel ze niet als 20 mislukte sessies. De eerste stap heeft geen conversion_from_previous. De laatste stap heeft geen drop_off_to_next_units en geen drop_off_to_next_rate. Een eenheid bereikt een latere stap alleen als de tijden van de stappen strikt oplopen. Events met dezelfde tijdstempel kunnen niet aan twee opeenvolgende stappen voldoen. De laatste stap moet binnen conversion_window_seconds na de eerste stap plaatsvinden. De sessiemodus telt sessies, geen mensen. Gebruik identified_user alleen voor events met een ondoorzichtig subject-ID van het soort user. Die modus kan events uit verschillende sessies binnen het conversievenster samenvoegen. Houd dezelfde eenheid en dezelfde stappen aan als je resultaten vergelijkt. Standaard is conversion_window_seconds 24 uur of de lengte van het bereik, als die korter is. Het maximum is de lengte van het bereik in hele seconden, naar boven afgerond.

Lege trechterresultaten

Een geslaagde lege response toont nog steeds de gevraagde stappen, met nul units. Zijn er geen kandidaateenheden, dan laat summary entry_rate en overall_conversion_rate weg. De route geeft geen 404 alleen omdat er geen events overeenkomen. Lees coverage en next_action om de oorzaak te vinden:

`next_action.code`	Oorzaak
`capture_product_activity`	Er zijn geen geclassificeerde events in de scope.
`choose_captured_funnel_steps`	Geen enkel event past bij een gevraagde stap.
`sessionize_product_activity`	Er zijn stapevents, maar geen ervan heeft een sessie-ID.
`identify_product_users`	Er zijn stapevents, maar geen ervan heeft een subject van het soort `user`.
`verify_funnel_entry`	Geen enkele eenheid is bij stap 1 binnengekomen.
`investigate_funnel_drop_off`	Er kwamen eenheden binnen, maar geen enkele eenheid voltooide alle stappen.
`compare_funnel_contexts`	Minstens één eenheid voltooide de trechter.

Geweigerde trechterrequests

Naast de gedeelde scopefouten geven deze requests 422 en validation_failed. Minder dan 2 of meer dan 8 stappen:

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

Een conversion_window_seconds van 0, of een waarde groter dan de lengte van het bereik:

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

Een event_name die leeg is, langer is dan 256 tekens of een stuurteken bevat, geeft product analytics funnel event_name must be non-empty, control-free, and at most 256 characters. Een stap interaction moet ook een geldige actienaam zijn. Anders is de fout product analytics interaction event_name must be a bounded stable action name. Corrigeer het request voordat je het opnieuw stuurt. Verwijder geen stappen en wijzig de analyse-eenheid niet alleen om een niet-leeg resultaat te krijgen.

Analyse op exacte events en automatische analyse

Retentie en levenscyclus accepteren twee vormen van requests. Kies met response_version de vorm die je vraag beantwoordt:

Analyse	`response_version`	Eventselectors
Retentie voor exacte events	`1`, of weggelaten	Stuur zowel `start_event` als `return_event`.
Levenscyclus voor één exact event	`1`, of weggelaten	Stuur `event`.
Automatische retentie of levenscyclus	`2`	Stuur geen eventselector.

Een exacte selector bevat kind en event_name. kind is page_view, screen_view of interaction. Kopieer event_name uit classified_activity.top_events. Raad geen eventnaam op basis van een knoplabel. Beide vormen tellen alleen gebruikers: ondoorzichtige subject-ID’s van het soort user. Anonieme subjecten en events zonder bruikbaar subject-ID tellen niet als gebruikers. Responses geven nooit subject-ID’s terug. De vaste intervallen zijn hour, day, week en thirty_day. Het zijn vaste tijdsduren. thirty_day is 30 dagen, geen kalendermaand. Laat je interval weg, dan gebruikt de API hour voor een bereik van 48 uur of korter, en day voor een langer bereik.

Request voor retentie op exacte events

Stuur deze body naar POST /api/telemetry/analytics/retention. Die vraagt of gebruikers nog een checkout afronden na hun eerste checkout in het bereik:

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

Het eerste overeenkomende startevent in het bereik is het anker van elke gebruiker. Een terugkeer moet strikt na dat anker en vóór until plaatsvinden. Beide selectors mogen hetzelfde event zijn.

Veld	Waarden	Standaard
`interval_count`	`1` tot `31` perioden	`10`
`mode`	`return_on` telt een terugkeer binnen elke exacte periode. `return_on_or_after` telt een terugkeer op of na het begin van elke periode.	`return_on`
`cohort_mode`	`first_in_range`	`first_in_range`

Geslaagde retentie op exacte events

In dit fictieve voorbeeld ronden twee gebruikers een checkout af. De eerste gebruiker rondt een checkout af op 1 juni om 12:00 en opnieuw om 13:00. De tweede gebruiker rondt een checkout af op 2 juni om 12:00. Op 2 juni om 13:00 bekijkt de tweede gebruiker een pagina, maar rondt geen nieuwe checkout af.

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

Retentie lezen

Dekking telt alle vier de geclassificeerde events, maar slechts drie passen bij elke checkoutselector. De paginaweergave telt niet als terugkeer. Een van de twee gebruikers herhaalt de checkout, dus return_rate_after_start is 0.5. Alleen de eerste gebruiker heeft na het anker een volledige dag waarneming. Die gebruiker keert binnen de dag terug, dus de ratio in de curve is 1.0. De tweede gebruiker heeft maar 12 uur waarneming. Die gebruiker komt niet in aanmerking voor periode 0, dus de cel van het tweede cohort laat retention_rate weg. Tel die gebruiker niet als verloren. weighted_retention_rate deelt alle behouden gebruikers door alle gebruikers die in aanmerking komen. fully_observed_cohort_average_rate is het gewone gemiddelde van de ratio’s van de cohorten waarin elke gebruiker in aanmerking komt. Cohorten zijn vaste tijdsintervallen die beginnen bij since. cohorts bevat alleen cohorten met gebruikers. Met mode: "return_on_or_after" laat de curve window_end_seconds weg.

Automatische retentie

Stuur response_version: 2 zonder start_event of return_event. Elke ondersteunde paginaweergave, schermweergave en interactie telt als start en als terugkeer. Deze versie kiest een set events. Ze kiest geen vastlegformaat van de SDK.

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

De response heeft dezelfde vorm voor summary, curve, cohorts en next_action als de response voor exacte events. Dit fragment toont de velden die veranderen. In dit voorbeeld hebben dezelfde twee gebruikers drie events en geen paginaweergave:

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

In de automatische modus zijn start_events en return_events allebei gelijk aan classified_events. Deze aantallen zijn events, geen gebruikers.

Retentie zonder gebruikers die in aanmerking komen

Een geslaagd resultaat kan zonder cohortgebruikers zijn. Dit fragment toont één gevraagde periode zonder cohorten:

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

Lees coverage en next_action. Die onderscheiden een scope zonder geclassificeerde events (capture_product_activity) van events zonder gebruikers (identify_product_users of identify_returning_users). Een ontbrekende ratio is geen gemeten nul.

Retentiefouten

Naast de gedeelde scopefouten geven deze requests 422 en validation_failed:

Oorzaak	`error`
Versie 1 zonder beide selectors, versie 2 met een selector, of een andere versie	`product analytics retention activity selection is contradictory`
`interval_count` buiten `1` tot `31`	`product analytics retention interval_count must be between 1 and 31`
Tijdsintervallen voor cohorten maal `interval_count` is meer dan 500	`product analytics retention interval and interval_count would exceed 500 cohort matrix cells`

De limiet op cellen gebruikt het bereik en de perioden, niet het aantal gebruikers. Een bereik van 30 dagen met interval: "hour" heeft 720 tijdsintervallen voor cohorten. Met interval_count: 1 zijn dat 720 cellen, meer dan 500:

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

Verwijder beide selectors om automatische retentie te gebruiken. Wijzig de SDK niet om dit leesrequest te corrigeren.

Request voor levenscyclus op een exact event

Stuur deze body naar POST /api/telemetry/analytics/lifecycle. Die deelt gebruikers in op basis van één event, niet op basis van alle activiteit in het project:

{
  "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 bepaalt hoeveel volledige perioden vóór since LogBrew als geschiedenis leest. Het accepteert 2 tot 31. Standaard is dat 2. Een gebruiker kan inactief zijn voor dit event terwijl die gebruiker andere dingen doet.

Geslaagde levenscyclus op een exact event

Dit fictieve voorbeeld gebruikt twee dagen geschiedenis en twee analysedagen. De letters staan alleen voor voorbeeldgebruikers. De response geeft geen gebruikers-ID’s terug.

Datum, UTC	Gebruikers die een checkout afronden
30 mei, geschiedenis	B
31 mei, geschiedenis	A en D
1 juni, analyse	A, B en C
2 juni, analyse	A en B

C bekijkt op 2 juni ook een pagina. Dat event past niet bij de checkoutselector.

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

Levenscyclus lezen

Op 1 juni is A terugkerend, B opnieuw actief, C nieuw en D inactief. Op 2 juni zijn A en B terugkerend, en is C inactief voor checkout, ondanks de paginaweergave. De netto verandering op 2 juni is 2 - 3 = -1. In elk tijdsinterval tellen nieuwe, terugkerende en opnieuw actieve gebruikers op tot active_subjects. returning_subjects plus dormant_subjects is gelijk aan previous_active_subjects. net_active_change is active_subjects min previous_active_subjects. Tel de dagelijkse actieve aantallen niet op om unieke gebruikers te krijgen. Hier tellen de dagaantallen op tot 5, maar analysis_active_subjects is 3. In geschiedenis en analyse samen komen vier unieke gebruikers voor. fully_observed is false voor een laatste tijdsinterval dat na until eindigt. De aantallen ervan kunnen veranderen als de volledige periode waarneembaar is. De next_action stelt een onderzoek voor. Die toont geen oorzaak.

Automatische levenscyclus

Stuur response_version: 2 zonder selector event. Elke ondersteunde paginaweergave, schermweergave en interactie telt als activiteit:

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

De response heeft dezelfde vorm voor summary, buckets en next_action als de response voor een exact event. Dit fragment toont de velden die veranderen:

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

In de automatische modus is coverage.selected_events gelijk aan coverage.analysis_classified_events. Het vijfde item in limitations is

Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.

Levenscyclus zonder gebruikers

Als het analysebereik en de geschiedenis geen bruikbare gebruikers bevatten, is buckets leeg en laat summary latest_fully_observed_period weg:

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

Gebruikers die alleen in de geschiedenis voorkomen, kunnen toch tijdsintervallen met inactieve gebruikers opleveren als het analysebereik geen activiteit heeft.

Levenscyclusfouten

Naast de gedeelde scopefouten geven deze requests 422 en validation_failed:

Oorzaak	`error`
Versie 1 zonder `event`, versie 2 met `event`, of een andere versie	`product analytics lifecycle activity selection is contradictory`
`history_period_count` buiten `2` tot `31`	`product analytics lifecycle history_period_count must be between 2 and 31`
Geschiedenisperioden van samen meer dan 62 dagen	`product analytics lifecycle history must not exceed 62 days`
Meer dan 100 tijdsintervallen voor analyse	`product analytics lifecycle interval would exceed 100 analysis buckets`

Tien geschiedenisperioden van week hebben bijvoorbeeld 70 dagen nodig:

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

De gekozen analysescope lezen

Responses voor exacte events hebben schema_version: 1. Hun query herhaalt de selectors en laat activity_scope weg. Automatische responses hebben schema_version: 2 en query.activity_scope: "all_classified_activity". Ze laten de selectors weg. Een andere selector kan het resultaat veranderen zonder dat de vastgelegde activiteit verandert.

Response voor metric-tijdreeksen

GET /api/telemetry/metrics/series leest één exacte metricnaam in één project. Kopieer de naam uit GET /api/telemetry/metrics. Dit request groepeert een delta-counter per service:

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"

Geslaagde metric-tijdreeks

Deze fictieve response bevat één tijdreeks van een delta-counter. Drie metingen met de waarden 2, 3 en 5 vallen in het eerste tijdsinterval. Twee metingen met de waarden 1 en 4 vallen in het laatste tijdsinterval. In het middelste tijdsinterval valt geen meting, dus de response heeft daarvoor geen datapunt.

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

Een metric-tijdreeks lezen

Het eerste datapunt registreert 10 voltooide jobs, niet 10 metingen. rate_per_second deelt die verandering door het tijdsinterval van 300 seconden. last is de laatst geregistreerde verandering, niet de som. Zie betekenissen van metric-aggregaties. Het soort en de temporaliteit van een tijdreeks bepalen de aggregation.code en de statistieken in elk datapunt. Een datapunt laat een statistiek weg die niet van toepassing is. Een ontbrekende statistiek is geen nul.

Soort en temporaliteit	`status`	`aggregation.code`	`value`	Andere statistieken
`gauge`, `instant`	`ready`	`gauge_last`	Laatste meting	`last`, `min`, `max`, `average`
`counter`, `delta`	`ready`	`delta_sum`	Som van de veranderingen	`last`, `min`, `max`, `average`, `sum`, `rate_per_second`
`histogram`, `delta`	`ready`	`distribution_p95`	p95 bij benadering	`min`, `max`, `average`, `sum`, `p50`, `p95`, `p99`
Elk soort, `cumulative`	`limited`	`raw_cumulative_last`	Laatste ruwe meting	`last`, `min`, `max`
Elk ander paar	`limited`	`raw_last`	Laatste ruwe meting	`last`, `min`, `max`

limited is een geslaagde response, geen fout. Het voegt aggregation.limitation toe, dat uitlegt waarom LogBrew alleen ruwe waarden toont. ready bewijst niet dat alles is vastgelegd. Lees coverage voordat je een grafiek tekent:

samples telt de metingen van alle overeenkomende tijdreeksen, ook tijdreeksen die de response niet teruggeeft.
series telt overeenkomende tijdreeksen. returned_series en points tellen de teruggegeven gegevens.
truncated is true als series_limit tijdreeksen met minder volume heeft weggelaten.
expected_buckets_per_series is het aantal mogelijke tijdsintervallen in het bereik.

Voeg geen datapunt toe voor een tijdsinterval zonder metingen. Vul geen nul in en kopieer de vorige waarde niet. Elk datapunt geeft maximaal 3 trace_exemplars terug. Een trace-exemplar koppelt één meting aan een trace. Het verklaart niet elke meting in het tijdsinterval. Als geen enkel datapunt een trace-exemplar heeft, is next_action.target gelijk aan metric_samples.

Scope en fouten van metric-tijdreeksen

project_id, name en since zijn verplicht. name mag hoogstens 200 tekens hebben. interval is auto, 1m, 5m, 15m, 1h, 6h of 1d. Standaard is dat auto. Die waarde kiest het kleinste interval met hoogstens 300 tijdsintervallen. Een expliciet interval mag niet meer dan 500 tijdsintervallen nodig hebben. group_by is none, service_name, release of environment. Standaard is dat none. Zonder groepering blijven verschillende soorten, eenheden en temporaliteiten in aparte tijdreeksen. series_limit accepteert 1 tot 20. Standaard is dat 10. Een leeg resultaat geeft 200 met series: [] en nul samples. Het object coverage laat first_seen_at en last_seen_at weg. Dat bewijst niet dat de applicatie de metric nooit heeft verstuurd. Controleer het project, de metricnaam en het tijdsbereik. Zonder name krijg je 422:

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

Tijdsintervallen van één minuut over zeven dagen geven 422:

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

Andere fouten met 422 zijn metric series group_by is not supported, metric series interval is not supported en metric series_limit must be between 1 and 20.

Response van padanalyse

POST /api/telemetry/analytics/paths vindt de benoemde events vóór of na één gekozen event in dezelfde sessie. Het gekozen event is het anker. Kopieer de kind en event_name ervan uit classified_activity.top_events. De route geeft schema_version: 1 terug. Ze accepteert geen response_version of analysis_unit.

{
  "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 en anchor zijn verplicht.

Geslaagde padanalyse

In dit fictieve resultaat bevatten vier sessies het anker. De twee teruggegeven paden staan voor drie van die sessies. Eén lager gerangschikt pad wordt niet teruggegeven.

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

Paden lezen

share_of_anchored_sessions deelt de sessies van een pad door alle vier de sessies met het anker. De aandelen zijn 50% en 25%, niet 67% en 33%. unrepresented_sessions telt sessies met het anker die geen enkel teruggegeven pad vertegenwoordigt. paths_truncated: true betekent dat het resultaat onvolledig is. Dekking telt events, geen sessies. Hier passen vijf events bij het anker, maar één heeft geen sessie-ID. Dat event kan niet in een pad komen. Elk pad geeft maximaal 3 trace-exemplars terug. Gebruik een trace-ID uit je eigen response. Een tracekoppeling toont niet wat een gebruikersactie of een fout veroorzaakte.

Veld	Betekenis
`following`	Begint bij het vroegste overeenkomende anker in elke sessie. Het anker heeft positie `0`. Latere knooppunten hebben positieve posities.
`preceding`	Eindigt bij het laatste overeenkomende anker in elke sessie. Eerdere knooppunten hebben negatieve posities. Het anker heeft positie `0`.
`depth`	Aantal knooppunten naast het anker, het anker zelf niet meegeteld. `1` tot `8`. Standaard is dat `4`. Een pad kan minder knooppunten hebben.
`collapse_repeated`	Voegt opeenvolgende knooppunten met hetzelfde soort en dezelfde naam samen. Standaard is dat `true`.
`path_limit`	Maximaal aantal teruggegeven paden, gerangschikt op aantal sessies. `1` tot `20`. Standaard is dat `10`.

Knooppunten staan in beide richtingen op tijdsvolgorde. Een pad is geen volledige herhaling van de sessie. LogBrew leest hoogstens 1024 benoemde events per sessie voordat het het anker kiest: de vroegste events voor following en de laatste events voor preceding. Een anker buiten die limiet kan ontbreken.

Het anker filteren op eigenschap

Stuur maximaal vier property_filters, elk met één exacte key en value. Kopieer de sleutel uit de eigenschappencatalogus. De filters gelden alleen voor het anker, niet voor de events eromheen. Waarden zijn hoofdlettergevoelig. Als er filters zijn, herhaalt query ze en meldt coverage.anchor_property_filters:

Veld	Betekenis
`context_events`	Ankerevents in de scope vóór de eigenschapsfilters.
`property_ready_events`	Ankerevents die elke gevraagde sleutel hebben.
`missing_property_events`	Ankerevents zonder een of meer gevraagde sleutels.
`matching_events`	Ankerevents waarvan de waarden bij elk filter passen.
`nonmatching_value_events`	Ankerevents die elke sleutel hebben, maar een andere waarde.
`property_ready_rate`	`property_ready_events` gedeeld door `context_events`.
`match_rate`	`matching_events` gedeeld door `property_ready_events`.

Ontbrekende sleutels en afwijkende waarden vragen om verschillende oplossingen. Tel ze niet bij elkaar op. Het object ontbreekt als het request geen eigenschapsfilter heeft.

Lege paden en geweigerde requests

Een lege array paths kan een geslaagde response 200 zijn. Lees summary, coverage en next_action. Deze codes onderscheiden de oorzaken: capture_product_activity, choose_captured_path_anchor, capture_anchor_properties, improve_anchor_property_coverage, verify_anchor_property_values, sessionize_product_activity en narrow_or_move_path_anchor. Naast de gedeelde scopefouten geven deze requests 422 en validation_failed:

Oorzaak	`error`
`depth` buiten `1` tot `8`	`product analytics path depth must be between 1 and 8`
`path_limit` buiten `1` tot `20`	`product analytics path_limit must be between 1 and 20`
Meer dan vier eigenschapsfilters	`product analytics paths accept at most four exact anchor property filters`
Een sleutel die niet in de eigenschappencatalogus staat	`product analytics path property keys must be supported privacy-safe keys`
Dezelfde sleutel twee keer	`product analytics path property keys must be unique`
Een lege waarde, een waarde langer dan 256 tekens, of een stuurteken	`product analytics path property values must be non-empty, control-free, and at most 256 characters`

depth: 0 geeft bijvoorbeeld:

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

Eigenschappencatalogus voor productanalyse

GET /api/telemetry/analytics/properties toont de eigenschapssleutels op geclassificeerde productevents in één project. Gebruik de sleutels in segmentvergelijkingen en in filters voor padankers. De catalogus geeft sleutels en aantallen terug. Hij geeft nooit eigenschapswaarden of identiteiten terug.

Beschikbare eigenschapssleutels lezen

Stuur project_id en since. Je kunt ook until, service_name, release, environment, limit en response_version sturen. limit accepteert 1 tot 50 sleutels. Standaard is dat 20. Stuur response_version=2 voor de openbare waarde van estimation.method.

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"

Geslaagde eigenschappencatalogus

In dit fictieve resultaat zijn er 100 geclassificeerde events. Vijf daarvan zijn vastgelegd vóór de huidige eigenschappenindex.

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

De catalogus interpreteren

source is standard_context voor een standaardcontextsleutel, zoals resource.runtime.name, of custom_tag voor een sleutel die begint met tag.. value_type is altijd string. properties is gesorteerd op events, de hoogste eerst. tag.plan staat op 60 van de 100 geclassificeerde events. De sleutel heeft ongeveer 3 unieke waarden. De beschrijving toont die waarden niet. Gebruik waarden die je uit je applicatie kent. Raad geen waarde op basis van een aantal. Eén event kan meerdere sleutels hebben, dus tel de aantallen in events per sleutel niet bij elkaar op.

Veld	Betekenis
`summary.classified_events`	Geclassificeerde events in de scope. Dit is de noemer van elke `coverage_rate`.
`summary.available_property_keys`	Geschat aantal unieke sleutels, niet het aantal teruggegeven rijen.
`coverage.unindexed_events`	Events die vóór de huidige eigenschappenindex zijn vastgelegd. Ze kunnen geen sleutels leveren.
`coverage.incomplete_index_events`	Events met deels misvormde of afgekapte context. Hun geldige sleutels tellen nog steeds mee.
`coverage.privacy_filtered_events`	Events waaruit LogBrew gevoelige sleutels van aangepaste tags heeft verwijderd. Dit is geen aantal sleutels.
`coverage.properties_truncated`	`true` als er meer sleutels zijn dan `limit`. Maak de scope kleiner, of verhoog `limit` tot maximaal 50.
`coverage.values_returned`	Altijd `false`.

Een lege array properties bewijst niet dat het project geen productevents heeft. Lees summary, coverage en next_action.

Fouten in de eigenschappencatalogus

Naast de gedeelde scopefouten geeft limit=0 of limit=51 een 422:

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

Een response_version anders dan 1 of 2 geeft product analytics response_version must be 1 or 2. LogBrew controleert response_version vóór de andere waarden. Een POST-request geeft 405:

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

Segmentvergelijking in productanalyse

POST /api/telemetry/analytics/segments/compare vergelijkt hoe vaak sessies of gebruikers één exact event bereiken in 2 tot 4 segmenten binnen één project. Een segment selecteert events op service, release, omgeving en eigenschapswaarden. Het eerste segment is het referentiesegment.

De vergelijking definiëren

Stuur deze JSON-body met accountauthenticatie en Content-Type: application/json. Hier zijn basic en premium abonnementswaarden van de voorbeeldapplicatie, geen abonnementen van LogBrew:

{
  "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 en segments zijn verplicht. analysis_unit is session of identified_user. Standaard is dat session. Die waarde telt sessies, geen mensen. interval accepteert dezelfde waarden als het overzicht. Standaard is dat auto. Elk segment heeft een unieke key, een label en een eigen set filters nodig:

key: 1 tot 32 bytes. Begin met een kleine ASCII-letter of een cijfer. Gebruik alleen kleine ASCII-letters, cijfers, _ en -.
label: 1 tot 80 tekens, zonder stuurtekens.
service_name, release, environment: optioneel. Elke waarde heeft 1 tot 256 tekens, zonder stuurtekens.
property_filters: 0 tot 4 filters. Elke sleutel mag één keer in een segment voorkomen. Een event moet bij alle filters van het segment passen. Waarden zijn hoofdlettergevoelig en hebben 1 tot 256 tekens. LogBrew verwijdert spaties aan het begin en het eind.

Een segment zonder filters selecteert alle geclassificeerde activiteit in het project en het tijdsbereik. Segmenten mogen overlappen. Een ander label of een andere sleutel maakt twee identieke sets filters niet geldig.

Geslaagde segmentvergelijking

In dit fictieve resultaat bereikt het referentiesegment de checkout in 10 van de 50 sessies. Het segment premium bereikt die in 18 van de 60 sessies.

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

Ratio’s en verschillen lezen

eligible_units schat de sessies of gebruikers met geclassificeerde activiteit in het segment. reached_units schat hoeveel daarvan het doel bereikten. reach_rate is reached_units gedeeld door eligible_units. Events zonder ID van de gekozen eenheid tellen niet mee voor deze eenheden. De ratio van het referentiesegment is 20%. De ratio van premium is 30%. Het verschil is 10 procentpunten. De relatieve stijging is 50%, niet 10%. Kleine decimale afwijkingen komen door rekenen met drijvendekommagetallen. Rond ratio’s af voor weergave, maar reken met de teruggegeven waarden. Het referentiesegment heeft geen comparison_to_baseline. De relatieve stijging ontbreekt als de bereikratio van het referentiesegment nul is. In query is een segmentfilter dat je niet hebt gestuurd null. Een lege lijst property_filters wordt weggelaten. coverage.property_filters heeft dezelfde velden als de dekking van padankerfilters. Hier is matching_events gelijk aan classified_events. Houd ontbrekende sleutels en afwijkende waarden apart. Segmenten kunnen overlappen, en één sessie kan in meerdere tijdsintervallen voorkomen. Tel aantallen eenheden niet op over segmenten of tijdsintervallen heen. De vergelijking is beschrijvend. confidence.causal_inference is not_established en confidence.statistical_significance is not_tested. Een ratio van 30% tegenover 20% toont niet aan dat een abonnement tot meer checkouts leidde.

Fouten in segmentvergelijkingen

Naast de gedeelde scopefouten geven deze requests 422 en validation_failed:

Oorzaak	`error`
Minder dan 2 of meer dan 4 segmenten	`product analytics segment comparison requires two through four segments`
Twee segmenten met dezelfde sleutel	`product analytics segment keys must be unique`
Twee segmenten met dezelfde filters	`product analytics segment filters must be unique`
Een sleutel die niet uit 1 tot 32 toegestane bytes bestaat	`product analytics segment keys must be 1 through 32 machine-safe bytes`
Een label dat leeg of te lang is, of een stuurteken bevat	`product analytics segment labels must be non-empty, control-free, and at most 80 characters`
Een filterwaarde met een stuurteken	`product analytics segment filters must be control-free`
Meer dan vier eigenschapsfilters in een segment	`product analytics segments accept at most four exact property filters`
Een sleutel die niet in de eigenschappencatalogus staat	`product analytics segment property keys must be supported privacy-safe keys`
Dezelfde eigenschapssleutel twee keer in een segment	`product analytics segment property keys must be unique within each segment`
Een eigenschapswaarde die leeg of te lang is, of een stuurteken bevat	`product analytics segment property values must be non-empty, control-free, and at most 256 characters`
Een `response_version` anders dan `1` of `2`	`product analytics response_version must be 1 or 2`

De fouten voor interval zijn dezelfde als de fouten in het overzicht. Twee segmenten met verschillende sleutels en identieke filters geven bijvoorbeeld:

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

Een ander label of een andere volgorde van eigenschapsfilters verandert de geselecteerde events niet. Een mislukte validatie is geen bewijs dat er geen events overeenkomen. Een GET-request geeft 405:

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

Response voor signaalvolume

GET /api/telemetry/summary/volume telt bewaarde signalen voor één project en tijdsbereik. De route vereist project_id en since. Ze accepteert geen project_ids. until mag niet in de toekomst liggen. Laat je het weg, dan is het einde het tijdstip van het request. Een korte since zoals 24h telt terug vanaf until. interval is auto, 1m, 5m, 15m, 1h, 6h of 1d. De standaardwaarde auto kiest het kleinste interval met hoogstens 120 tijdsintervallen. Een request mag niet meer dan 500 tijdsintervallen nodig hebben. De enige response_version is 1.

Signaalaantallen

Deze fictieve response beslaat twee tijdsintervallen van één minuut. Het request liep om 12:02 UTC zonder until. Het account heeft een bewaartermijn van 30 dagen. Lees de teruggegeven bewaartermijn en het grenstijdstip. Ga er niet van uit dat deze waarden voor jouw account gelden.

{
  "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"]
  }
}

Elk aantal in zijn eigen eenheid lezen

Signaal	Wat `total` telt	Lees het niet als
`issues`	Bewaarde issuevoorvallen	Gegroepeerde issues of getroffen gebruikers
`logs`	Bewaarde logevents	Requests
`traces`	Unieke trace-ID’s, geteld bij hun eerste bewaarde span in dit tijdvenster	Spans of alle tracestarts ooit
`actions`	Bewaarde actie-events	Gebruikers of sessies
`metrics`	Bewaarde metric-datapunten	De som van metricwaarden

total is de som van de aantallen per tijdsinterval in de tijdreeks. peak is het hoogste aantal in één tijdsinterval. non_empty_buckets telt tijdsintervallen met een aantal boven nul. De vijf tijdreeksen staan altijd in deze volgorde. Voeg verschillende signaalaantallen niet samen tot één impactscore. Tijdsintervallen beginnen bij query.since. Een tijdsinterval bevat zijn begin, maar niet zijn einde. Het laatste tijdsinterval kan korter zijn dan het interval. De response heeft geen tijdreeks met het aantal releases. Lees release_volume_not_included niet als nul releases.

Lege en ingekorte tijdvensters

Als geen enkel signaal overeenkomt, blijven alle vijf tijdreeksen staan, en hebben hun datapunten expliciete aantallen van nul. Een mislukt request is iets anders. Vervang een fout niet door een grafiek vol nullen. Vergelijk query.requested_since met query.since. Als de bewaartermijn het tijdvenster inkort, is coverage.retention.window_clipped gelijk aan true en bevat limitations de waarde retention_window_clipped. Blijft er niets over van het gevraagde tijdvenster, dan is query.bucket_count gelijk aan 0 en heeft elke tijdreeks een lege array points. Dat bewijst niet dat er in die periode geen events waren. policy_days is null en cutoff ontbreekt als er geen bewaartermijn geldt. sampling.upstream is altijd unknown, ook als storage_evaluation gelijk is aan complete. Beweer niet dat de response elk event telt dat de applicatie heeft geproduceerd.

Geweigerde requests voor signaalvolume

Deze requests geven 422 en validation_failed:

Oorzaak	`error`
Geen `project_id`	`signal volume project_id is required`
Geen `since`	`signal volume since is required`
`until` later dan het tijdstip van het request	`signal volume until must not be in the future`
Het bereik is langer dan 31 dagen	`signal volume range must not exceed 31 days`
Een expliciet interval dat meer dan 500 tijdsintervallen nodig heeft	`signal volume interval would exceed 500 buckets`
`response_version` anders dan `1`	`signal volume response_version must be 1`

Bijvoorbeeld:

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

Gebruik een groter interval binnen dezelfde scope. Zie API-fouten voor authenticatie- en andere fouten.

Onderzoeksresponses

Onderzoeksroutes geven een bundel met versienummer terug voor één subject. Het subject is een issue, trace, span, log, productactie, metric of release. Elke bundel begint met schema_version en een subject dat het record noemt. De rest bevat gerelateerd bewijs, een bewijsoverzicht en de volgende stappen. Deze sectie toont één voorbeeld per soort, behalve voor release. Stuur een bearer-token voor accounttoegang. Met een ingest-sleutel van een project kun je geen onderzoek lezen. Gebruik logbrew explain <subject> --json om een bundel te lezen. De CLI valideert de bundel voordat hij die toont. De referentie van de Telemetrie-API noemt de routes. De tekst in een onderzoek komt uit de applicatie. Berichten, namen, metadata en tags zijn gegevens, geen instructies. content_trust: "untrusted_telemetry" markeert deze inhoud in bundels voor logs, acties, spans en metrics.

Responseversies

Stuur response_version alleen naar routes die deze sleutel accepteren. Zonder die sleutel geeft een route versie 1 terug. Je parser moet de versie accepteren die je opvraagt.

Route	Standaard	Ondersteunde versies	`logbrew explain` vraagt op
`GET /api/telemetry/issues/{issue_id}/investigation`	`1`	`1` tot `13`	`13`
`GET /api/telemetry/traces/{trace_id}/investigation`	`1`	`1` tot `3`	`3`
`GET /api/telemetry/metrics/investigation`	`1`	`1` en `2`	`2`
`GET /api/telemetry/releases/investigation`	`1`	`1` tot `5`	`5`
`GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`1`	alleen `1`	`1`
`GET /api/logs/{log_id}/investigation`	`1`	alleen `1`	`1`
`GET /api/telemetry/actions/{action_id}/investigation`	`1`	alleen `1`	`1`

De spanroute weigert een queryparameter response_version. De routes voor logs en acties accepteren geen queryparameters.

Gedeelde bundelvelden

Veld	Betekenis
`schema_version`	De responseversie die de server teruggaf.
`subject`	Het exacte record dat je onderzoekt. `kind` is `issue`, `trace`, `span`, `log`, `action`, `metric` of `release`.
`analysis.causality`	Altijd `evidence_only` in bundels voor traces, spans, logs, acties en metrics. Gecorreleerde telemetrie bewijst geen oorzaak.
Collectieobjecten	Gerelateerd bewijs als `{ "status", "items", "truncated" }`.
`timeline`	Teruggegeven bewijs van oud naar nieuw, met een eigen vlag `truncated`. De volgorde bewijst geen oorzaak.
`evidence`	Het bewijsoverzicht. `status` is `complete` of `partial`.
`next_actions`	Voorgestelde leesacties op volgorde van `priority`, vanaf `1`. Ze zijn nog niet uitgevoerd.

Elke gerelateerde collectie meldt één status voor beschikbaarheid:

Status	Betekenis	Gedrag van de client
`available`	De leesactie is voltooid en gaf items terug.	Toon de items en de vlag `truncated`.
`not_linked`	Het subject heeft geen ID voor deze koppeling, zoals een trace-ID.	Leg uit dat de koppeling ontbreekt. Bouw er geen op basis van tijdstempels.
`not_found`	De leesactie is voltooid en vond geen bewaard bewijs.	Toon een leeg resultaat.
`unavailable`	De optionele leesactie is mislukt. Het subject is nog steeds geldig.	Houd het subject zichtbaar. Probeer het later opnieuw. Toon geen nul items als resultaat.

Het bewijsoverzicht heeft vier gesorteerde lijsten met vaste veldnamen: captured_fields, missing_fields, redacted_fields en truncated_fields. status is alleen complete als de laatste drie lijsten leeg zijn. Afgeschermde gegevens zijn geen ontbrekende gegevens. Afgekapte gegevens zijn geen volledige gegevens. Vul geen afgeschermde of afgekapte waarde in.

Limieten van een onderzoek

Deze limieten begrenzen één response. Een vlag truncated of een regel in truncated_fields laat zien dat een limiet gegevens heeft weggelaten.

Bewijs	Limiet
Gerelateerde items in één collectie	20
Gelezen bewaarde spans voor één trace	1.000
Items in de tijdlijn	50 voor bundels van logs, acties en spans. 100 voor bundels van traces en metrics.
Gestructureerde attributen, eigenschappen en metadata	64 scalaire waarden, 4 niveaus van objecten of arrays, 16 items per array, 512 tekens per string
Tijdvenster voor correlatie	5 minuten vóór en na een log, actie of geselecteerd issuevoorval. Voor een trace of span 5 minuten vóór de start en na het einde, hoogstens 24 uur.

Elke sectie per soort noemt haar eigen limieten.

Response van een issueonderzoek

Gebruik GET /api/telemetry/issues/{issue_id}/investigation om het bewijs voor één voorval van een gegroepeerd issue te lezen. De handleiding voor issueonderzoek laat zien in welke volgorde je het bewijs leest. Vraag versie 13 op:

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"

De queryparameters zijn response_version, selection en occurrence_id. selection is recommended, first of latest. De waarden zijn hoofdlettergevoelig. In versies 2 tot 13 gebruikt een weggelaten selector recommended. Versie 1 geeft het laatste bewaarde voorval terug en accepteert geen selector. Filters van de issuelijst gelden niet voor deze leesactie.

Voorbeeld van een issueonderzoek in versie 13

Deze fictieve response 200 OK heeft één afgehandeld voorval van TypeError met een gekoppelde trace. Er zijn geen request, breadcrumbs, gerelateerde logs of deploymentbewijs, dus evidence.status is partial.

{
  "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"
    }
  ]
}

Veld	Versie	Betekenis
`subject`	1	Het gegroepeerde issue. `first_seen_at`, `last_seen_at` en `occurrence_count` beschrijven de groep.
`event`	1	Het geselecteerde voorval: SDK, `context`, `exception`, `stack_frames` en `breadcrumbs`. In versie 1 `null` als er geen laatste voorval te lezen is.
`cause`	1	`status` is `reported_hypothesis`, `evidence_only` of `unknown`. `signals` noemt de waargenomen signalen.
`fix`	1	Een plek in de code. `status` is `reported_location`, `observed_application_frame`, `observed_frame`, `observed_underlying_exception_frame` of `unknown`.
`impact`	1	Aantallen voorvallen en `user_impact`. `reported` bevat impact die de applicatie meldt, of `null`.
`correlations`	1	`trace`, `logs`, `actions`, `metrics` en `release`.
`occurrence_selection`	2	De gevraagde selector, de reden en samenvattingen van het geselecteerde, eerste, laatste en aanbevolen voorval.
`lifecycle`	3	`persisted_status`, `effective_status`, statusactiviteit en `regression`. `effective_status` kan `regressed` zijn.
`occurrence_analysis`	4	Trend van voorvallen en de verdeling over releases, omgevingen, services en SDK’s.
`event.exception_chain`	5	Maximaal 8 gekoppelde exceptions. `relationship` is `reported`, `cause`, `context`, `aggregate_member` of `suppressed`.
`event.request`	6	`method`, `route_template` en `response_status_code`. De sleutel ontbreekt als er geen request is vastgelegd.
`grouping`	7	De `strategy` van de groepering, de `components` ervan en het gebruik van stackframes.
`correlations.release.deployment_status`	8	De status van het opzoeken van de deployment. `deployment`, `time_since_deployment_ms` en `deployment_causality` verschijnen alleen als er een deployment is gevonden.
`correlations.related_issues`	9	Andere issues op dezelfde trace.
`source_locator`	10	Repository, component, revisie en bestandspad binnen de repository, als LogBrew die kan koppelen.
`reproduction`	11	`status` is `ready`, `partial` of `insufficient_evidence`.
Code `verify_correction` in `next_actions`	12	Verschijnt als `reproduction.status` gelijk is aan `ready`.
`impact.user_impact.count_method`	13	Meldt een unieke telling bij benadering als `approximate_distinct`. Eerdere versies gebruiken een oudere waardenaam. `unavailable` betekent dat er geen telling is.

Sleutels uit een latere versie ontbreken in een eerdere versie. Lees een ontbrekende sleutel niet als null. subject.status en de statussen in lifecycle melden een gearchiveerd issue als ignored. Responses van de issuelijst en van issuedetails gebruiken archived vanaf responseversie 2. Limieten voor issues: de aanbeveling leest hoogstens 50 bewaarde voorvallen. De trend heeft hoogstens 30 tijdsintervallen. Elke verdeling geeft hoogstens 10 waarden terug. Een stack heeft hoogstens 32 frames.

Requestfouten bij een issueonderzoek

Gebruik selection of occurrence_id. Stuur ze niet allebei, ook niet als ze hetzelfde voorval selecteren:

{
  "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`	Oorzaak	Herstel
`422`	`selection and occurrence_id are mutually exclusive`	Het request heeft beide selectors.	Houd één selector.
`422`	`issue occurrence selection requires response_version=2 through 13`	Het request heeft een selector en versie 1, of geen versie.	Stuur `response_version=13`. Houd de selector.
`422`	`issue investigation response_version must be 1 through 13`	De versie valt buiten het bereik.	Stuur een ondersteunde versie.
`422`	`invalid query parameters`	Een onbekende sleutel, een ongeldige UUID, een versie die geen geheel getal is, of een onbekende waarde voor `selection`.	Corrigeer de query.
`404`	`issue occurrence not found`	Het voorval zit niet in de bewaarde geschiedenis van deze groep.	Kopieer het voorval-ID uit de events van dit issue. Gebruik niet zonder goedkeuring `latest` of `recommended` in plaats daarvan.
`404`	`issue not found`	Geen enkel leesbaar project heeft dit issue.	Controleer het account en de UUID van het issue. Stuur geen UUID van een voorval als issue-ID.

Een ontbrekend voorval betekent niet dat het issue ontbreekt. Een 404 laat niet zien of een ander account het issue kan lezen.

Response van een traceonderzoek

Gebruik GET /api/telemetry/traces/{trace_id}/investigation om één trace te lezen met het foutpad, het traagste pad en gerelateerde signalen. De queryparameters zijn response_version, project_id, release en environment. Ze zijn allemaal optioneel. Vraag versie 3 op:

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"

Versie 2 voegt cause en fix toe aan elk gerelateerd issue. Versie 3 voegt span_id toe aan gerelateerde issues, acties en metrics, als dat is vastgelegd.

Voorbeeld van een traceonderzoek in versie 3

Deze fictieve response heeft een server-rootspan en een mislukte client-span. De mislukte span is ook de traagste onderliggende span. De spans hebben geen gestructureerde context, dus spans.context ontbreekt.

{
  "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
    }
  ]
}

Veld	Betekenis
`subject`	Tracetotalen uit de geanalyseerde spans.
`analysis.status`	`errors_observed`, `latency_focus` of `no_error_observed`.
`analysis.first_error_path`	De bekende keten van bovenliggende spans van de root tot de vroegste foutspan.
`analysis.bottleneck_path`	De bekende keten van bovenliggende spans tot de traagste onderliggende span.
`spans.items[].roles`	Waarom de span in de preview staat: `root`, `first_error`, `error_path`, `bottleneck`, `bottleneck_path`, `error` of `slow`.
`correlations.window`	Het tijdsbereik en de deploymentscopes voor gerelateerde leesacties.
`correlations.issues`, `logs`, `actions`, `metrics`	Signalen met hetzelfde trace-ID in het tijdvenster.

trace.parentage ontbreekt als een span een bovenliggende span noemt die LogBrew niet heeft bewaard. De spanpreview heeft hoogstens 64 spans. Elk analysepad heeft hoogstens 64 spans. Gerelateerde leesacties gebruiken hoogstens 8 deploymentscopes. Een volgende actie met als doel trace_span noemt een span_id uit deze bundel. Roep de spanroute aan met de project_id, environment en release van die span om de span te lezen.

Response van een spanonderzoek

Gebruik GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation om één bewerking in een trace te lezen. Stuur project_id, environment en release. Alle drie zijn verplicht. Kopieer ze van de geselecteerde span. Stuur de id van de spanrij niet als span_id.

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"

Voorbeeld van een spanonderzoek

Deze fictieve response beschrijft de mislukte client-span uit het tracevoorbeeld. Een foutlog heeft hetzelfde span-ID. De span duurde langer dan het 95e percentiel bij benadering van de bewaarde vergelijkbare spans.

{
  "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
    }
  ]
}

Veld	Betekenis
`payload`	`metadata` van de span, maximaal 8 `events` en maximaal 8 `links`. Ze delen samen een budget van 64 waarden.
`analysis.observations`	`subject_error`, `child_error`, `exact_span_error_log`, `related_issue`, `subject_at_or_above_peer_p95` of `subject_at_or_above_peer_p99`.
`topology`	`root`, `parent`, `ancestors`, directe `children`, `descendant_count` en `cross_service_edges`.
`topology.parent_chain_status`	`root`, `complete`, `missing`, `cycle`, `truncated` of `unavailable`.
`baseline`	Eerdere spans met hetzelfde project, dezelfde omgeving, release, service, bewerking en naam.
`correlations.logs`	Logs met hetzelfde trace-ID en span-ID.
`correlations.issues`, `actions`, `metrics`	Signalen met hetzelfde trace-ID in hetzelfde project, dezelfde omgeving en dezelfde release.
`timeline[].offset_ms`	Milliseconden vanaf de start van de span. Een negatieve waarde ligt vóór de span.

De referentie leest de 24 uur vóór de start van de span. since telt mee en until niet. error_rate_basis_points: 500 betekent 5%. subject_percentile_basis_points: 9500 betekent dat 95% van de bewaarde vergelijkbare spans niet langer duurde dan deze span. Percentielen zijn bij benadering. Houd baseline.limitations bij de waarden. Een referentie met not_found heeft geen bewaarde vergelijkbare spans. Een referentie met unavailable is een mislukte leesactie, geen aantal van nul. parent_chain_status: "complete" betekent dat de bewaarde keten een root bereikt. Het bewijst niet dat LogBrew elke span van het request heeft bewaard. De topologie geeft hoogstens 64 voorouders, 50 directe kinderen en 50 verbindingen tussen services terug.

HTTP	`error`	Herstel
`422`	`trace_id must be a non-zero 32-character hexadecimal value`	Kopieer `trace_id` uit een trace-response van LogBrew.
`422`	`span_id must be a non-zero 16-character hexadecimal value`	Kopieer `span_id` uit een trace-response van LogBrew.
`422`	`environment and release must be non-empty exact span scope values`	Kopieer de scope van de geselecteerde span.
`422`	`invalid query parameters`	Stuur `project_id`, `environment` en `release`, en geen andere sleutel.
`404`	`span not found`	Controleer de ID’s, het project, de omgeving en de release.

Response van een logonderzoek

Gebruik GET /api/logs/{log_id}/investigation om één log en het gerelateerde bewijs te lezen. Deze route heeft geen queryparameters. Kopieer het log-ID uit een loglijst.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/logs/$LOG_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

De leesactie kan bewijs teruggeven buiten de filters van de loglijst. Gerelateerde leesacties gebruiken het project, de omgeving en de release van de log, en 5 minuten vóór en na de log. Logs in de buurt gebruiken ook dezelfde service. Die hebben geen trace-ID nodig. Leesacties op de exacte trace hebben het trace-ID van de log nodig en kunnen andere services bevatten. De tracesamenvatting gebruikt hetzelfde trace-ID en dezelfde scope, zonder het tijdvenster.

Voorbeeld van een logonderzoek

Deze fictieve response heeft een waarschuwingslog zonder tracecontext en één log in de buurt. De response bouwt geen tracekoppeling op basis van de tijdstempels.

{
  "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
    }
  ]
}

Veld	Betekenis
`attributes`	De begrensde gestructureerde attributen. `values` bevat geen `context`. Die staat in het veld `context` op het hoogste niveau.
`analysis.status`	`critical_evidence`, `error_evidence`, `warning_evidence` of `no_failure_observed`.
`correlations.trace`	Het trace-ID, het span-ID, `exact_span` en de `summary` van de trace.
`correlations.trace_logs`	Logs met hetzelfde trace-ID. `relationship` is `exact_trace`.
`correlations.nearby_logs`	Logs van dezelfde service in het tijdvenster. `relationship` is `nearby_scope`. Het subject en de logs van de exacte trace tellen niet mee.
`correlations.issues`, `actions`, `metrics`	Signalen met hetzelfde trace-ID.
`correlations.release`	De releasescope voor een releaseonderzoek. Het bevat geen vergelijking.
`timeline[].relationship`	`subject`, `exact_span`, `exact_trace` of `nearby_scope`.

Een trace-ID kan aanwezig zijn als de tracestatus not_found of unavailable is. Een beschikbare tracesamenvatting garandeert geen exact_span.

Response van een actieonderzoek

Gebruik GET /api/telemetry/actions/{action_id}/investigation om één productactie te lezen, met de gemelde status en gerelateerd bewijs. Deze route heeft geen queryparameters. Gerelateerde leesacties gebruiken hetzelfde tijdvenster en dezelfde scopes als een logonderzoek.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/telemetry/actions/$ACTION_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

correlations, timeline en next_actions gebruiken de vormen van een logonderzoek. Gerelateerde acties bevatten de onderzochte actie zelf niet.

Voorbeeld van een actieonderzoek

Deze fictieve response beschrijft een mislukte checkoutactie van een ingelogde gebruiker. De actie heeft geen trace-ID.

{
  "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
    }
  ]
}

Veld	Betekenis
`subject.status`	`queued`, `running`, `success`, `failure`, of `null` als er geen ondersteunde status is vastgelegd.
`subject.subject_classification`	`user`, `anonymous`, `legacy_unknown`, `missing`, `historical_unindexed` of `unsupported`.
`subject.session_captured`	Of de actie een sessie had. De response geeft het sessie-ID nooit terug.
`properties`	Het begrensde object `metadata` van de actie.
`analysis.status`	`subject_failure`, `correlated_failure_evidence`, `in_progress`, `success_observed` of `status_not_captured`.

De response geeft nooit ID’s van subjecten of sessies terug. Het bewijsoverzicht noemt subject.distinct_id altijd als afgeschermd, en ook subject.session_id als er een sessie is vastgelegd. Daarom is elke actiebundel partial en bevat die improve_capture. Verwijder geen privacymaatregelen om daaraan te voldoen.

Response van een metriconderzoek

Gebruik GET /api/telemetry/metrics/investigation om één metricnaam in één project en tijdsbereik te lezen. De response bevat de huidige tijdreeks, een vergelijking met het voorgaande tijdvenster van dezelfde lengte, de laatste meting, trace-exemplars en voltooide deployments. Versie 2 voegt de beschrijving van de metric uit de laatste bewaarde meting toe. Versie 1 meldt altijd description_status: "not_captured".

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 en since zijn verplicht. since telt mee en until niet. Standaard is until gelijk aan nu. De vergelijking leest ook het voorgaande tijdvenster van dezelfde lengte.

Voorbeeld van een metriconderzoek in versie 2

Dit fictieve histogram heeft 5 metingen in twee tijdsintervallen van 5 minuten. Het laatste tijdsinterval heeft een p95 van 48 ms. Het laatste tijdsinterval van het vorige tijdvenster heeft een p95 van 24 ms.

{
  "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"
      }
    }
  ]
}

Veld	Betekenis
`subject.description_status`	`captured`, `not_captured` of `unavailable`.
`query`	De genormaliseerde query. `service_name`, `release` en `environment` verschijnen alleen als je ze stuurt.
`analysis.status`	`no_samples`, `change_observed`, `no_change_observed`, `baseline_not_found` of `comparison_unavailable`.
`analysis.focus`	Het vergelijkingsitem met de grootste relatieve verandering, of de grootste absolute verandering als er geen relatieve verandering is. `null` als geen enkel item vergelijkbaar is.
`series[].aggregation.code`	`gauge_last`, `delta_sum`, `distribution_p95`, `raw_cumulative_last` of `raw_last`.
`comparison.status`	`available`, `partial`, `not_found`, `unavailable` of `no_current_samples`.
`comparison.items[]`	Het laatste niet-lege tijdsinterval van elk tijdvenster voor dezelfde tijdreeks.
`latest_sample`	De laatste ruwe meting, met SDK, `context`, `metadata` en tracekoppeling.
`exemplars`	Ruwe metingen met een trace-ID. `coverage` telt de gekoppelde metingen.
`deployments`	Voltooide deployments vanaf het begin van het vorige tijdvenster tot `until`.
`next_actions[]`	`code`, `target`, een `reason` in platte tekst en een scope in `context` voor de volgende leesactie.

relative_change_percent is (current - previous) / abs(previous) * 100. Het is null als de vorige waarde nul is of ontbreekt. expected_buckets_per_series telt mogelijke tijdsintervallen, geen tijdsintervallen met gegevens. Teken lege tijdsintervallen niet als nul. Een deployment vlak bij een verandering bewijst niet dat die de verandering veroorzaakte. Een project dat het account niet kan lezen, geeft 200 OK met analysis.status: "no_samples", geen 404. Een leeg resultaat zegt niets over andere signaaltypen. Limieten voor metrics: het bereik is hoogstens 31 dagen. Elke tijdreeks heeft hoogstens 500 tijdsintervallen. series_limit is 1 tot 20, standaard 10. De response geeft hoogstens 20 exemplars en 20 deployments terug.

HTTP	`error`	Herstel
`422`	`metric investigation response_version must be 1 or 2`	Laat `response_version` weg of stuur `2`.
`422`	`metric series project_id is required`	Stuur één leesbaar project-ID.
`422`	`metric series name is required`	Kopieer de naam uit de metriclijst.
`422`	`metric series since is required`	Stuur een waarde zoals `24h` of een RFC 3339-tijdstempel.
`422`	`metric series range must not exceed 31 days`	Gebruik een korter bereik.
`422`	`metric series interval would exceed 500 buckets`	Gebruik `interval=auto` of een groter interval.
`422`	`metric series_limit must be between 1 and 20`	Stuur een waarde van 1 tot 20.

interval is auto, 1m, 5m, 15m, 1h, 6h of 1d. group_by is none, service_name, release of environment. Andere waarden geven 422.

Onderzoeksfouten

HTTP	Route	`error`
`404`	Log	`log not found`
`404`	Actie	`action not found`
`404`	Trace	`trace not found`
`422`	Trace	`trace investigation response_version must be 1, 2, or 3`
`400`	Log, actie, issue	`invalid URL path parameters` als het ID in het pad geen UUID is
`422`	Issue, trace, span, metric	`invalid query parameters` bij een onbekende sleutel of een waarde van het verkeerde type

Een 404 betekent dat geen enkel leesbaar project het record heeft. Elke route geeft ook 401 zonder geldige authenticatie en 405 voor een andere methode dan GET. Zie API-fouten voor de responses bij niet gevonden, pad, authenticatie en methode. Een optionele leesactie voor bewijs kan mislukken binnen een response 200 OK. De collectie meldt dan unavailable. Toon dat niet als not_found of als nul records.

Ernstwaarden

De ernstwaarden die gebruikers zien, zijn info, warning, error en critical. SDK’s en runtimes kunnen gangbare aliassen sturen, zoals trace, debug, warn of fatal. REST- en live-responses geven altijd de canonieke waarde terug. LogBrew accepteert bijvoorbeeld warn als invoer en geeft warning terug. De ingest-API weigert onbekende ernstwaarden.

Alias	Canonieke waarde
`trace`, `debug`	`info`
`warn`	`warning`
`fatal`	`critical`

Responses van ernstregels

Een ernstregel verandert hoe LogBrew een log of issue toont. De regel verandert niet de ernst die de applicatie heeft vastgelegd. Logs en issues geven een object triage terug:

Veld	Betekenis
`effective_severity`	De ernst om te tonen. Zonder regel is die gelijk aan `severity`.
`ignored`	`true` als een logregel de log negeert, of als het issue is gearchiveerd.
`rule_applied`	`true` als een ernstregel of de genegeerde toestand geldt. `false` is de standaardwaarde, geen ontbrekende gegevens.

Gebruik triage.effective_severity voor weergave. Houd severity als de vastgelegde waarde. Standaard laat de loglijst genegeerde logs weg. Stuur status=ignored of status=all op GET /api/logs om ze mee te nemen. Het account moet issues in het project mogen beheren. Leestoegang is niet genoeg. Zonder die toestemming geeft een regelwijziging 403 met code: forbidden.

Een logregel wijzigen

PUT /api/logs/{log_id}/triage-rule stelt de regel in voor de log en voor latere logs met dezelfde signatuur. De body heeft zowel severity als ignored nodig:

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

Een response 200 OK bevat de volledige log. De severity blijft warning. De triage toont de regel:

{
  "severity": "warning",
  "triage": {
    "effective_severity": "info",
    "ignored": true,
    "rule_applied": true
  }
}

Dit fragment toont alleen de gewijzigde velden. severity in het request is source, info, warning, error of critical. source zet de vastgelegde ernst terug. Een genegeerde log wordt daardoor niet weer actief. Stuur "ignored": false om de log weer te tonen.

Een issueregel wijzigen

PUT /api/telemetry/issues/{issue_id}/triage-rule stelt de getoonde ernst in van een gegroepeerd issue en de latere voorvallen ervan. De body accepteert alleen severity:

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

Een response 200 OK bevat het volledige issue in versie 1. De vastgelegde severity en status veranderen niet:

{
  "severity": "error",
  "status": "unresolved",
  "triage": {
    "effective_severity": "warning",
    "ignored": false,
    "rule_applied": true
  }
}

Dit fragment toont maar een deel van de velden. Een regel lost een issue niet op, archiveert het niet en heropent het niet. Gebruik daarvoor de statuswijziging. Een afgeleide prioriteit volgt de nieuwe effectieve ernst. Lees het issue met response_version=2 of 3 om die te zien. Een niet-ondersteunde ernst geeft 422:

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

Een onbekend veld in de body, zoals status bij een issueregel, geeft 422 met code: invalid_json. Een log of issue dat ontbreekt of niet leesbaar is, geeft 404 met code: not_found. Is de response verloren gegaan? Lees dan de log of het issue opnieuw voordat je de regel opnieuw stuurt.

Formaat van foutresponses

Applicatiefouten geven een JSON-envelop terug. Dit voorbeeld toont een geweigerd request. De tekst in error en next hangt af van het probleem:

{
  "error": "<what is wrong>",
  "code": "validation_failed",
  "next": "<how to fix it>",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Gebruik code voor vertakkingen in je programma en next_action voor automatisering. Toon error en next als platte tekst aan mensen. Parse hun formulering niet. Sommige fouten voegen velden toe, zoals limit, reset_at of retry_after_seconds. Een response zonder JSON-body heeft geen code van LogBrew. Zie API-fouten voor alle codes.

Gegevens lezen met de CLI

De CLI leest dezelfde routes en geeft met --json dezelfde JSON terug. Begin breed en verfijn daarna:

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

Voeg --pagination cursor toe voor de cursorenvelop. De CLI vraagt versie 4 van de issueresponse op. Zie De volgende pagina lezen en Live volgen.

​Een response lezen

​Wat je verstuurt

​Response van de ingest-API

​Response op een SDK-batch

​Response op een native envelop

​Opnamefouten

​Responseformaat van telemetrielijsten

​Logresponse

​Issueresponse

​Response met toewijsbare accounts en teams

​Actieresponse

​Metricresponse

​Releaseresponse

​Response bij het zoeken naar traces

​Lege lijsten en ontbrekende records

​Geweigerde projectselecties

​Cursorfouten

​Responses van de releasecursor

​Fouten bij het zoeken naar traces

​Voorvalgeschiedenis van een issue

​Responses voor trace-spans en samenvattingen

​Spanlijst

​Tracesamenvatting

​Geen overeenkomende spans

​Responseformaat van live-events

​Een ticket aanmaken

​De verbinding openen

​De berichten lezen

​Een gesloten verbinding afhandelen

​Responsevoorbeelden voor de issuestatus

​Scope van analyserequests

​Gedeelde scopefouten

​Response van het overzicht voor productanalyse

​Geslaagd overzicht

​Het overzicht lezen

​Fouten in het overzicht

​Response van een geordende trechter

​Geslaagde trechter

​Conversie en dekking lezen

​Lege trechterresultaten

​Geweigerde trechterrequests

​Analyse op exacte events en automatische analyse

​Request voor retentie op exacte events

​Geslaagde retentie op exacte events

​Retentie lezen

​Automatische retentie

​Retentie zonder gebruikers die in aanmerking komen

​Retentiefouten

​Request voor levenscyclus op een exact event

​Geslaagde levenscyclus op een exact event

​Levenscyclus lezen

​Automatische levenscyclus

​Levenscyclus zonder gebruikers

​Levenscyclusfouten

​De gekozen analysescope lezen

​Response voor metric-tijdreeksen

​Geslaagde metric-tijdreeks

​Een metric-tijdreeks lezen

​Scope en fouten van metric-tijdreeksen

​Response van padanalyse

​Geslaagde padanalyse

​Paden lezen

​Het anker filteren op eigenschap

​Lege paden en geweigerde requests

​Eigenschappencatalogus voor productanalyse

​Beschikbare eigenschapssleutels lezen

​Geslaagde eigenschappencatalogus

​De catalogus interpreteren

​Fouten in de eigenschappencatalogus

​Segmentvergelijking in productanalyse

​De vergelijking definiëren

​Geslaagde segmentvergelijking

​Ratio’s en verschillen lezen

​Fouten in segmentvergelijkingen

​Response voor signaalvolume

​Signaalaantallen

​Elk aantal in zijn eigen eenheid lezen

​Lege en ingekorte tijdvensters

​Geweigerde requests voor signaalvolume

​Onderzoeksresponses

Een response lezen

Wat je verstuurt

Response van de ingest-API

Response op een SDK-batch

Response op een native envelop

Opnamefouten

Responseformaat van telemetrielijsten

Logresponse

Issueresponse

Response met toewijsbare accounts en teams

Actieresponse

Metricresponse

Releaseresponse

Response bij het zoeken naar traces

Lege lijsten en ontbrekende records

Geweigerde projectselecties

Cursorfouten

Responses van de releasecursor

Fouten bij het zoeken naar traces

Voorvalgeschiedenis van een issue

Responses voor trace-spans en samenvattingen

Spanlijst

Tracesamenvatting

Geen overeenkomende spans

Responseformaat van live-events

Een ticket aanmaken

De verbinding openen

De berichten lezen

Een gesloten verbinding afhandelen

Responsevoorbeelden voor de issuestatus

Scope van analyserequests

Gedeelde scopefouten

Response van het overzicht voor productanalyse

Geslaagd overzicht

Het overzicht lezen

Fouten in het overzicht

Response van een geordende trechter

Geslaagde trechter

Conversie en dekking lezen

Lege trechterresultaten

Geweigerde trechterrequests

Analyse op exacte events en automatische analyse

Request voor retentie op exacte events

Geslaagde retentie op exacte events

Retentie lezen

Automatische retentie

Retentie zonder gebruikers die in aanmerking komen

Retentiefouten

Request voor levenscyclus op een exact event

Geslaagde levenscyclus op een exact event

Levenscyclus lezen

Automatische levenscyclus

Levenscyclus zonder gebruikers

Levenscyclusfouten

De gekozen analysescope lezen

Response voor metric-tijdreeksen

Geslaagde metric-tijdreeks

Een metric-tijdreeks lezen

Scope en fouten van metric-tijdreeksen

Response van padanalyse

Geslaagde padanalyse

Paden lezen

Het anker filteren op eigenschap

Lege paden en geweigerde requests

Eigenschappencatalogus voor productanalyse

Beschikbare eigenschapssleutels lezen

Geslaagde eigenschappencatalogus

De catalogus interpreteren

Fouten in de eigenschappencatalogus

Segmentvergelijking in productanalyse

De vergelijking definiëren

Geslaagde segmentvergelijking

Ratio’s en verschillen lezen

Fouten in segmentvergelijkingen

Response voor signaalvolume

Signaalaantallen

Elk aantal in zijn eigen eenheid lezen

Lege en ingekorte tijdvensters

Geweigerde requests voor signaalvolume

Onderzoeksresponses