# Structured logs

> https://docs.errora.org/en/products/logs

Logs sit next to your errors instead of in a separate tool: same project, same trace ids,
same search box.

## Setup

### Python

```python
sentry_sdk.init(dsn="…", enable_logs=True)
```

Standard-library logging is forwarded automatically, `extra` fields become typed attributes:

```python
logger.warning("retrying payment", extra={"order_id": order.id, "attempt": 3})
```

### JavaScript / Node.js

```javascript
Sentry.init({ dsn: "…", _experiments: { enableLogs: true } });

const { logger } = Sentry;
logger.info("payment captured", { orderId, amount });
logger.error("gateway rejected", { orderId, code });
```

### PHP / Laravel

Add the `sentry` log channel (see [PHP & Laravel](/en/platforms/php-laravel#logs)) and use
`Log::info(...)` as usual.

### Raw HTTP

Logs travel as a `log` envelope item — a batch container of typed items:

```json
{"items":[{"timestamp":1767225600.0,"level":"info","body":"backup finished",
           "trace_id":"7b3f…","attributes":{"host":{"value":"db-1","type":"string"},
                                            "bytes":{"value":10485760,"type":"integer"}}}]}
```

## Levels

`trace`, `debug`, `info`, `warn`, `error`, `fatal`. Levels are facets in the UI, so you can
see the shape of your log volume before filtering.

## Searching

**Logs** in the sidebar gives you:

- **Full-text search** over the log body, using the database's native FTS with word-prefix
  semantics.
- **Level facets** with counts.
- **Attribute filters** — every attribute key your SDK has sent is offered by
  `GET /projects/{id}/logs/attribute-keys`.
- **Time period** selection.
- **User filter** — narrow the stream to one person (matched against the `user.id`,
  `user.email` and `user.name` attributes), the same filter issues, requests and jobs carry.
- **Trace correlation** — a log line carrying a `trace_id` links to the transaction that
  produced it, and vice versa.

## API

```text
GET /api/v1/projects/{project_id}/logs?q=&level=&environment=&user=&stats_period=24h
GET /api/v1/projects/{project_id}/logs/attribute-keys
GET /api/v1/projects/{project_id}/logs/{log_id}
```

AI agents can search logs over [MCP](/en/products/mcp) with `search_logs`.

## Cost and retention

Logs are metered with errors as the **Error/Log** service — see [Wallet](/en/billing/wallet).
They are deleted by the same nightly retention job as events; set `retention_days` per
organization in **Settings → Retention**.

Keep the volume sane:

- Log at `info` and above in production; keep `debug` for local work.
- Put identifiers in **attributes**, not in the message text — attributes are filterable,
  and identical bodies group better.

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| No logs arriving | The logging integration is off (`enable_logs` / `enableLogs`), or the SDK version predates it |
| Logs but no trace link | The log was emitted outside an active span — start a transaction around the work |
| Attributes missing | They were passed as a formatted string instead of structured fields (`extra=`, second argument) |
| Search finds nothing | FTS uses word prefixes — search `time` not `imeou`; wildcards are implicit at the end only |