pydantic/skills· MIT 内容可用

logfire-query

Query and analyze Logfire telemetry data — traces, logs, spans, metrics, summaries, and SQL results. Use this skill when the user asks to "query logfire", "search traces", "find logs", "query data", "search spans", "look up errors in logfire", "get metrics from logfire", "analyze telemetry", "summarize errors", "find root cause", or add Logfire querying capabilities to code. Do not use this skill for direct Logfire UI, browser, live-view, Explore-page, or link-opening requests; use logfire-ui instead. If "show" or "view" wording is ambiguous, ask whether the user wants a UI view or query analysis.

安装

与 skills.sh 相同的 Command / Prompt 安装方式

name: logfire-query description: Query and analyze Logfire telemetry data — traces, logs, spans, metrics, summaries, and SQL results. Use this skill when the user asks to "query logfire", "search traces", "find logs", "query data", "search spans", "look up errors in logfire", "get metrics from logfire", "analyze telemetry", "summarize errors", "find root cause", or add Logfire querying capabilities to code. Do not use this skill for direct Logfire UI, browser, live-view, Explore-page, or link-opening requests; use logfire-ui instead. If "show" or "view" wording is ambiguous, ask whether the user wants a UI view or query analysis.

Query Logfire Data

When to Use This Skill

Invoke this skill when:

User wants to query traces, logs, spans, or metrics from Logfire
User wants to search for specific events, errors, or patterns in telemetry data
User wants to analyze OpenTelemetry data stored in Logfire
User wants to add programmatic query capabilities to their code
User asks to "query logfire", "search traces", "find logs", "get metrics", "count", "summarize", "compare", or "find root cause"

User-Facing Progress

Keep progress updates terse. Do not narrate route classification, local skill instructions, schema selection, or routine query setup. If an update is needed, use one short sentence focused on the action, such as "Querying recent Logfire errors."

Critical Routing: One Workflow Per Request

Before using any query tool, classify the request.

Query route: "analyze", "query", "count", "summarize", "compare", "find root cause", "find slowest", "look up errors", "get metrics", or "add query capabilities".
UI route: "open", "show in browser", "show in Codex", "show in Logfire", "live view", "open Explore", "open the UI", "give me a link", or GUI/browser presentation. Use logfire-ui; do not call query_run just to make a URL.
Ambiguous route: prompts like "show recent errors", "view logs", or "show spans" do not specify whether the user wants chat analysis or the Logfire UI. Ask the user to choose query analysis or UI view.
Combined route: if the user explicitly asks for both analysis and a link, query only for the requested analysis or to identify the requested item, then provide the relevant Logfire link. Do not add UI/browser work unless the user asked for it.

Only query before opening Logfire UI when the user asks to open a specific unknown item that must be found first, such as "find the slowest trace and open it" or "open the latest error trace".

Two Approaches

Aspect	MCP `query_run`	REST API `/v1/query`
Best for	Interactive analysis in Codex	Adding query code to a project
Auth	OAuth via MCP session	Bearer read token
Setup	Already configured via plugin	Need a read token
Formats	JSON rows	JSON, CSV, Apache Arrow
Default window	Last 30 min	Last 24 hours
Max range	14 days	14 days
Row limit	Must be in SQL	Default 500, max 10,000

Quick Schema Reference

`records` table (spans and logs)

Key columns for querying:

