Structured logs

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

Setup

Python

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

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

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

JavaScript / Node.js

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) and use Log::info(...) as usual.

Raw HTTP

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

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

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 with search_logs.

Cost and retention

Logs are metered with errors as the Error/Log service — see 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