feat(search-events): Add tracemetrics dataset support (#902)

Add support for Sentry's current-generation span metrics in
search_events and list_events.

The previous attempt in #899 targeted the wrong dataset. The current
Sentry path uses dataset=tracemetrics on the events endpoint, raw metric
aggregate expressions such as
p95(value,http.request.duration,distribution,millisecond), and Metrics
page URLs under /explore/metrics/. This updates the MCP query builder,
formatting, mocks, tests, generated definitions, and docs to match that
behavior.

This also preserves raw aggregate sort expressions for tracemetrics so
grouped metric queries keep working instead of being rewritten into
Discover-style aliases.

---------

Co-authored-by: Codex <codex@openai.com>

Author: dcramer

docs/search-events-api-patterns.md

@@ -2,23 +2,23 @@
 
 ## Overview
 
-The `search_events` tool provides a unified interface for searching Sentry events across different datasets (errors, logs, spans). This document covers the API patterns, query structures, and best practices for both individual event queries and aggregate queries.
+The `search_events` tool provides a unified interface for searching Sentry events across different datasets (`errors`, `logs`, `spans`, and `metrics`). This document covers the API patterns, query structures, and best practices for both individual event queries and aggregate queries.
 
 ## API Architecture
 
-### Legacy Discover API vs Modern EAP API
+### Discover-Style API vs Modern EAP API
 
-Sentry uses two different API architectures depending on the dataset:
+Sentry uses two different query-building patterns depending on the dataset, even though they share the same `/events/` endpoint:
 
-1. **Legacy Discover API** (errors dataset)
-   - Uses the original Discover query format
-   - Simpler aggregate field handling
-   - Returns data in a different format
+1. **Discover-style events queries** (`errors`, `metrics`)
+   - Use repeated `field` parameters
+   - Use raw aggregate expressions in both `field` and `sort`
+   - Generate Discover-style URLs for `errors` and Metrics page URLs for `metrics`
 
-2. **Modern EAP (Event Analytics Platform) API** (spans, logs datasets)
-   - Uses structured aggregate parameters
-   - More sophisticated query capabilities
-   - Different URL generation patterns
+2. **Modern EAP (Event Analytics Platform) queries** (`spans`, `logs`)
+   - Use the same `/events/` endpoint with EAP-oriented field conventions
+   - Support richer span/log search semantics
+   - Generate Explore URLs for traces and logs
 
 ### API Endpoint
 
@@ -29,10 +29,11 @@ All queries use the same base endpoint:
 
 ### Dataset Mapping
 
-The tool handles dataset name mapping internally:
-- User specifies `errors` → API uses `errors` (Legacy Discover)
-- User specifies `spans` → API uses `spans` (EAP)
-- User specifies `logs` → API uses `ourlogs` (EAP) ⚠️ Note the transformation!
+The tool forwards the dataset name directly to the API:
+- User specifies `errors` → API uses `errors`
+- User specifies `spans` → API uses `spans`
+- User specifies `logs` → API uses `logs`
+- User specifies `metrics` → API uses `tracemetrics`
 
 ## Query Modes
 
@@ -56,6 +57,7 @@ https://us.sentry.io/api/0/organizations/sentry/events/?dataset=spans&field=id&f
 - **Spans**: `id`, `span.op`, `span.description`, `span.duration`, `transaction`, `timestamp`, `project`, `trace`
 - **Errors**: `issue`, `title`, `project`, `timestamp`, `level`, `message`, `error.type`, `culprit`
 - **Logs**: `timestamp`, `project`, `message`, `severity`, `trace`
+- **Tracemetrics**: `id`, `timestamp`, `project`, `trace`, `metric.name`, `metric.type`, `metric.unit`, `value`
 
 ### 2. Aggregate Queries (Statistics)
 
@@ -85,7 +87,7 @@ https://us.sentry.io/api/0/organizations/sentry/events/?dataset=spans&field=ai.m
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
-| `dataset` | Which dataset to query | `spans`, `errors`, `logs` (API uses `ourlogs`) |
+| `dataset` | Which dataset to query | `spans`, `errors`, `logs`, `metrics` |
 | `field` | Fields to return (repeated for each field) | `field=span.op&field=count()` |
 | `query` | Sentry query syntax filter | `has:db.statement AND span.duration:>1000` |
 | `sort` | Sort order (prefix with `-` for descending) | `-timestamp`, `-count()` |
@@ -112,7 +114,13 @@ https://us.sentry.io/api/0/organizations/sentry/events/?dataset=spans&field=ai.m
 - Does NOT support timestamp filters in query (use `statsPeriod` instead)
 - Severity levels: fatal, error, warning, info, debug, trace
 - Common aggregate functions: `count()`, `epm()`
-- Uses `ourlogs` as the actual API dataset value (not `logs`)
+
+#### Metrics Dataset
+- Represents newer span metrics, including counters, gauges, and distributions
+- Uses the same `/events/` endpoint with `dataset=tracemetrics`
+- Attribute discovery uses `/trace-items/attributes/?itemType=tracemetrics`
+- Aggregate fields must encode the target metric directly: `fn(value,metric.name,metric.type,metric.unit)`
+- Sort fields for aggregate results must stay raw, for example `-p95(value,http.request.duration,distribution,millisecond)`
 
 ## Query Syntax
 
@@ -144,6 +152,12 @@ Instead of using `span.op` patterns, use `has:` queries for more flexible attrib
 - `max(field)` - Maximum value
 - `p50(field)`, `p75(field)`, `p90(field)`, `p95(field)`, `p99(field)` - Percentiles
 
+#### Tracemetrics Aggregate Functions
+- Use the metric-aware form `fn(value,metric.name,metric.type,metric.unit)`
+- Counter examples: `sum(value,http.server.request.count,counter,-)`, `per_minute(value,http.server.request.count,counter,-)`
+- Gauge examples: `avg(value,cpu.usage,gauge,percent)`, `max(value,cpu.usage,gauge,percent)`
+- Distribution examples: `p75(value,http.request.duration,distribution,millisecond)`, `p95(value,http.request.duration,distribution,millisecond)`
+
 #### Errors-Specific Functions
 - `count_if(field,equals,value)` - Conditional count
 - `last_seen()` - Most recent timestamp
@@ -183,6 +197,14 @@ Sort: -count()
 Dataset: logs
 ```
 
+### Request Duration Percentiles by Route (Trace Metrics Aggregate)
+```
+Query: metric.name:http.request.duration AND metric.type:distribution
+Fields: ["transaction", "p75(value,http.request.duration,distribution,millisecond)", "p95(value,http.request.duration,distribution,millisecond)", "count(value,http.request.duration,distribution,millisecond)"]
+Sort: -p95(value,http.request.duration,distribution,millisecond)
+Dataset: metrics
+```
+
 ### Tool Calls by Model (Aggregate)
 ```
 Query: has:mcp.tool.name
@@ -205,7 +227,7 @@ Dataset: spans
 2. **Wrong sort field**: The field you sort by must be included in the fields array
 3. **Timestamp filters on logs**: Use `statsPeriod` parameter instead of query filters
 4. **Using project slugs**: API requires numeric project IDs, not slugs
-5. **Dataset naming**: Use `logs` in the tool, but API expects `ourlogs`
+5. **Tracemetrics sort mangling**: Do not rewrite `-p95(value,...)` into Discover-style aliases; the raw aggregate expression must be preserved
 
 ## Web UI URL Generation
 
@@ -214,10 +236,12 @@ The tool automatically generates shareable Sentry web UI URLs after making API c
 - **Errors dataset**: `/organizations/{org}/discover/results/`
 - **Spans dataset**: `/organizations/{org}/explore/traces/`
 - **Logs dataset**: `/organizations/{org}/explore/logs/`
+- **Tracemetrics dataset**: `/organizations/{org}/explore/metrics/`
 
 Note: The web UI URLs use different parameter formats than the API:
 - Legacy Discover uses simple field parameters
-- Modern Explore uses `aggregateField` with JSON-encoded values
+- Modern Explore uses dataset-specific parameter formats
+- The Metrics page uses one or more JSON-encoded `metric=` parameters
 - The tool handles this transformation automatically in `buildDiscoverUrl()` and `buildEapUrl()`
 
 ### Web URL Generation Parameters
@@ -515,4 +539,4 @@ This occurs when sorting by a field not included in the field list. Ensure your
 ### API Errors
 - 400: Invalid query syntax or parameters (often due to field mismatch in aggregates)
 - 404: Project or organization not found
-- 500: Internal error (check Sentry status)
+- 500: Internal error (check Sentry status)

docs/specs/search-events.md

@@ -16,7 +16,7 @@ A unified search tool that accepts natural language queries and translates them
 interface SearchEventsParams {
   organizationSlug: string;      // Required
   naturalLanguageQuery: string;  // Natural language search description
-  dataset?: "spans" | "errors" | "logs"; // Dataset to search (default: "errors")
+  dataset?: "spans" | "errors" | "logs" | "metrics"; // Dataset to search (default: "errors")
   projectSlug?: string;          // Optional - limit to specific project
   regionUrl?: string;           
   limit?: number;                // Default: 10, Max: 100
@@ -47,13 +47,20 @@ search_events({
   naturalLanguageQuery: "warning logs about memory usage",
   dataset: "logs"
 })
+
+// Find request duration metrics
+search_events({
+  organizationSlug: "my-org",
+  naturalLanguageQuery: "p95 request duration by transaction this week",
+  dataset: "metrics"
+})
 ```
 
 ## Architecture
 
 1. **Tool receives** natural language query and dataset selection
 2. **Fetches searchable attributes** based on dataset:
-   - For `spans`/`logs`: Uses `/organizations/{org}/trace-items/attributes/` endpoint with parallel calls for string and number attribute types
+   - For `spans`/`logs`/`metrics`: Uses `/organizations/{org}/trace-items/attributes/` endpoint with parallel calls for string and number attribute types
    - For `errors`: Uses `/organizations/{org}/tags/` endpoint (legacy, will migrate when new API supports errors)
 3. **OpenAI GPT-5 translates** natural language to Sentry query syntax using:
    - Comprehensive system prompt with Sentry query syntax rules
@@ -63,9 +70,9 @@ search_events({
    - Translated query string
    - Dataset-specific field selection
    - Numeric project ID (converted from slug if provided)
-   - Proper dataset mapping (logs → ourlogs)
+   - Public dataset normalization (`metrics` maps to the current API dataset `tracemetrics`)
 5. **Returns** formatted results with:
-   - Dataset-specific rendering (console format for logs, cards for errors, timeline for spans)
+   - Dataset-specific rendering (console format for logs, cards for errors, timeline for spans, and table/sample formatting for metrics)
    - Prominent rendering directives for AI agents
    - Shareable Sentry Explorer URL
 
@@ -85,13 +92,16 @@ The AI produces different query patterns based on the selected dataset:
 - **Spans dataset**: Focus on `span.op`, `span.description`, `span.duration`, `transaction`, supports timestamp filters
 - **Errors dataset**: Focus on `message`, `level`, `error.type`, `error.handled`, supports timestamp filters  
 - **Logs dataset**: Focus on `message`, `severity`, `severity_number`, **NO timestamp filters** (uses statsPeriod instead)
+- **Tracemetrics dataset**: Focus on `metric.name`, `metric.type`, `metric.unit`, `value`, and metric-aware aggregates like `p95(value,http.request.duration,distribution,millisecond)`
 
 ### Key Technical Constraints
 
 - **Logs timestamp handling**: Logs don't support query-based timestamp filters like `timestamp:-1h`. Instead, use `statsPeriod=24h` parameter
 - **Project ID mapping**: API requires numeric project IDs, not slugs. Tool automatically converts project slugs to IDs
-- **Parallel attribute fetching**: For spans/logs, fetches both string and number attribute types in parallel for better performance
-- **itemType specification**: Must use "logs" (plural) not "log" for the trace-items attributes API
+- **Parallel attribute fetching**: For spans/logs/metrics, fetches both string and number attribute types in parallel for better performance
+- **itemType specification**: Must use `logs` and `tracemetrics` exactly for the trace-items attributes API
+- **Tracemetrics sort handling**: Aggregate sort expressions like `-p95(value,...)` must be sent to the API unchanged
+- **Tracemetrics URL generation**: Explorer links must point at `/explore/metrics/` with JSON-encoded `metric=` parameters, not the traces or logs Explore pages
 
 ### Tool Removal
 
@@ -124,16 +134,17 @@ search_events({
 ### Completed Features
 
 1. **Custom attributes API integration**: 
-   - ✅ `/organizations/{org}/trace-items/attributes/` for spans/logs with parallel string/number fetching
+   - ✅ `/organizations/{org}/trace-items/attributes/` for spans/logs/metrics with parallel string/number fetching
    - ✅ `/organizations/{org}/tags/` for errors (legacy API)
 
 2. **Dataset mapping**:
-   - ✅ User specifies `logs` → API uses `ourlogs`
    - ✅ User specifies `errors` → API uses `errors`
    - ✅ User specifies `spans` → API uses `spans`
+   - ✅ User specifies `logs` → API uses `logs`
+   - ✅ User specifies `metrics` → API uses `tracemetrics`
 
 3. **URL Generation**:
-   - ✅ Uses appropriate explore path based on dataset (`/explore/traces/`, `/explore/logs/`)
+   - ✅ Uses appropriate explore path based on dataset (`/discover/results/`, `/explore/traces/`, `/explore/logs/`, `/explore/metrics/`)
    - ✅ Query and project parameters properly encoded with numeric project IDs
 
 4. **Error Handling**:
@@ -146,14 +157,15 @@ search_events({
    - ✅ Console format for logs with severity emojis
    - ✅ Alert cards for errors with color-coded levels
    - ✅ Performance timeline for spans with duration bars
+   - ✅ Aggregate-table and sample formatting for metrics
 
 ## Success Criteria - All Complete ✅
 
 - ✅ **Accurate translation of common query patterns** - GPT-5 with comprehensive system prompts
 - ✅ **Proper handling of org-specific custom attributes** - Parallel fetching and integration
 - ✅ **Seamless migration from old tools** - find_errors, find_transactions removed from exports
 - ✅ **Maintains performance** - Parallel API calls, efficient caching, translation overhead minimal
-- ✅ **Supports multiple datasets** - spans, errors, logs with dataset-specific handling
+- ✅ **Supports multiple datasets** - spans, errors, logs, and metrics with dataset-specific handling
 - ✅ **Generates shareable Sentry Explorer URLs** - Proper encoding with numeric project IDs
 - ✅ **Clear output indicating URL should be shared** - Prominent sharing instructions
 - ✅ **Comprehensive test coverage** - Unit tests, integration tests, and AI evaluations
@@ -163,4 +175,4 @@ search_events({
 
 - **Runtime**: OpenAI API key required (`OPENAI_API_KEY` environment variable)
 - **Build**: @ai-sdk/openai, ai packages added to dependencies
-- **Testing**: Comprehensive mocks for OpenAI and Sentry APIs
+- **Testing**: Comprehensive mocks for OpenAI and Sentry APIs