Column	Type	Description
`start_timestamp`	timestamp (UTC)	When span/log was created
`end_timestamp`	timestamp (UTC)	When span/log completed
`duration`	double (seconds)	Time between start and end; NULL for logs
`trace_id`	string (32 hex)	Unique trace identifier
`span_id`	string (16 hex)	Unique span identifier
`parent_span_id`	string (16 hex)	Parent span; NULL for root spans
`span_name`	string	Low-cardinality label for similar records
`message`	string	Human-readable description with arguments filled in
`level`	integer	Severity (supports `level = 'error'` string comparison)
`kind`	string	`span`, `log`, `span_event`, or `pending_span`
`service_name`	string	Service identifier
`is_exception`	boolean	Whether an exception was recorded
`exception_type`	string	Exception class name
`exception_message`	string	Exception message
`exception_stacktrace`	string	Full traceback
`attributes`	JSON	Structured data; query with `->>'key'`
`tags`	string[]	Grouping labels; query with `array_has(tags, 'x')`
`http_response_status_code`	integer	HTTP status code
`http_method`	string	HTTP method
`http_route`	string	HTTP route pattern
`otel_status_code`	string	Span status

`metrics` table

Column	Type	Description
`recorded_timestamp`	timestamp (UTC)	When metric was recorded
`metric_name`	string	Metric name
`metric_type`	string	Type (gauge, counter, histogram)
`unit`	string	Unit of measurement
`scalar_value`	double	Metric value
`service_name`	string	Service identifier
`attributes`	JSON	Metric dimensions

Full schema: references/schema.md

SQL Syntax

Logfire uses Apache DataFusion (Postgres-like). Key patterns:

-- Time filtering
WHERE start_timestamp > now() - interval '1 hour'

-- JSON attribute access
WHERE attributes->>'user_id' = '123'
SELECT attributes->>'http.url' as url FROM records

-- Nested JSON
attributes->'request'->>'method'

-- Array filtering
WHERE array_has(tags, 'production')

-- Level filtering (string comparison works)
WHERE level = 'error'

-- Case-insensitive matching
WHERE message ILIKE '%timeout%'

-- Time bucketing for aggregation
SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket,
       count(*) FROM records GROUP BY bucket ORDER BY bucket

MCP Approach (Interactive)

Call the query_run MCP tool:

