| name | tusk-drift-query |
| description | Search, analyze, and debug recorded API traffic using the Tusk Drift CLI query commands. Use when users want to explore their API endpoints, investigate errors or latency, trace requests, or understand traffic patterns. |
| allowed-tools | Bash(tusk drift query:*) |
Search and analyze API traffic span recordings from Tusk Drift using CLI commands.
These commands help you query, analyze, and debug API traffic including HTTP requests/responses, database queries, gRPC calls, and more — latency metrics, error rates, and distributed traces across services.
All commands output JSON to stdout. All accept --service-id to override the default from .tusk/config.yaml.
Service discovery
Before running any query commands, run tusk drift query services to find available services.
- 0 services: The user hasn't set up Tusk Drift cloud yet. Tell them to run
tusk drift setup in the service of their choosing.
- 1 service: Use that service's
id as --service-id on all subsequent commands. No need to ask the user.
- Multiple services: STOP and ask the user which service they want to query before running any other commands. Present the list with names and repo info. Use their choice as
--service-id on all subsequent commands.
If tusk drift query services fails with an auth error, tell the user to run tusk auth login or set TUSK_API_KEY.
Workflow tips
- Start with
tusk drift query distinct to discover available endpoints
- Use
tusk drift query spans to find specific API calls
- Use
tusk drift query trace to debug a request's full call chain
Root cause analysis workflow
If the user is investigating performance issues or errors:
- Use
spans or aggregate to identify the problematic endpoint/span
- Use
trace to see the full call chain and identify which child span is the bottleneck
- Look at the span's metadata (inputValue/outputValue) to understand the request context
- Navigate to the relevant source code using the span name (usually maps to route handlers or functions)
- Analyze the code path to understand the root cause
Commands
tusk drift query distinct
List unique values for a field, ordered by frequency.
Use this to:
- Discover available endpoints:
--field name
- See all instrumentation packages in use:
--field packageName
- Find unique environments:
--field environment
- Explore JSONB values like status codes:
--field "outputValue.statusCode"
This helps you understand what values exist before building specific queries.
Flags:
--field (required) — Field to get distinct values for. Can be a column name or JSONB path (e.g., name, packageName, outputValue.statusCode)--limit (default 50) — Max distinct values to return (1-100)--where — Optional filter conditions as JSON (SpanWhereClause)--jsonb-filters — Optional JSONB filters as JSON array
tusk drift query spans
Search and filter API traffic span recordings.
Use this to:
- Find specific API calls by endpoint name, HTTP method, or status code
- Search for errors or slow requests
- Get recent traffic for a specific endpoint
- Debug specific API calls
Examples:
- Find failed requests:
--where '{"name":{"contains":"/api/users"}}' --jsonb-filters '[{"column":"outputValue","jsonPath":"$.statusCode","gte":400,"castAs":"int"}]'
- Find slow requests:
--min-duration 1000
- Recent traffic for endpoint:
--name "/api/orders" --limit 10 --order-by timestamp:DESC
Convenience flags:
--name — Filter by span/endpoint name (exact match)--package-name — Filter by instrumentation package (http, pg, fetch, grpc, etc.)--trace-id — Filter by trace ID--environment — Filter by environment--min-duration — Minimum duration in milliseconds--root-spans-only — Only return root spans--limit (default 20) — Max results (1-100)--offset (default 0) — Pagination offset--include-payloads (default false) — Include full inputValue/outputValue (can be verbose)--max-payload-length (default 500) — Truncate payload strings to this length--order-by — Sort results, format field:direction (e.g., timestamp:DESC, duration:ASC). Fields: timestamp, duration, name
Advanced flags (JSON strings, override convenience flags):
--where — Full SpanWhereClause as JSON. Supports field filters (name, packageName, instrumentationName, environment, traceId, spanId, duration, isRootSpan) with operators (eq, neq, in, contains, startsWith, endsWith, gt, gte, lt, lte). Supports AND/OR arrays for combining conditions.--jsonb-filters — Array of JSONB filters as JSON. Each filter has: column (inputValue, outputValue, metadata, status), jsonPath (starting with $, e.g., $.statusCode), comparison operators (eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith, isNull, in), and optional castAs (text, int, float, boolean).
tusk drift query trace <trace-id>
Get all spans in a distributed trace as a hierarchical tree.
Use this to:
- Debug a specific request end-to-end
- See the full call chain from HTTP request to database queries
- Understand timing and dependencies between spans
- Identify bottlenecks in a request
First use spans to find spans, then use the traceId from the results to get the full trace.
Flags:
--include-payloads (default false) — Include inputValue/outputValue--max-payload-length (default 500) — Truncate payload strings to this length
tusk drift query aggregate
Calculate aggregated metrics and statistics across spans.
Use this to:
- Get latency percentiles for endpoints (p50, p95, p99)
- Calculate error rates by endpoint
- Get request counts over time
- Compare performance across environments
Examples:
- Endpoint latency:
--group-by name --metrics count,avgDuration,p95Duration
- Error rates:
--group-by name --metrics count,errorCount,errorRate
- Hourly trends:
--time-bucket hour --metrics count,errorRate
Flags:
--metrics (required) — Metrics to calculate, comma-separated. Values: count, errorCount, errorRate, avgDuration, minDuration, maxDuration, p50Duration, p95Duration, p99Duration--group-by — Fields to group by, comma-separated. Values: name, packageName, instrumentationName, environment, statusCode--time-bucket — Time bucket for time-series data: hour, day, week--order-by — Order by metric, format metric:direction (e.g., count:DESC)--limit (default 20) — Max results (1-100)--where — Filter conditions as JSON (SpanWhereClause)
tusk drift query schema
Get schema and structure information for span recordings.
Use this to:
- Understand what fields are available for a specific instrumentation type
- See example payloads for HTTP requests, database queries, etc.
- Learn what to filter on before querying spans
Common package names:
- http: Incoming HTTP requests (has statusCode, method, url, headers)
- fetch: Outgoing HTTP calls
- pg: PostgreSQL queries (has db.statement, db.name)
- grpc: gRPC calls
- express: Express.js middleware spans
Flags:
--name — Span name to get schema for (e.g., /api/users)--package-name — Package name (e.g., http, pg, fetch)--instrumentation-name — Specific instrumentation name--show-example (default true) — Include an example span with real data--max-payload-length (default 500) — Truncate example payload strings
tusk drift query spans-by-ids
Fetch specific span recordings by their IDs.
Use this when you have span IDs from a previous query and need the full details including payloads. Useful for:
- Getting full details for spans found via
spans
- Examining specific requests in detail
- Comparing multiple specific spans
Flags:
--ids (required) — Span recording IDs, comma-separated (max 20)--include-payloads (default true) — Include full inputValue/outputValue--max-payload-length (default 500) — Truncate payload strings to this length
Error handling
