> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> How LogBrew models logs, traces, issues, and actions so developers and AI agents can correlate production behavior.

LogBrew stores first-party telemetry in four streams. They share the same
project, service, release, environment, and trace context so agents can move
between them without guessing.

In plain terms, telemetry is the evidence your app sends out while it runs. A
log says what happened, a trace shows where it happened in a request, an issue
groups repeated failures, and an action records a product event.

<CardGroup cols={2}>
  <Card title="Logs" icon="file-text">
    Point-in-time messages from runtime, build, or application code. Logs are
    best for local facts such as route, user ID, status code, and error text.
  </Card>

  <Card title="Trace spans" icon="route">
    Timed operations inside one distributed trace. Spans answer where time was
    spent and which operation failed.
  </Card>

  <Card title="Issues" icon="bug">
    Grouped failures. LogBrew turns issue events into stable fingerprints so
    repeated crashes become one issue with an occurrence count.
  </Card>

  <Card title="Actions" icon="mouse-pointer-click">
    Product events. Actions answer what users or systems did, such as
    `checkout_failed`, `invite_sent`, or `plan_changed`.
  </Card>
</CardGroup>

## Shared fields

| Field          | Why it matters                                               |
| -------------- | ------------------------------------------------------------ |
| `project_id`   | Owns the telemetry and controls access.                      |
| `service_name` | Names the app or service that emitted the data.              |
| `release`      | Required. Ties every signal to the deployed code version.    |
| `environment`  | Separates production, staging, preview, and local data.      |
| `trace_id`     | Correlates logs, spans, issues, and actions for one request. |

## Severity values

For streams that carry severity, LogBrew uses four canonical user-facing
values: `info`, `warning`, `error`, and `critical`.

| Canonical value | Common SDK or runtime aliases |
| --------------- | ----------------------------- |
| `info`          | `trace`, `debug`, `info`      |
| `warning`       | `warn`, `warning`             |
| `error`         | `error`                       |
| `critical`      | `fatal`, `critical`           |

Use the canonical values in dashboards, CLI output, API output, live responses,
and examples. SDKs may accept common aliases as input compatibility, but
unknown severity or level values are rejected.

## Agent investigation pattern

<Steps>
  <Step title="Find the release">
    Read release summaries first to see which version has new issues, logs,
    trace spans, or actions.

    ```bash theme={null}
    logbrew read releases --environment production --json
    ```
  </Step>

  <Step title="Read unresolved issues">
    Grouped issues show the title, severity, message, status, first seen time,
    last seen time, and occurrence count.

    ```bash theme={null}
    logbrew read issues --release api@1.2.3 --status unresolved --json
    ```
  </Step>

  <Step title="Follow the trace">
    Use the issue or log `trace_id` to read all spans for the request.

    ```bash theme={null}
    logbrew read trace 4bf92f3577b34da6a3ce929d0e0e4736 --json
    ```
  </Step>

  <Step title="Check actions">
    Actions show product impact, such as which users hit a failed checkout.

    ```bash theme={null}
    logbrew read actions --name checkout_failed --since 24h --json
    ```
  </Step>
</Steps>