Add CLI support for fetching logs associated with a trace

[betegon]

Summary

Provide a CLI way to fetch logs associated with a trace — the same logs shown in the trace UI "Logs" tab.

Current State

There is no dedicated "logs per trace" command. Attempting sentry log list -q "trace:<trace-id>" does not work because the current implementation queries the Explore/Events logs dataset endpoint (/organizations/{org}/events/?dataset=logs), which does not support filtering by trace ID in query syntax.

Technical Finding

Trace logs must be fetched via a dedicated endpoint:

GET /organizations/{org}/trace-logs/?traceId=<trace-id>&statsPeriod=<period>

Key details:

• statsPeriod is required — without it, the API may return an empty result set even when logs exist for the trace.
• The response schema differs from the Explore/Events logs endpoint (e.g. id instead of sentry.item_id, includes project.id and severity_number).

Working example:

# Returns empty — missing statsPeriod
$ sentry api "organizations/my-org/trace-logs/?traceId=618d343b2eb84a888311abdff612c8fb"
{ "data": [] }

# Returns logs — statsPeriod included
$ sentry api "organizations/my-org/trace-logs/?statsPeriod=14d&traceId=618d343b2eb84a888311abdff612c8fb"
{ "data": [{ "id": "...", "severity": "warn", "message": "After error", ... }] }

Proposal

Add first-class trace logs support to the CLI. Options to consider:

Option A: Extend sentry log list with --trace-id

sentry log list --trace-id <trace-id>
sentry log list -t <trace-id>

When --trace-id is provided, route to the /trace-logs/ endpoint instead of /events/?dataset=logs. Would also need to handle statsPeriod (either a sensible default like 14d, or expose via --period flag). Note: the trace-logs/ endpoint is org-scoped (no project required), so project resolution could become optional in this path.

Option B: Add --logs flag to sentry trace view

sentry trace view <org>/<project> <trace-id> --logs

Print logs after the span tree in trace view output. Keeps trace-related data together in one command.

Option C: Dedicated sentry trace logs subcommand

sentry trace logs <trace-id>
sentry trace logs <org> <trace-id>

A subcommand under the trace group, aligned with the API structure. Clear separation from the existing sentry log list / sentry log view commands.

Design Considerations

• Avoid ambiguity with existing log view: sentry log view currently views a single log entry by its item ID. A syntax like <org>/<project>@<id> could be ambiguous between event-id and trace-id. Prefer:
  • A flag (--trace-id), and/or
  • A dedicated trace logs command namespace, and/or
  • A clearly non-ambiguous trace-specific identifier format (trace IDs are 32-char hex)
• statsPeriod handling: The API requires it. A default (e.g. 14d) is needed, with an optional override flag.
• --follow compatibility: If extending sentry log list, consider whether --follow + --trace-id should be supported or treated as mutually exclusive.