Planetscale Query Insights And Tags Agent Skill

Query Insights and tags

Purpose

Use PlanetScale Insights to understand query behavior, then recommend SQLCommenter-compatible tags that make future diagnosis and Traffic Control possible. Do not change database settings or repository code without approval.

What to inspect

Query behavior

For the selected database and branch, inspect:

• Top queries by total time.
• Top queries by time per execution.
• Top queries by rows read.
• Top queries by execution count.
• For Postgres, top queries by CPU usage (sort=cpuTime or

sort=percentCpuTime on the Insights API).

• Queries with errors.
• Notable queries and active anomalies.
• Query patterns affected by recent deploys.
• Query patterns attached to schema recommendations.
• For sharded Vitess databases, vindex usage for each query pattern: the

percentage of traffic using relevant vindexes and the vindex-usage trend

over time. The API exposes per-pattern index_usages and

routing_index_usages; get the trend from the dashboard Vindexes tab or

by comparing API windows. Treat missing or declining relevant-vindex

usage as an indexing or routing investigation input, not as proof that a

new index is required.

Insights API surface

Query Insights is public API: read-only GET endpoints under

organizations/{org}/databases/{db}/branches/{branch}, authorized by a

service token or OAuth token with read_databases/read_database.

• /insights — aggregated statistics per query pattern over the requested

window. Set the window with from/to (ISO 8601) or period (for

example 1h, 24h); search SQL patterns with q; sort server-side with

sort and dir — sort keys include count, errorCount, rowsRead,

totalTime, cpuTime, ioTime, percentTime, percentCpuTime,

p50Latency, p99Latency, maxLatency, egressBytes, and the

trafficControlWarnings/trafficControlThrottled family. Filter with

tablet_type (primary, replica, rdonly) and type (SELECT,

INSERT, UPDATE, DELETE); trim responses with fields; paginate

with page/per_page.

• /insights/{fingerprint} — individual collected executions for a

pattern (timestamps, duration, rows, username, client address, error

message). Available regardless of raw query collection; raw collection

adds literal parameter values to these records.

/insights/{fingerprint}/summary returns the single-pattern aggregate;

/insights/queries/{id} fetches one execution.

• /insights/errors — error fingerprints with counts and messages (q

searches the error message; sort by count, lastRun, totalTime, or

timePerQuery). /insights/errors/{fingerprint} lists the failing

executions behind one error fingerprint.

• /insights/anomalies and /insights/anomalies/{id} — anomaly windows

with per-query correlation coefficients identifying which patterns moved

with the anomaly.

• /insights/tags — tag keys with observed values (values_limit,

literal_values_only, and fingerprint/keyspace filters);

/insights/tags/{tag} for a single key. /insights/tags/summaries

groups the full statistics schema by one or more tag keys via the tags

parameter — use it to attribute load to routes, jobs, or features

without client-side aggregation.

• /insights/{fingerprint}/traffic/budgets — the Traffic Control budgets

and rules that affect a fingerprint (Postgres).

Aggregates cover the requested window. Duration fields use names like

sum_total_duration_millis, with explicit share-of-window percent fields

(sum_total_duration_percent); both totals and percentages are reliable

for the window requested.

The response schema is shared across engines, but some fields are

engine-specific: CPU/IO durations and block-cache statistics

(sum_cpu_duration_millis, blocks_read, block_cache_hit_ratio, …) are

populated for Postgres; shard queries, keyspaces, tablet_type, and

routing-index (vindex) usage are populated for Vitess.

Tag coverage

For each expensive or anomalous query, determine:

• Is it tagged?
• Which service produced it?
• Which route, job, controller, or action produced it?
• Which deployment SHA produced it?
• Is the tag cardinality safe?
• Are tags consistent across frameworks and languages?
• Use the tags API to answer these questions: /insights/tags shows which

keys and values are present, and /insights/tags/summaries?tags=...

attributes load per tag value. In the Vitess dashboard, filter the query

table with tag:key:value and drill into query details to see tags on

individual executions. Built-in query metadata and SQLCommenter tags are

both valid attribution sources.

Raw query collection

