fix(tracing): support minute/second window shorthand in spans API

[jonmcwest]

Problem

The tracing (APM) spans API accepts a relative dateRange.date_from and parses it with PostHog's global relative-date grammar — where a bare lowercase m means months. For a product whose data is measured in hours and days, that's the wrong default: -30m (intended as "30 minutes ago") resolves to ~30 months ago, so a "last 30 minutes" query silently returns very old spans. Worse, an unrecognized window string fell back to "now" with no error, so a typo'd range returned stale data with no signal that anything was wrong.

This was hit in practice via the MCP query-apm-spans tool: a "slow queries in the last 30 minutes" request returned weeks-old rows.

Changes

• New products/tracing/backend/date_window.py with a tracing-scoped window normalizer:
  • Reads s/m/h/d/w intuitively, so -30m = 30 minutes (the one deliberate divergence from the global grammar, mapped onto its M-for-minutes token).
  • Passes ISO 8601 timestamps and the broader global relative grammar (-1dStart, -3q, -1y, month boundaries …) through unchanged, so nothing that worked before regresses.
  • Raises a ValidationError (HTTP 400) on genuinely unparseable input instead of failing open to "now".
• Applied at every dateRange parse site across the spans endpoints (query, sparkline, aggregation, breakdown, histogram, symbol stats, attribute names/values, service names).
• Updated the dateRange serializer help_text so the documented format flows into the generated MCP tool schemas.

How did you test this code?

I'm an agent (PostHog Slack app). I added products/tracing/backend/tests/test_date_window.py — parameterized unit tests over the pure normalizer covering: lowercase-m-means-minutes translation, case-insensitive units, ISO and global-grammar passthrough (locking in no-regression for -1dStart/-3q/-1mStart), empty-value handling, and the 400-on-garbage behavior that replaces the old silent fallback. These guard the exact regression this PR fixes (a window meaning the wrong unit, or bad input silently returning stale data).

I could not run the Python suite in this environment (no flox/venv), so I validated the regex/translation logic against all test cases in a standalone harness and py_compiled the changed modules. Ordering and lint should be confirmed by CI.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Authored by the PostHog Slack app from a Slack thread, after diagnosing the -30m-returns-stale-data behavior live via the query-apm-spans / apm-trace-get MCP tools. Skills invoked: /improving-drf-endpoints (serializer/help_text review) and /writing-tests (kept the tests at the pure-function level rather than standing up the API).

Key decision: lowercase m means months everywhere else in PostHog and is heavily tested, so the minutes interpretation is scoped to the tracing layer rather than changed globally. Months/years are meaningless for trace retention, so the divergence is safe here; the global grammar is still accepted for anyone relying on it.

---

Created with PostHog from a Slack thread

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(tracing): support minute/second wind..." | Re-trigger Greptile}