# Tempo MCP Server

An advanced Model Context Protocol (MCP) server for querying Grafana Tempo traces and spans with comprehensive filtering capabilities.

## Features

- **Flexible Trace Search**: Query traces using TraceQL or legacy tags
- **Span Filtering**: Filter spans by service name, duration, attributes, errors
- **Detailed Span Analysis**: Get complete span details with calculated durations
- **Span Statistics**: Aggregate statistics grouped by service/operation/status
- **Tag-based Queries**: Easy filtering by custom tags
- **Time Range Support**: Query by absolute or relative time ranges
- **Duration Filtering**: Filter by min/max duration at trace and span level

## Installation

```bash
cd ~/tempo-mcp-server
npm install
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
# Required
TEMPO_URL=http://localhost:3200

# Optional
TEMPO_USERNAME=admin
TEMPO_PASSWORD=secret
TEMPO_TOKEN=bearer_token_here
TEMPO_TIMEOUT=30000
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tempo-mcp": {
      "command": "node",
      "args": ["[YOUR-PROJECT-PATH]/dist/index.js"],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      }
    }
  }
}
```

## Available Tools

### 1. `tempo_search_traces`
Search traces with flexible filtering options.

**Parameters:**
- `query` (string): TraceQL query (e.g., `{.service.name="app-demo"}`)
- `tags` (string): Legacy tags format (e.g., `service.name=app-demo`)
- `minDuration` (string): Minimum duration (e.g., "100ms", "1s")
- `maxDuration` (string): Maximum duration (e.g., "5s")
- `limit` (number): Max traces to return (default: 20)
- `start` (string): Start time (RFC3339 or Unix timestamp)
- `end` (string): End time (RFC3339 or Unix timestamp)

**Example:**
```json
{
  "query": "{.service.name=\"app-demo\" && span.http.status_code >= 400}",
  "minDuration": "100ms",
  "limit": 50,
  "start": "2025-01-01T00:00:00Z"
}
```

### 2. `tempo_get_trace`
Get complete trace data by ID.

**Parameters:**
- `traceId` (string, required): The trace ID

### 3. `tempo_get_trace_spans`
Get all spans from a trace with optional filtering.

**Parameters:**
- `traceId` (string, required): The trace ID
- `serviceName` (string): Filter by service name
- `spanName` (string): Filter by span name (partial match)
- `minDuration` (number): Min span duration in ms
- `maxDuration` (number): Max span duration in ms
- `hasError` (boolean): Filter error spans only
- `attributes` (object): Filter by attributes (e.g., `{"http.method": "POST"}`)

**Example:**
```json
{
  "traceId": "1c4090cb9c90630901b167ad22c769aa",
  "serviceName": "app-demo",
  "minDuration": 100,
  "attributes": {
    "http.method": "POST"
  }
}
```

### 4. `tempo_search_spans`
Search traces and return matching spans across multiple traces.

**Parameters:**
- Trace search params: `query`, `tags`, `minDuration`, `maxDuration`, `limit`, `start`, `end`
- Span filter params: `serviceName`, `spanName`, `spanMinDuration`, `spanMaxDuration`, `spanHasError`, `spanAttributes`

**Example:**
```json
{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 10,
  "spanName": "POST",
  "spanMinDuration": 1000
}
```

### 5. `tempo_get_span_statistics`
Get aggregated span statistics.

**Parameters:**
- Search params: `query`, `tags`, `limit`, `start`, `end`
- `groupBy` (string): "service", "operation", or "status"

**Returns:**
- Count, avg/min/max durations, p50/p95/p99 percentiles per group

**Example:**
```json
{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 100,
  "groupBy": "service"
}
```

### 6. `tempo_query_by_tag`
Query traces by custom tag filters (convenience method).

**Parameters:**
- `tagFilters` (object, required): Tag key-value pairs
- `serviceName` (string): Service name filter
- `minDuration`, `maxDuration`, `limit`, `start`, `end`

**Example:**
```json
{
  "tagFilters": {
    "customtag": "tagValue",
    "environment": "production"
  },
  "limit": 20
}
```

## Usage Examples

### Example 1: Find all traces for a custom tag
```typescript
tempo_query_by_tag({
  tagFilters: { "customtag": "tagValue" },
  start: "2025-01-01T00:00:00Z",
  end: "2025-01-02T00:00:00Z"
})
```

### Example 2: Get detailed span breakdown
```typescript
tempo_get_trace_spans({
  traceId: "abc123...",
  serviceName: "app-demo"
})
```

### Example 3: Find slow database operations
```typescript
tempo_search_spans({
  query: "{.service.name=\"app-demo\"}",
  spanName: "SELECT",
  spanMinDuration: 1000  // > 1 second
})
```

### Example 4: Get service performance statistics
```typescript
tempo_get_span_statistics({
  query: "{.service.name=\"app-demo\"}",
  start: "2025-01-01T00:00:00Z",
  groupBy: "operation"
})
```

### Example 5: Find errors in a time range
```typescript
tempo_search_traces({
  query: "{span.http.status_code >= 400}",
  start: "1704067200",  // Unix timestamp
  limit: 50
})
```

## TraceQL Query Examples

```javascript
// By service name
{.service.name="app-demo"}

// By tag
{.customtag="tagValue"}

// HTTP status codes
{span.http.status_code >= 400}

// Duration
{duration > 1s}

```

## Time Format Examples

```javascript
// RFC3339
"2025-01-01T00:00:00Z"
"2025-01-01T00:00:00+05:30"

// Unix timestamp (seconds)
"1704067200"
1704067200

// Relative (in TraceQL)
"now-1h"
"now-24h"
```

## Development

```bash
# Watch mode
npm run watch

# Build
npm run build

# Run
npm start
```

## Troubleshooting

### Connection Issues
- Verify `TEMPO_URL` is correct
- Check Tempo is running: `curl http://localhost:3200/api/status`
- Check firewall/network connectivity

### Query Errors
- Validate TraceQL syntax - queries must be wrapped in `{}`
- Check time range is valid (RFC3339 or Unix seconds)
- Ensure trace IDs are correct format (hex string)
- Use `resource.service.name` instead of `.service.name` for service filtering
- For debugging, set `TEMPO_DEBUG=true` in environment

### Performance
- Reduce `limit` parameter for faster queries
- Narrow time ranges
- Use specific filters to reduce data volume