/frontend-session-rca

name: frontend-session-rca
license: Apache-2.0
description: >
  Diagnoses a Grafana Frontend Observability (RUM) session: whether it is healthy,
  what went wrong, ranked problems with timestamps and evidence, likely cause, how
  to fix it. Optional follow-up: zoom in on the top error, impact across sessions,
  Session Replay, or a Tempo trace if the user asks.
  Fetches telemetry with `gcx frontend sessions get --save` and reads only that dump
  file.
  Use when the user asks to explain, diagnose, analyse, RCA, or review a session;
  asks if a session is healthy; pastes Frontend Observability session context (app
  id, session id, datasource UID); or mentions Faro, user journey, Core Web Vitals,
  exceptions, ANR, or a web or mobile RUM session — even if they do not say
  "session narrator" or "frontend-session-rca". Do not use this skill to instrument
  an app (Faro Web, React Native, Flutter, native OpenTelemetry) — use
  `app-observability` for Faro Web setup instead.

Frontend Observability session RCA

Diagnose one real-user session from a `gcx` dump. First answer is dump-only. Do not invent LogQL, SQL, or Explore URLs. Do not instrument SDKs here.

1. Collect identity

Required — do **not** fetch until all three are present:

• **app id**: `<app_id>`
• **session id**: `<session_id>`
• **datasource UID** (`-d`): `<datasource_uid>` — Grafana datasource UID, not `loki` or `pinot`

Optional:

• **grafana URL**: `<grafana_url>`
• **from**: `<from>`
• **to**: `<to>`

Take them from the prompt, pasted Frontend Observability session context, or filled placeholders above. If a required value is still a `<…>` token or missing, **ask the user and stop**. Do not guess ids. Do not pick a datasource for them (you may mention `gcx datasources list` so they can choose a Loki or Pinot UID). In that same ask, say the time-range default below so they can override it in one reply.

Optional also: `--app-type web|mobile`.

Time range is **not** required. If the user did not give `--from`/`--to` or `--since`, tell them:

> We will run the query for 1d for Loki and 7d for Pinot. If you want a different time range, please provide it.

Do **not** call `gcx` yet. Infer Loki vs Pinot and choose `--since` in step 2, after gcx is installed and logged in. If they already gave a window, use that (`--since` is mutually exclusive with `--from`).

2. Ensure gcx

command -v gcx && gcx frontend sessions get -h

| Result | Action | |---|---| | `gcx` missing | Tell the user to install from https://github.com/grafana/gcx (`brew install gcx` or the curl installer on that README). Do not invent tokens. | | `gcx` present, `sessions get` unknown | Installed gcx is too old. Tell the user to upgrade gcx, then retry. | | Command exists | Continue. |

Unauthenticated:

gcx login --server <grafana_url>

Grafana base URL (for deep links), if the user did not paste one:

gcx config view -o json

Use the current stack `grafana.server`. Do not print tokens.

Then infer Loki vs Pinot from the UID (`gcx datasources get <datasource_uid>`). Use the Type field as a **kind**: `loki` (or Type contains `loki`) → `--since 1d` (session Loki queries time out at 60s). `pinot` (or Type contains `pinot`) → `--since 7d`. Do not require a specific plugin id. If they already gave `--from`/`--to` or `--since`, keep that window.

3. Fetch the session

Always `--save` so stdout is a small artifact receipt (path only), not the dump.

gcx frontend sessions get <session_id> \
  --app <app_id> \
  -d <datasource_uid> \
  --since <since> \
  --save /tmp/session-<session_id>.txt

• `-d/--datasource` is required (Grafana datasource UID). Do not pass `loki` or `pinot` as the value. gcx infers the type from the datasource.
• Time range: use the user’s `--from`/`--to` or `--since` when they gave one. Otherwise `--since 1d` (Loki) or `--since 7d` (Pinot) after telling them the default (see steps 1–2). `--since` is mutually exclusive with `--from`.
• Omit `--app-type` unless the user set it; gcx infers web vs mobile from the dump.
• Agent mode requires `--save`. If stdout is JSON `gcx.artifact_receipt`, read `files[0].path`. If stdout is `Wrote <path>`, read that path.

Never paste the dump into the user-visible reply.

4. Read the dump, then answer

1. Open the file. Parse `=== session metadata ===` then `=== events ===`. See [dump-format.md](references/dump-format.md). 2. Classify health and rank issues using [signal-catalog.md](references/signal-catalog.md). 3. Follow-up is 1–3 questions, not a link dump (see template). Do not attach Tempo URLs to every problem. Do not call a replay API.

**Empty or failed fetch:** say so. Suggest widening `--since` / `--from`/`--to`, checking `--app` and `--datasource`, and confirming the user can see the session in Frontend Observability. Stop.

**Specific question** (one error, one page, one trace, “why is LCP poor”, “why was cold start slow”, “other sessions with this error”): answer that. Skip the full template. Dump-only unless they asked for impact or a trace — then a scoped `gcx logs query` / `gcx datasources pinot query` / `gcx traces get` is allowed (see Grounding rules).

**Vague “diagnose / explain this session”:** use the template below.

Full-session template

## Session overview
- App, session id, web or mobile, duration (`session_start` → last event as `session_end` only if `session_start` is in this dump; if that event is missing, say so — do not use the first row as start. `session_end` is not a Faro event)
- Environment: browser/OS or device/SDK, geo, app version, user id/username if present (avoid email/PII unless the user explicitly asks)
- Outcome: **healthy** | **degraded** | **error** | **unknown**

## What the user did
3–6 sentences of the journey in time order, oldest first (navigation, views, actions). No raw dump.

## Session health
One paragraph: healthy or not, and why (exceptions, failed HTTP, poor web vitals or