query (required): SQL query string
project (optional): target project (default: user's current project)
min_timestamp / max_timestamp (optional): ISO timestamps for time window

Default window is last 30 min. Max range is 14 days. Always include LIMIT in SQL.

Common queries

-- Recent errors
SELECT start_timestamp, message, exception_type, exception_message
FROM records WHERE is_exception LIMIT 20

-- Slow spans
SELECT span_name, duration, start_timestamp
FROM records WHERE duration > 1.0 ORDER BY duration DESC LIMIT 20

-- Endpoint errors
SELECT start_timestamp, message, http_response_status_code
FROM records WHERE http_route = '/api/users' AND level = 'error' LIMIT 20

-- Full trace
SELECT span_name, message, duration, parent_span_id
FROM records WHERE trace_id = '<id>' ORDER BY start_timestamp

-- Error breakdown by service
SELECT service_name, count(*) as errors
FROM records WHERE is_exception GROUP BY service_name ORDER BY errors DESC

UI Links After Querying

If the user explicitly asks for both analysis and a Logfire link, finish the query analysis first, then use a Logfire link only for the known result:

For a known trace_id, use project_logfire_link(trace_id=trace_id, project=project, handoff=True) only when the user asked to open it immediately in the browser. Use project_logfire_link(trace_id=trace_id, project=project) for a durable or shareable URL.
For a project/filter view, use the logfire-ui routing rules.
Do not open the browser unless the user asked to open the link.

For a span-count prompt, provide SQL like this when the user wants an aggregate query or analysis:

SELECT
  time_bucket(interval '5 minutes', start_timestamp) AS bucket,
  count(*) AS span_count
FROM records
WHERE kind = 'span'
GROUP BY bucket
ORDER BY bucket
LIMIT 200

REST API Approach (Programmatic)

Endpoint: GET https://logfire-api.pydantic.dev/v1/query

Region variants:

US: https://logfire-us.pydantic.dev/v1/query
EU: https://logfire-eu.pydantic.dev/v1/query

Auth: Authorization: Bearer <read_token>

Parameters:

sql (required): SQL query
min_timestamp / max_timestamp (optional): ISO timestamps
limit (optional): row limit (default 500, max 10,000)

Response formats (via Accept header):

application/json — column-oriented JSON (default)
application/json with row_oriented=true param — row-oriented JSON
text/csv — CSV
application/vnd.apache.arrow.stream — Apache Arrow

Python clients: LogfireQueryClient (sync), AsyncLogfireQueryClient (async), logfire.db_api (PEP 249 / pandas).

Detailed examples: references/client-usage.md

Query Best Practices

Always LIMIT — start with 20, increase as needed
Use min_timestamp/max_timestamp params for simple time windows instead of SQL WHERE
Filter efficiently — service_name, span_name, trace_id, is_exception are fast filters
Use ->>'key' for JSON attribute access (returns text); use -> for nested JSON objects
Avoid SELECT * — select only the columns you need
Max 14-day range — queries cannot span more than 14 days

附带文件

references/client-usage.md

# Logfire Query Client Usage

Detailed examples for querying Logfire data programmatically.

## Creating a Read Token

### Via the Logfire UI

1. Go to [logfire.pydantic.dev](https://logfire.pydantic.dev)
2. Select your project
3. Open Settings (gear icon) → Read tokens tab
4. Click "Create read token"
5. Copy the token immediately — it won't be shown again

### Via the CLI

```bash
logfire read-tokens --project <organization>/<project> create
```

Store the token in an environment variable:

```bash
export LOGFIRE_READ_TOKEN=<your-read-token>
```

---

## Python `LogfireQueryClient` (Sync)

```python
from logfire.query_client import LogfireQueryClient

with LogfireQueryClient(read_token='<token>') as client:
    # Column-oriented JSON (default)
    result = client.query_json(sql='SELECT start_timestamp, message FROM records LIMIT 10')

    # Row-oriented JSON
    rows = client.query_json_rows(sql='SELECT start_timestamp, message FROM records LIMIT 10')

    # CSV
    csv_data = client.query_csv(sql='SELECT start_timestamp, message FROM records LIMIT 10')

    # Apache Arrow (requires pyarrow)
    arrow_table = client.query_arrow(sql='SELECT start_timestamp, message FROM records LIMIT 10')

    # Token info
    info = client.info()
```

With time filtering:

```python
with LogfireQueryClient(read_token='<token>') as client:
    result = client.query_json(
        sql='SELECT message, exception_type FROM records WHERE is_exception LIMIT 20',
        min_timestamp='2025-01-01T00:00:00Z',
        max_timestamp='2025-01-02T00:00:00Z',
    )
```

### Using environment variables

```python
import os
from logfire.query_client import LogfireQueryClient

# Reads from LOGFIRE_READ_TOKEN env var
with LogfireQueryClient(read_token=os.environ['LOGFIRE_READ_TOKEN']) as client:
    result = client.query_json(sql='SELECT message FROM records LIMIT 5')
```

---

## Python `AsyncLogfireQueryClient` (Async)

```python
from logfire.query_client import AsyncLogfireQueryClient

async with AsyncLogfireQueryClient(read_token='<token>') as client:
    result = await client.query_json(
        sql='SELECT start_timestamp, message FROM records LIMIT 10'
    )
    rows = await client.query_json_rows(
        sql='SELECT start_timestamp, message FROM records LIMIT 10'
    )
    csv_data = await client.query_csv(
        sql='SELECT start_timestamp, message FROM records LIMIT 10'
    )
    arrow_table = await client.query_arrow(
        sql='SELECT start_timestamp, message FROM records LIMIT 10'
    )
```

---

## Python DB API 2.0 (`logfire.db_api`)

PEP 249 compliant interface. Works with pandas, Jupyter, and marimo.

### Basic usage

```python
import logfire.db_api

with logfire.db_api.connect(read_token='<token>') as conn:
    cursor = conn.cursor()
    cursor.execute('SELECT start_timestamp, message FROM records LIMIT 10')
    rows = cursor.fetchall()
    for row in rows:
        print(row)
```

### Parameterized queries

Use `%(name)s` syntax (pyformat style) to safely pass parameters:

```python
cursor.execute(
    'SELECT message FROM records WHERE service_name = %(service)s LIMIT 10',
    {'service': 'my-app'}
)
```

### Pandas integration

```python
import pandas as pd
import logfire.db_api

with logfire.db_api.connect(read_token='<token>') as conn:
    df = pd.read_sql('SELECT start_timestamp, message, duration FROM records LIMIT 100', conn)
    print(df.describe())
```

### Configuration options

```python
import logfire.db_api
from datetime import timedelta, datetime, timezone

# Custom row limit
conn = logfire.db_api.connect(read_token='<token>', limit=1000)

# Query last 7 days (default is 24 hours)
conn = logfire.db_api.connect(read_token='<token>', min_timestamp=timedelta(days=7))

# Disable default timestamp filter
conn = logfire.db_api.connect(read_token='<token>', min_timestamp=None)

# Per-cursor overrides
cursor = conn.cursor()
cursor.limit = 500
cursor.min_timestamp = datetime.now(timezone.utc) - timedelta(days=14)
```

---

## Direct REST API

For any language or tool. Works with `curl`, `httpx`, `requests`, `fetch`, etc.

### Endpoint

```
GET https://logfire-api.pydantic.dev/v1/query
```

Region variants:
- US: `https://logfire-us.pydantic.dev/v1/query`
- EU: `https://logfire-eu.pydantic.dev/v1/query`

### Authentication

```
Authorization: Bearer <read_token>
```

### Query parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sql` | Yes | SQL query string |
| `min_timestamp` | No | ISO timestamp lower bound |
| `max_timestamp` | No | ISO timestamp upper bound |
| `limit` | No | Row limit (default 500, max 10,000) |
| `row_oriented` | No | Set `true` for row-oriented JSON |

### Response formats

Set the `Accept` header:
- `application/json` — column-oriented JSON (default)
- `text/csv` — CSV
- `application/vnd.apache.arrow.stream` — Apache Arrow

### curl examples

```bash
# Basic query (column-oriented JSON)
curl -G 'https://logfire-api.pydantic.dev/v1/query' \
  -H "Authorization: Bearer $LOGFIRE_READ_TOKEN" \
  --data-urlencode "sql=SELECT start_timestamp, message FROM records LIMIT 5"

# Row-oriented JSON
curl -G 'https://logfire-api.pydantic.dev/v1/query' \
  -H "Authorization: Bearer $LOGFIRE_READ_TOKEN" \
  --data-urlencode "sql=SELECT start_timestamp, message FROM records LIMIT 5" \
  --data-urlencode "row_oriented=true"

# CSV format
curl -G 'https://logfire-api.pydantic.dev/v1/query' \
  -H "Authorization: Bearer $LOGFIRE_READ_TOKEN" \
  -H "Accept: text/csv" \
  --data-urlencode "sql=SELECT start_timestamp, message FROM records LIMIT 5"

# With time range
curl -G 'https://logfire-api.pydantic.dev/v1/query' \
  -H "Authorization: Bearer $LOGFIRE_READ_TOKEN" \
  --data-urlencode "sql=SELECT message FROM records WHERE is_exception LIMIT 20" \
  --data-urlencode "min_timestamp=2025-01-01T00:00:00Z" \
  --data-urlencode "max_timestamp=2025-01-02T00:00:00Z"
```

### Python (httpx)

```python
import httpx

response = httpx.get(
    'https://logfire-api.pydantic.dev/v1/query',
    params={'sql': 'SELECT start_timestamp, message FROM records LIMIT 5'},
    headers={'Authorization': f'Bearer {read_token}'},
)
data = response.json()
```

### JavaScript (fetch)

```javascript
const params = new URLSearchParams({
  sql: 'SELECT start_timestamp, message FROM records LIMIT 5',
});

const response = await fetch(
  `https://logfire-api.pydantic.dev/v1/query?${params}`,
  { headers: { Authorization: `Bearer ${readToken}` } }
);
const data = await response.json();
```

references/schema.md

# Logfire Schema Reference

Logfire stores OpenTelemetry data in two tables: `records` (spans and logs) and `metrics`. SQL dialect is Apache DataFusion (Postgres-like).

## `records` Table

All spans, logs, and span events are stored in the `records` table.

### Timestamps

| Column | Type | Description |
|--------|------|-------------|
| `start_timestamp` | timestamp (UTC) | When span/log was created |
| `end_timestamp` | timestamp (UTC) | When span/log completed |
| `duration` | double (seconds) | Time between start and end; NULL for logs |

### Span Tree Structure

| Column | Type | Description |
|--------|------|-------------|
| `trace_id` | string (32 hex chars) | Unique identifier for the trace |
| `span_id` | string (16 hex chars) | Unique identifier within a trace |
| `parent_span_id` | string (16 hex chars) | Parent span ID; NULL for root spans |

### Core Fields

| Column | Type | Description |
|--------|------|-------------|
| `span_name` | string | Low-cardinality label for similar records |
| `message` | string | Human-readable description with arguments filled in |
| `level` | integer | Severity level; supports string comparison (`level = 'error'`) |
| `kind` | string | Record type: `span`, `log`, `span_event`, or `pending_span` |
| `attributes` | JSON | Arbitrary structured data |
| `tags` | string[] | Optional grouping labels |

### Exception Fields

| Column | Type | Description |
|--------|------|-------------|
| `is_exception` | boolean | Whether an exception was recorded |
| `exception_type` | string | Fully qualified exception class name |
| `exception_message` | string | Exception message text |
| `exception_stacktrace` | string | Full traceback |

### Service / Resource Fields

| Column | Type | Description |
|--------|------|-------------|
| `service_name` | string | Service type identifier |
| `service_version` | string | Service version |
| `service_instance_id` | string | Unique instance identifier |
| `service_namespace` | string | Service namespace |
| `deployment_environment` | string | Environment (production/staging/development) |
| `process_pid` | integer | Process ID |
| `otel_resource_attributes` | JSON | Full OpenTelemetry resource metadata |

### HTTP / URL Fields

| Column | Type | Description |
|--------|------|-------------|
| `http_response_status_code` | integer | HTTP response status code |
| `http_method` | string | HTTP method (GET, POST, etc.) |
| `http_route` | string | HTTP route pattern |
| `url_full` | string | Complete URL |
| `url_path` | string | URL path component |
| `url_query` | string | URL query string |

### OpenTelemetry Fields

| Column | Type | Description |
|--------|------|-------------|
| `otel_status_code` | string | Span status (OK, ERROR, UNSET) |
| `otel_status_message` | string | Status description on error |
| `otel_events` | JSON array | Span events attached to the span |
| `otel_links` | JSON array | Span links to other traces |
| `otel_scope_name` | string | Instrumenting library name |
| `otel_scope_version` | string | Instrumenting library version |
| `otel_scope_attributes` | JSON | Additional scope metadata |

### Telemetry SDK Fields

| Column | Type | Description |
|--------|------|-------------|
| `telemetry_sdk_name` | string | SDK name |
| `telemetry_sdk_language` | string | SDK language |
| `telemetry_sdk_version` | string | SDK version |

### Other

| Column | Type | Description |
|--------|------|-------------|
| `log_body` | string/JSON | Body for OpenTelemetry logs (non-span records) |

---

## `metrics` Table

| Column | Type | Description |
|--------|------|-------------|
| `recorded_timestamp` | timestamp (UTC) | When metric was recorded |
| `metric_name` | string | Metric name |
| `metric_type` | string | Type (gauge, sum, histogram, exponential_histogram) |
| `unit` | string | Unit of measurement |
| `metric_description` | string | Metric description |
| `scalar_value` | double | Scalar metric value (gauge/sum) |
| `start_timestamp` | timestamp (UTC) | Start of aggregation window |
| `aggregation_temporality` | enum | Cumulative or delta |
| `is_monotonic` | boolean | Whether the metric is monotonic |
| `histogram_min` | double | Histogram minimum |
| `histogram_max` | double | Histogram maximum |
| `histogram_count` | integer | Histogram count |
| `histogram_sum` | double | Histogram sum |
| `histogram_bucket_counts` | integer[] | Histogram bucket counts |
| `histogram_explicit_bounds` | double[] | Histogram bucket boundaries |
| `exp_histogram_scale` | integer | Exponential histogram scale |
| `exp_histogram_zero_count` | integer | Exponential histogram zero count |
| `exp_histogram_zero_threshold` | double | Exponential histogram zero threshold |
| `exp_histogram_positive_bucket_counts` | integer[] | Positive bucket counts |
| `exp_histogram_positive_bucket_counts_offset` | integer | Positive bucket offset |
| `exp_histogram_negative_bucket_counts` | integer[] | Negative bucket counts |
| `exp_histogram_negative_bucket_counts_offset` | integer | Negative bucket offset |
| `attributes` | JSON | Metric dimensions/labels |
| `service_name` | string | Service identifier |
| `service_version` | string | Service version |
| `service_instance_id` | string | Unique instance identifier |
| `service_namespace` | string | Service namespace |
| `process_pid` | integer | Process ID |
| `otel_scope_name` | string | Instrumenting library name |
| `otel_scope_version` | string | Instrumenting library version |
| `otel_scope_attributes` | JSON | Additional scope metadata |

---

## JSON Attribute Access

The `attributes` column stores arbitrary structured data as JSON. Use `->>` to extract text values, `->` to extract nested objects.

```sql
-- Extract a text value
SELECT attributes->>'user_id' as user_id FROM records

-- Nested access
SELECT attributes->'request'->>'method' as method FROM records

-- Filter by attribute
WHERE attributes->>'http.url' LIKE '%/api/%'

-- Cast extracted values
WHERE CAST(attributes->>'response.status' AS INTEGER) >= 500
```

## Common Filter Patterns

```sql
-- Recent errors with details
SELECT start_timestamp, service_name, exception_type, exception_message
FROM records
WHERE is_exception AND start_timestamp > now() - interval '1 hour'
ORDER BY start_timestamp DESC LIMIT 20

-- HTTP errors by route
SELECT http_route, http_response_status_code, count(*) as count
FROM records
WHERE http_response_status_code >= 400
GROUP BY http_route, http_response_status_code
ORDER BY count DESC LIMIT 20

-- Slow endpoints (p95 duration)
SELECT http_route,
       approx_percentile_cont(duration, 0.95) as p95_duration,
       count(*) as count
FROM records
WHERE kind = 'span' AND http_route IS NOT NULL
GROUP BY http_route ORDER BY p95_duration DESC LIMIT 20

-- Trace waterfall
SELECT span_name, message, duration, start_timestamp, span_id, parent_span_id
FROM records WHERE trace_id = '<trace_id>'
ORDER BY start_timestamp

-- Tag filtering
SELECT * FROM records WHERE array_has(tags, 'critical') LIMIT 20

-- Time-bucketed error rate
SELECT time_bucket(interval '5 minutes', start_timestamp) as bucket,
       count(*) FILTER (WHERE is_exception) as errors,
       count(*) as total
FROM records
GROUP BY bucket ORDER BY bucket DESC LIMIT 50

-- Metrics query
SELECT recorded_timestamp, scalar_value, attributes
FROM metrics
WHERE metric_name = 'http.server.request.duration'
ORDER BY recorded_timestamp DESC LIMIT 20
```