Check whether raw query / complete query collection is enabled. On

Postgres the effective state is the pginsights.raw_queries cluster

parameter (per branch, dashboard Extensions tab, default false); the

database API object's insights_raw_queries field is a separate surface.

When the two differ, report the cluster parameter as the effective state

and do not describe the difference as an inconsistency. On Vitess there

is no cluster parameter; the database API's insights_raw_queries field

is the effective state.

Report it as a capability state, not a risk posture. Raw query collection

records literal parameter values per execution, which pattern-level Insights

data does not provide. It is the mechanism for isolating which specific

invocation of a pattern is pathological. Execution-level records are

retrievable from /insights/{fingerprint} with or without raw collection;

raw collection adds the literal parameter values to those records.

When it is disabled, the finding is a capability gap: identify the query

patterns in this assessment where pattern-level data is insufficient

(unexplained latency variance within a fingerprint, tenant- or

parameter-dependent behavior) and state that raw collection would resolve

them. State the operational property once, as fact: literal values become

visible to the observability pipeline. Where the customer's data-handling

requirements constrain this, scoped enablement (incident windows, defined

retention) and leaving collection disabled are both valid outcomes —

record the rationale rather than a default judgment in either direction.

Tags and raw collection are complementary instruments: tags attribute a

pattern to a code path; raw collection identifies the specific invocation.

Assessments should evaluate both.

SQLCommenter tag schema

Recommend this baseline tag set:

• application: stable app name.
• service: service or process name.
• environment: production, staging, development.
• route: normalized route template, for example /accounts/:id/orders, not /accounts/123/orders.
• controller: framework controller name where applicable.
• action: framework action name where applicable.
• job: background job class or worker name.
• queue: background queue.
• feature: bounded feature name for traffic classes like export, report, search, billing, checkout.
• release_sha: short git SHA or deploy identifier.
• source: app, worker, script, agent, mcp, bi, integration.
• tenant_tier: free, pro, enterprise, internal, only if bounded.

Do not recommend these tags by default:

• user_id
• request_id
• tenant_id
• email
• session_id
• raw URL
• unbounded GraphQL operation text
• access token
• secret

If the customer needs tenant-level isolation, recommend a bounded abstraction first, such as tenant tier, cell, shard, or customer class. Tenant ID is only acceptable with explicit approval after cardinality and privacy review.

Cardinality rules

Flag a tag as unsafe when:

• Values are unbounded.
• Values include IDs, UUIDs, emails, slugs, or raw paths.
• The same query pattern emits many unique tag combinations.
• The tag would make Insights or Traffic Control aggregation noisy.

Recommend normalizing at the application boundary.

Analysis output

For each top query pattern, produce:

• Fingerprint or normalized query.
• Current metrics.
• Current tags.
• Missing tags.
• Likely source in application code.
• Whether it is a schema recommendation candidate.
• Whether it is a Traffic Control candidate.
• Whether it is an application optimization candidate.

Recommendation classes

Add tags

Recommend SQLCommenter instrumentation when query attribution is weak.

Improve tag normalization

Recommend replacing high-cardinality tags with bounded values.

Add Traffic Control warning budget

For Postgres only, recommend warn mode budgets for expensive but important routes, jobs, analytics, exports, or third-party integrations.

Add schema recommendation workflow

For Vitess, recommend turning open schema recommendations into branch/deploy-request work. For Postgres, recommend turning them into reviewed migrations against a non-production branch.

Fix code path

Recommend a repository PR when the expensive query is caused by N+1, missing pagination, accidental eager load, unbounded export, broad search, or polling.

Safety rules

Do not:

• Enable raw query collection.
• Add tags to code.
• Change Traffic Control budgets.
• Apply schema recommendations.
• Run production EXPLAIN ANALYZE on expensive queries.

Without explicit approval.

Output

Return:

• Query risk table.
• Tag coverage table.
• Bad/high-cardinality tag table.
• Recommended tag schema for this application.
• Candidate Traffic Control slices.
• Candidate schema and code changes.
• Proposed changes requiring approval.

End with:

“No Insights, tag, repository, or Traffic Control changes have been applied.”