fix(log): use 30d default period and show newest logs first (#568)

## Summary

- Fix `sentry log list` returning stale/incomplete data by changing the
default `statsPeriod` from `90d` to `30d` (log retention is 30 days —
periods >30d hit a degraded API path)
- Change default sort order to newest-first for one-shot queries, add
`--sort` flag (`newest`/`oldest`)
- Keep chronological (oldest-first) ordering for `--follow` mode
- Sort is server-side (`-timestamp` / `timestamp` API param), not
client-side array reversal

**Root cause confirmed via API testing:**

| Period | Count | Newest | Status |
|--------|-------|--------|--------|
| 14d | 19 | 16:42:23 | correct |
| 30d | 82 | 16:42:23 | correct |
| 60d | 13 | 15:21:42 | **stale** |
| 90d | 13 | 15:21:42 | **stale** |

## Design decisions

- **Server-side sorting**: The `--sort` flag maps to the API `sort`
parameter (`"newest"` → `"-timestamp"`, `"oldest"` → `"timestamp"`)
rather than reversing arrays client-side. This matches the pattern used
by `trace list` and `span list`.
- **`LogSortDirection` type in API layer**: Defined and exported from
`src/lib/api/logs.ts`, following the convention of `SpanSortValue` in
`api/traces.ts`. Re-exported via `api-client.ts`.
- **`parseLogSort` naming**: The shared parser in `arg-parsing.ts` is
named `parseLogSort` (not `parseSort`) to avoid collisions with the
three existing per-command `parseSort` functions that operate on
different sort vocabularies (`date`/`duration`,
`date`/`new`/`freq`/`user`).
- **Follow mode unaffected**: `--follow` streaming always fetches
newest-first and displays in arrival order. The `--sort` flag only
affects one-shot fetch mode.

## Test plan
- [x] Updated unit tests for new default period (`30d`) and newest-first
ordering
- [x] Added test for `--sort oldest` flag — verifies API receives `sort:
"oldest"`
- [x] Tests verify sort param is passed through to API (not just output
order)
- [x] All 65 unit tests pass across `log/list` and `trace/logs`
- [ ] Manual: `sentry logs <org>/<project>` shows recent logs, newest at
top
- [ ] Manual: `sentry logs <org>/<project> --sort oldest` shows oldest
at top
- [ ] Manual: `sentry logs <org>/<project> -f` follow mode still
chronological

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Burak Yigit Kaya <byk@sentry.io>

Author: 4 people

docs/src/content/docs/commands/log.md

@@ -36,6 +36,8 @@ sentry log list <project>
 | `-n, --limit <n>` | Number of log entries to show (1-1000, default: 100) |
 | `-q, --query <query>` | Filter query (Sentry search syntax) |
 | `-f, --follow [interval]` | Stream logs in real-time (optional: poll interval in seconds, default: 2) |
+| `-t, --period <period>` | Time period (e.g., "30d", "14d", "24h"). Default: 30d. Log retention is 30 days. |
+| `-s, --sort <order>` | Sort order: "newest" (default) or "oldest" |
 | `--json` | Output as JSON |
 
 **Examples:**

plugins/sentry-cli/skills/sentry-cli/references/logs.md

@@ -19,7 +19,8 @@ List logs from a project
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
-- `-t, --period <value> - Time period (e.g., "90d", "14d", "24h"). Default: 90d (project mode), 14d (trace mode)`
+- `-t, --period <value> - Time period (e.g., "30d", "14d", "24h"). Default: 30d (project mode), 14d (trace mode)`
+- `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
 **JSON Fields** (use `--json --fields` to select specific fields):

plugins/sentry-cli/skills/sentry-cli/references/traces.md

@@ -88,6 +88,7 @@ View logs associated with a trace
 - `-t, --period <value> - Time period to search (e.g., "14d", "7d", "24h"). Default: 14d - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (<=1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
+- `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 
 All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

src/commands/log/list.ts

@@ -9,9 +9,17 @@
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/node-core/light";
 import type { SentryContext } from "../../context.js";
-import { listLogs, listTraceLogs } from "../../lib/api-client.js";
-import { validateLimit } from "../../lib/arg-parsing.js";
-import { AuthError, stringifyUnknown } from "../../lib/errors.js";
+import {
+  type LogSortDirection,
+  listLogs,
+  listTraceLogs,
+} from "../../lib/api-client.js";
+import { parseLogSort, validateLimit } from "../../lib/arg-parsing.js";
+import {
+  AuthError,
+  stringifyUnknown,
+  ValidationError,
+} from "../../lib/errors.js";
 import {
   buildLogRowCells,
   createLogStreamingTable,
@@ -47,6 +55,7 @@ type ListFlags = {
   readonly query?: string;
   readonly follow?: number;
   readonly period?: string;
+  readonly sort: LogSortDirection;
   readonly json: boolean;
   readonly fresh: boolean;
   readonly fields?: string[];
@@ -155,8 +164,10 @@ function parseLogListArgs(
   return parseDualModeArgs(args, TRACE_USAGE_HINT);
 }
 
-/** Default time period for project-scoped log queries */
-const DEFAULT_PROJECT_PERIOD = "90d";
+/** Default time period for project-scoped log queries.
+ * Log retention is 30 days (https://docs.sentry.io/security-legal-pii/security/data-retention-periods/).
+ * Periods >30d hit a degraded API path that returns stale/incomplete data. */
+const DEFAULT_PROJECT_PERIOD = "30d";
 
 /**
  * Execute a single fetch of logs (non-streaming mode).
@@ -174,21 +185,19 @@ async function executeSingleFetch(
     query: flags.query,
     limit: flags.limit,
     statsPeriod: period,
+    sort: flags.sort,
   });
 
   if (logs.length === 0) {
     return { result: { logs: [], hasMore: false }, hint: "No logs found." };
   }
 
-  // Reverse for chronological order (API returns newest first, tail shows oldest first)
-  const chronological = [...logs].reverse();
-
   const hasMore = logs.length >= flags.limit;
   const countText = `Showing ${logs.length} log${logs.length === 1 ? "" : "s"}.`;
   const tip = hasMore ? " Use --limit to show more, or -f to follow." : "";
 
   return {
-    result: { logs: chronological, hasMore },
+    result: { logs, hasMore },
     hint: `${countText}${tip}`,
   };
 }
@@ -434,6 +443,7 @@ async function executeTraceSingleFetch(
     query: flags.query,
     limit: flags.limit,
     statsPeriod: period,
+    sort: flags.sort,
   });
 
   if (logs.length === 0) {
@@ -445,14 +455,12 @@ async function executeTraceSingleFetch(
     };
   }
 
-  const chronological = [...logs].reverse();
-
   const hasMore = logs.length >= flags.limit;
   const countText = `Showing ${logs.length} log${logs.length === 1 ? "" : "s"} for trace ${traceId}.`;
   const tip = hasMore ? " Use --limit to show more." : "";
 
   return {
-    result: { logs: chronological, traceId, hasMore },
+    result: { logs, traceId, hasMore },
     hint: `${countText}${tip}`,
   };
 }
@@ -635,18 +643,32 @@ export const listCommand = buildListCommand(
           kind: "parsed",
           parse: String,
           brief:
-            'Time period (e.g., "90d", "14d", "24h"). Default: 90d (project mode), 14d (trace mode)',
+            'Time period (e.g., "30d", "14d", "24h"). Default: 30d (project mode), 14d (trace mode)',
           optional: true,
         },
+        sort: {
+          kind: "parsed",
+          parse: parseLogSort,
+          brief: 'Sort order: "newest" (default) or "oldest"',
+          default: "newest",
+        },
       },
       aliases: {
         n: "limit",
         q: "query",
         f: "follow",
         t: "period",
+        s: "sort",
       },
     },
     async *func(this: SentryContext, flags: ListFlags, ...args: string[]) {
+      if (flags.follow && flags.sort === "oldest") {
+        throw new ValidationError(
+          '--sort "oldest" cannot be used with --follow. Follow mode streams new logs as they arrive.',
+          "sort"
+        );
+      }
+
       const { cwd } = this;
 
       const parsed = parseLogListArgs(args);

src/commands/trace/logs.ts

@@ -5,8 +5,8 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { listTraceLogs } from "../../lib/api-client.js";
-import { validateLimit } from "../../lib/arg-parsing.js";
+import { type LogSortDirection, listTraceLogs } from "../../lib/api-client.js";
+import { parseLogSort, validateLimit } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { filterFields } from "../../lib/formatters/json.js";
@@ -31,6 +31,7 @@ type LogsFlags = {
   readonly period: string;
   readonly limit: number;
   readonly query?: string;
+  readonly sort: LogSortDirection;
   readonly fresh: boolean;
   readonly fields?: string[];
 };
@@ -147,6 +148,12 @@ export const logsCommand = buildCommand({
         brief: "Additional filter query (Sentry search syntax)",
         optional: true,
       },
+      sort: {
+        kind: "parsed",
+        parse: parseLogSort,
+        brief: 'Sort order: "newest" (default) or "oldest"',
+        default: "newest",
+      },
       fresh: FRESH_FLAG,
     },
     aliases: {
@@ -155,6 +162,7 @@ export const logsCommand = buildCommand({
       t: "period",
       n: "limit",
       q: "query",
+      s: "sort",
     },
   },
   async *func(this: SentryContext, flags: LogsFlags, ...args: string[]) {
@@ -180,19 +188,18 @@ export const logsCommand = buildCommand({
           statsPeriod: flags.period,
           limit: flags.limit,
           query: flags.query,
+          sort: flags.sort,
         })
     );
 
-    // Reverse to chronological order (API returns newest-first)
-    const chronological = [...logs].reverse();
-    const hasMore = chronological.length >= flags.limit;
+    const hasMore = logs.length >= flags.limit;
 
     const emptyMessage =
       `No logs found for trace ${traceId} in the last ${flags.period}.\n\n` +
       `Try a longer period: sentry trace logs --period 30d ${traceId}`;
 
     return yield new CommandOutput({
-      logs: chronological,
+      logs,
       traceId,
       hasMore,
       emptyMessage,

src/lib/api-client.ts

@@ -60,6 +60,7 @@ export {
 } from "./api/issues.js";
 export {
   getLogs,
+  type LogSortDirection,
   listLogs,
   listTraceLogs,
 } from "./api/logs.js";

src/lib/api/logs.ts

@@ -26,6 +26,14 @@ import {
   unwrapResult,
 } from "./infrastructure.js";
 
+/** Sort direction for log queries: newest-first or oldest-first. */
+export type LogSortDirection = "newest" | "oldest";
+
+/** Map CLI sort direction to Sentry API sort parameter. */
+function toApiSort(sort: LogSortDirection | undefined): string {
+  return sort === "oldest" ? "timestamp" : "-timestamp";
+}
+
 /** Fields to request from the logs API */
 const LOG_FIELDS = [
   "sentry.item_id",
@@ -41,8 +49,14 @@ type ListLogsOptions = {
   query?: string;
   /** Maximum number of log entries to return */
   limit?: number;
-  /** Time period for logs (e.g., "90d", "10m") */
+  /**
+   * Time period for logs (e.g., "30d", "14d", "10m").
+   * Defaults to "30d" — the maximum log retention period.
+   * Periods >30d hit a degraded API path returning stale/incomplete data.
+   */
   statsPeriod?: string;
+  /** Sort direction: "newest" (default) or "oldest" */
+  sort?: LogSortDirection;
   /** Only return logs after this timestamp_precise value (for streaming) */
   afterTimestamp?: number;
 };
@@ -83,8 +97,8 @@ export async function listLogs(
       project: isNumericProject ? [Number(projectSlug)] : undefined,
       query: fullQuery || undefined,
       per_page: options.limit || API_MAX_PER_PAGE,
-      statsPeriod: options.statsPeriod ?? "7d",
-      sort: "-timestamp",
+      statsPeriod: options.statsPeriod ?? "30d",
+      sort: toApiSort(options.sort),
     },
   });
 
@@ -193,6 +207,8 @@ type ListTraceLogsOptions = {
    * logs exist for the trace. Defaults to "14d".
    */
   statsPeriod?: string;
+  /** Sort direction: "newest" (default) or "oldest" */
+  sort?: LogSortDirection;
 };
 
 /**
@@ -208,8 +224,8 @@ type ListTraceLogsOptions = {
  *
  * @param orgSlug - Organization slug
  * @param traceId - The 32-character hex trace ID
- * @param options - Optional query/limit/statsPeriod overrides
- * @returns Array of trace log entries, ordered newest-first
+ * @param options - Optional query/limit/statsPeriod/sort overrides
+ * @returns Array of trace log entries
  */
 export async function listTraceLogs(
   orgSlug: string,
@@ -227,7 +243,7 @@ export async function listTraceLogs(
         statsPeriod: options.statsPeriod ?? "14d",
         per_page: options.limit ?? API_MAX_PER_PAGE,
         query: options.query,
-        sort: "-timestamp",
+        sort: toApiSort(options.sort),
       },
       schema: TraceLogsResponseSchema,
     }

src/lib/arg-parsing.ts

@@ -6,6 +6,7 @@
  * project list) and single-item commands (issue view, explain, plan).
  */
 
+import type { LogSortDirection } from "./api/logs.js";
 import { ContextError, ValidationError } from "./errors.js";
 import { validateResourceId } from "./input-validation.js";
 import { logger } from "./logger.js";
@@ -261,6 +262,28 @@ export function validateLimit(value: string, min = 1, max = 1000): number {
   return num;
 }
 
+// ---------------------------------------------------------------------------
+// Log sort direction parsing (shared by log list, trace logs)
+// ---------------------------------------------------------------------------
+
+const VALID_LOG_SORT_DIRECTIONS: readonly LogSortDirection[] = [
+  "newest",
+  "oldest",
+];
+
+/**
+ * Parse --sort flag value for log commands.
+ * @throws Error if value is not "newest" or "oldest"
+ */
+export function parseLogSort(value: string): LogSortDirection {
+  if (!VALID_LOG_SORT_DIRECTIONS.includes(value as LogSortDirection)) {
+    throw new Error(
+      `Invalid sort value. Must be one of: ${VALID_LOG_SORT_DIRECTIONS.join(", ")}`
+    );
+  }
+  return value as LogSortDirection;
+}
+
 /** Default span depth when no value is provided */
 const DEFAULT_SPAN_DEPTH = 3;