/k6-trend-analysis

name: k6-trend-analysis
description: >
  Analyze Grafana Cloud k6 test run trends over time. Detects slow metric drift
  (e.g., P95 latency creeping up while still passing thresholds), computes
  headroom to thresholds, flags anomalies, and recommends threshold tightening.
  Use when the user asks about test performance trends, wants to know if metrics
  are degrading, asks whether thresholds should be tightened, or wants a health
  check across recent runs for a specific test. Trigger on phrases like "how is
  my test trending", "is P95 getting worse", "check for performance regression",
  "should I tighten thresholds", "are my tests degrading", "show me trends for
  test X", "analyze my k6 test runs", or "is my test getting slower". Also
  trigger when a user asks to check all tests in a project -- run this skill
  once per test and synthesize.

k6 Trend Analysis

Analyze metric trends across multiple runs of a Grafana Cloud k6 test to catch degradation early -- before thresholds breach and alerts fire. A P95 at 380ms against a 500ms threshold is "green" today, but if it was 250ms a month ago, something is quietly degrading; this skill surfaces that drift and recommends action.

What this skill does NOT do

• **Deep-dive into a single run's failure**: load `k6-cloud-investigate-test`
• **Edit scripts or apply threshold changes**: load `k6-test-maintenance`
• **Create new test scripts**: use the appropriate test creation workflow
• **Query service-side metrics directly**: this skill hands off to

`debug-with-grafana` when observability correlation is needed

Dependencies

This skill delegates all GCk6 API mechanics to **`k6-manage`**. Read it before executing any API call -- it covers auth, path construction (the doubled `cloud/cloud/` prefix), pagination with `@nextLink`, the spill envelope, and metric query syntax. Do not duplicate that knowledge here.

Tools used: **`gcx`** (via k6-manage patterns).

---

Workflow

Follow these steps in order. Present findings at the end -- do not apply changes.

Step 1: Identify the test

The user provides one of:

• A GCk6 URL (extract the load test ID from the path)
• A test ID directly
• A test name (search via `gcx k6 tests list` or the v6 API)

Confirm the test exists by fetching its metadata. Record the `id`, `name`, `project_id`, and `created` timestamp. You will need the load test ID (not a run ID) for the multi-run metric endpoints.

Step 2: Determine the analysis window

Default to **last 30 days**. Adjust if:

• The user requests a specific window
• The test has very few runs (<5 in 30 days) -- widen the window and note this
• The test runs very frequently (hundreds of runs in 30 days) -- consider

sampling or narrowing. Ask the user if the volume is extreme (>200 runs)

State the window explicitly: "Analyzing runs from {start_date} to {end_date}."

Step 3: Fetch runs in the window

List all runs for the test using the v6 API with `$orderby=created desc` pagination (see k6-manage Section 3 for the `@nextLink` loop pattern). Filter to runs within the analysis window.

For each run, record:

• `id`, `created`, `ended`
• `result` (passed/failed/timed_out)
• `status` (created/queued/initializing/running/finished/aborted)
• `note` (if present -- users sometimes annotate runs)

Discard runs that did not reach `finished` status (aborted, timed_out, etc.) unless the user specifically asks about them -- incomplete runs produce unreliable metric aggregates.

Count the runs. If fewer than 3 usable runs exist, inform the user that trend analysis is not meaningful with this sample size and suggest widening the window or waiting for more runs.

Step 4: Fetch all metrics and their types

Before querying values, discover what metrics the test emits. Use the multi-run metric listing endpoint (k6-manage references/metrics.md Section 2):

GET /cloud/v5/load_tests/{loadTestId}/metrics(test_run_ids=[{id1},{id2},...])

Pass a representative subset of run IDs (the first and last few) to catch metrics that may have been added or removed over the window. Record each metric's `name` and `type` (counter, gauge, trend, rate).

Group metrics by type -- the query method must match the metric type (see metrics.md "Query methods"). Using the wrong method returns empty results.

Step 5: Fetch per-run aggregate values

For each metric, query its aggregate value across all runs in the window using the multi-run aggregate endpoint (metrics.md Section 8):

GET /cloud/v5/load_tests/{loadTestId}/query_aggregate_k6(
  query='<method>',
  metric='<metric_name>',
  test_run_ids=[{id1},{id2},...]
)

Concrete `gcx` form (proxy prefix per k6-manage §2; `-o json` avoids the spill envelope):

LT=<load_test_id>; IDS="123,124,125"
gcx --context <ctx> api "/api/plugins/k6-app/resources/cloud/cloud/v5/load_tests/$LT/query_aggregate_k6(query='histogram_quantile(0.95)',metric='http_req_duration',test_run_ids=[$IDS])" -o json

Choose the aggregate method based on metric type:

| Metric type | Primary method | What it captures | |-------------|---------------|------------------| | **trend** | `histogram_quantile(0.95)` | P95 latency -- the most common SLO target | | **trend** | `histogram_quantile(0.5)` | Median -- shows typical behavior | | **trend** | `histogram_avg` | Mean -- sensitive to outliers | | **counter** | `increase` | Total count per run | | **rate** | `ratio` | Success/failure ratio | | **gauge** | `max` | Peak value per run |

For trend-type metrics (latencies), query multiple quantiles (P50, P90, P95, P99) to see if degradation is uniform or concentrated in the tail.

**Always break down by request grouping for multi-target tests.** A single aggregate p95 across a whole test obscures regressions confined to one endpoint or one page -- a 3x slowdown on one URL can be invisible at the test-level p95 if the test hits many URLs. Default to grouped queries:

| Metric pattern | Default grouping | Why | |--------------