@adonis-agora/telescope 0.8.4 → 0.8.5

package/skills/telescope-alerts-ai/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: telescope-alerts-ai
+description: >-
+  Alerting, AI diagnosis and client-error ingestion in @adonis-agora/telescope —
+  config/telescope_alerts.ts with AlertRule types (new-exception, every-exception,
+  exception-rate, stateful metric-threshold), channel helpers (slackChannel,
+  webhookChannel, consoleChannel, customChannel), every/cooldown/instanceId/
+  geoLookup; config/telescope_ai.ts + TelescopeAiDiagnoser Claude diagnosis cached
+  by familyHash (keyless = disabled); clientErrors sendBeacon endpoint. Use for
+  "Slack alert on new errors", "AI diagnose exceptions", "page on every error",
+  "report browser errors", "why didn't my alert fire".
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/telescope"
+  library_version: "0.8.4"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-telescope:docs/packages/alerts.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/ai.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/client-errors.mdx"
+  - "DavideCarvalho/adonis-telescope:packages/core/src/alerts/index.ts"
+---
+
+# Alerting, AI diagnosis & client errors
+
+The alerter polls the store on an interval, evaluates rules over recorded
+`exception` entries, and fans each fire out to every configured channel. The AI
+subpath attaches a Claude root-cause diagnosis to an exception, cached by family.
+Client-error ingestion lets browsers report their own failures into the same
+pipeline. All three are subpaths of the one package — enable them via
+`node ace configure @adonis-agora/telescope` (pick **Alerts** / **AI**).
+
+## Setup
+
+```ts
+// config/telescope_alerts.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/alerts'
+
+export default defineConfig({
+  channels: [{ type: 'slack', url: env.get('TELESCOPE_SLACK_WEBHOOK') }],
+  rules: [{ type: 'new-exception', window: '1h' }],
+  dashboardUrl: 'https://telescope.example.com/', // enables Slack deep links
+  every: '30s',        // poll cadence — alerts are as late as the interval
+  cooldown: '15m',     // per-rule / per-family re-notify suppression
+})
+```
+
+```ts
+// config/telescope_ai.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/ai'
+
+export default defineConfig({
+  apiKey: env.get('ANTHROPIC_API_KEY'),   // validate as Env.schema.string.optional()
+  model: 'claude-sonnet-4-6',             // default; claude-opus-4-8 / claude-haiku-4-5-20251001
+  maxTokens: 1024,
+})
+```
+
+Durations are validated at boot — an unparseable `every`/`cooldown`/`window`
+(`'15min'`, a typo) **throws**, fail-closed. Valid units: `ms`, `s`, `m`, `h`, `d`.
+
+Source: `docs/packages/alerts.mdx` (Configuration),
+`docs/packages/ai.mdx` (Configuration).
+
+## Core patterns
+
+### Pattern 1 — pick rules deliberately
+
+```ts
+rules: [
+  { type: 'new-exception', window: '1h' },   // first sighting of a family (+ recurrences after it)
+  { type: 'every-exception', window: '15m' },// EVERY server + browser error, cooldown-limited per family;
+                                             // window is display-only (labels the occurrence count)
+  { type: 'exception-rate', window: '5m', threshold: 10 },
+  {
+    type: 'metric-threshold',                // stateful raise/auto-resolve, evaluated on every poll
+    metric: 'request-p99-ms',                // or query-p95-ms, cache-hit-rate, exception-count, ...
+    window: '5m',
+    comparator: 'gte',
+    threshold: 800,
+    minSamples: 10,                          // guard percentiles against a single slow request
+  },
+]
+```
+
+`new-exception` dedup is a bounded per-process map — in a multi-replica deploy the
+same family reports "new" once per replica, so budget `cooldown` accordingly.
+
+Source: `docs/packages/alerts.mdx` (Rules, Deduplication).
+
+### Pattern 2 — diagnose an exception with its trace context
+
+`TelescopeAiDiagnoser` is always resolvable from the container — even when disabled,
+when `diagnose` resolves `null` — so you can inject it without a null check.
+
+```ts
+// app/controllers/diagnose_controller.ts
+import { inject } from '@adonisjs/core'
+import type { HttpContext } from '@adonisjs/core/http'
+import { TelescopeService } from '@adonis-agora/telescope'
+import { TelescopeAiDiagnoser } from '@adonis-agora/telescope/ai'
+
+@inject()
+export default class DiagnoseController {
+  constructor(
+    private telescope: TelescopeService,
+    private diagnoser: TelescopeAiDiagnoser,
+  ) {}
+
+  async show({ params, response }: HttpContext) {
+    const entry = await this.telescope.find(params.id)
+    if (!entry || entry.type !== 'exception') {
+      return response.notFound({ error: 'Not an exception entry' })
+    }
+    const related = entry.traceId ? await this.telescope.byTrace(entry.traceId) : []
+    const diagnosis = await this.diagnoser.diagnose(entry, { related })
+    // → { cause, fix, confidence, model, cached } | null — never throws
+    return response.json(diagnosis)
+  }
+}
+```
+
+Diagnoses cache per `familyHash` (bounded LRU, 24h TTL); pass `{ force: true }` to
+spend a fresh call after changing code.
+
+Source: `docs/packages/ai.mdx` (Use it), `docs/recipes/ai-exception-diagnosis.mdx`.
+
+### Pattern 3 — a custom channel sink
+
+Channels fan out concurrently; one failing never blocks the others.
+
+```ts
+import { defineConfig, customChannel, slackChannel } from '@adonis-agora/telescope/alerts'
+import env from '#start/env'
+
+export default defineConfig({
+  channels: [
+    slackChannel(env.get('TELESCOPE_SLACK_WEBHOOK'), { username: 'Telescope' }),
+    customChannel(async (alert) => { await pagerduty.trigger(alert) }, 'pagerduty'),
+  ],
+  rules: [{ type: 'new-exception', window: '1h' }],
+})
+```
+
+Exception alerts carry `{ cause, fix, confidence, model }` when AI is configured —
+a guarded hook, so a slow model never delays or breaks the page.
+
+Source: `docs/packages/alerts.mdx` (Channels).
+
+### Pattern 4 — ingest browser errors
+
+Disabled by default; the route only exists once you enable it. Report with
+`navigator.sendBeacon`; entries become `client_exception` records through the same
+redaction/sampling/prune pipeline as server exceptions.
+
+```ts
+// config/telescope.ts
+export default defineConfig({
+  clientErrors: {
+    enabled: true,
+    path: '/telescope/client-errors',
+    maxBodyBytes: 32_768,          // larger bodies rejected 413 before validation
+    rateLimit: { perMinute: 60 },  // per-IP token bucket; over → 429
+  },
+})
+```
+
+```ts
+// Browser reporter
+window.addEventListener('error', (event) => {
+  navigator.sendBeacon(
+    '/telescope/client-errors',
+    JSON.stringify({
+      message: event.message,
+      name: event.error?.name ?? null,
+      stack: event.error?.stack ?? null,
+      url: location.href,
+      userAgent: navigator.userAgent,
+    }),
+  )
+})
+```
+
+Only `message` is required; `clientIp` is filled server-side, never trusted from
+the body.
+
+Source: `docs/packages/client-errors.mdx`.
+
+## Common mistakes
+
+### HIGH Listing two rules of the same exception type
+
+```ts
+// Wrong — the second new-exception rule is SILENTLY ignored.
+rules: [
+  { type: 'new-exception', window: '1h' },
+  { type: 'new-exception', window: '24h' },
+]
+```
+
+```ts
+// Correct — at most one of each exception rule; express variations via window/threshold.
+rules: [
+  { type: 'new-exception', window: '1h' },
+  { type: 'exception-rate', window: '5m', threshold: 10 },
+]
+```
+
+Mechanism: `new-exception`, `every-exception` and `exception-rate` are looked up
+once by type; duplicates never evaluate (`metric-threshold` is exempt).
+Source: `docs/packages/alerts.mdx` (When rules do and don't run).
+
+### HIGH Shipping AI config without a resolvable key
+
+```ts
+// Wrong — keyless install looks configured but silently does nothing:
+export default defineConfig({ model: 'claude-opus-4-8' })   // no apiKey, no client
+const diagnosis = await diagnoser.diagnose(entry)           // always null
+```
+
+```ts
+// Correct — source the key from validated env; check isConfigured() when unsure.
+export default defineConfig({ apiKey: env.get('ANTHROPIC_API_KEY') })
+```
+
+Mechanism: a configured-but-keyless install is treated as disabled — `diagnose`
+resolves `null` forever and the dashboard hides the Diagnose button, with no error
+anywhere.
+Source: `docs/packages/ai.mdx` (warn callout), `docs/reference/configuration.mdx` (AI).
+
+### MEDIUM Expecting sampled-out exceptions to page
+
+```ts
+// Wrong — sampling drops most queries AND some exceptions before any rule sees them.
+sampling: { default: 0.1 },
+rules: [{ type: 'new-exception', window: '1h' }],
+```
+
+```ts
+// Correct — tail-sampling keeps errors/slow regardless of rate.
+sampling: { default: 0.1, exception: { rate: 0.1, keepErrors: true } },
+```
+
+Mechanism: only what was recorded is alertable — sampling and the overload shed run
+before the alerter's poll, and polling itself adds up to `every` of latency.
+Source: `docs/packages/alerts.mdx` (How it hooks in).
+
+### MEDIUM Short cooldown with every-exception
+
+```ts
+// Wrong — a tight loop of the same error re-pages once per cooldown... which is 1 minute.
+rules: [{ type: 'every-exception' }],
+cooldown: '1m',
+```
+
+```ts
+// Correct — tune cooldown to your on-call tolerance; different families still page immediately.
+rules: [{ type: 'every-exception', window: '15m' }],
+cooldown: '10m',
+```
+
+Mechanism: cooldown is the *only* thing rate-limiting repeats per family (on its own
+independent clock from `new-exception`), so a short one on a noisy family is a
+self-inflicted alert storm.
+Source: `docs/packages/alerts.mdx` (cooldown info callout).
+
+### MEDIUM Probing for the client-error endpoint while it is disabled
+
+```sh
+# Wrong — expecting a 404 that proves wiring:
+curl -X POST http://localhost:3333/telescope/client-errors
+# → generic route-not-found; can't tell whether telescope owns this prefix
+```
+
+```ts
+// Correct — enable it, then verify the 204:
+clientErrors: { enabled: true }
+// curl -X POST ... → 204 No Content once registered
+```
+
+Mechanism: unlike an always-mounted controller, the provider registers the POST
+route only when `clientErrors.enabled` is true — while off the endpoint genuinely
+does not exist.
+Source: `docs/packages/client-errors.mdx` (Disabled by default warn callout).
+
+See also: `telescope-watchers/SKILL.md` — capture gaps become alert gaps;
+`telescope-access-mcp/SKILL.md` — the diagnose endpoint rides behind the dashboard guard.

package/skills/telescope-setup/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: telescope-setup
+description: >-
+  Set up @adonis-agora/telescope in an AdonisJS app. Covers node ace configure
+  codemods (telescope_provider + TelescopeMiddleware on the server stack +
+  config/telescope.ts), defineConfig keys (enabled/store/stores/watchers/redact),
+  the storage.memory and storage.lucid drivers, the headless TelescopeService query
+  API (list/find/byTrace/count/topFamilies/topTags/getHealth), recordException for
+  non-HTTP paths, opt-in requestCapture body gates, and why /telescope 404s without
+  @adonis-agora/telescope-ui. Use for "install telescope", "telemetry is empty",
+  "query captured entries", "capture request bodies", "AdonisJS observability".
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/telescope"
+  library_version: "0.8.4"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-telescope:README.md"
+  - "DavideCarvalho/adonis-telescope:docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/core.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/reference/configuration.mdx"
+---
+
+# Setting up @adonis-agora/telescope
+
+`@adonis-agora/telescope` is Laravel Telescope-style **headless** observability for
+AdonisJS: it records every inbound HTTP request, every unhandled exception and every
+`agora:<lib>:<event>` diagnostics publish as a queryable `Entry`. The core ships no
+page — mounting a UI is a separate package (`telescope-ui-dashboard` skill).
+
+## Setup
+
+```sh
+pnpm add @adonis-agora/telescope
+node ace configure @adonis-agora/telescope
+```
+
+`configure` runs codemods that register `@adonis-agora/telescope/telescope_provider`
+in `adonisrc.ts`, plug `TelescopeMiddleware` onto the **server** middleware stack
+(so it wraps the whole pipeline and observes the final status), and publish
+`config/telescope.ts`. That alone records `request` + `diagnostic` entries.
+
+The published config is all-defaults:
+
+```ts
+// config/telescope.ts
+import { defineConfig, storage } from '@adonis-agora/telescope'
+
+export default defineConfig({
+  enabled: true,                          // master switch
+  store: 'memory',                        // which driver in `stores` is active
+  stores: {
+    memory: storage.memory({ limit: 1000 }),   // bounded ring buffer, lost on restart
+    // lucid: storage.lucid({ connection: 'pg' }), // persistent SQL store (optional peer)
+  },
+  watchers: ['request', 'diagnostics'],   // omit one to disable it
+})
+```
+
+Read entries back from anywhere via the container:
+
+```ts
+import { TelescopeService } from '@adonis-agora/telescope'
+
+const telescope = await app.container.make(TelescopeService)
+
+await telescope.list({ type: 'request', limit: 50 })   // newest-first
+await telescope.byTrace('abc123')                       // one request's whole story
+await telescope.list({ tag: 'lib:billing', search: 'invoice' })
+await telescope.topFamilies(10, 'diagnostic')           // busiest lib:event pairs
+```
+
+## Core patterns
+
+### Pattern 1 — the headless API inside a controller
+
+Controllers have no `app` of their own; use `@inject()` so the container resolves
+the constructor dependency.
+
+```ts
+// app/controllers/inspector_controller.ts
+import { inject } from '@adonisjs/core'
+import type { HttpContext } from '@adonisjs/core/http'
+import { TelescopeService } from '@adonis-agora/telescope'
+
+@inject()
+export default class InspectorController {
+  constructor(private telescope: TelescopeService) {}
+
+  async index({ response }: HttpContext) {
+    return response.json(await this.telescope.list({ limit: 50 }))
+  }
+}
+```
+
+`EntryQuery` composes filters with AND: `{ type, tag, familyHash, traceId, before,
+after, search, limit }`. `search` matches JSON content **and** tags, so a request
+matches by url, a diagnostic by event name, a query by SQL — all from one box.
+For React usage in a custom console, see the `telescope-ui-dashboard` skill.
+
+Source: `docs/getting-started.mdx` (Step 3).
+
+### Pattern 2 — manual exception capture outside HTTP
+
+Queue workers, ace commands and `app/exceptions/handler.ts` are not wrapped by the
+middleware. `recordException` reads the live store with nothing injected, is a no-op
+when Telescope is off, and never throws.
+
+```ts
+// app/exceptions/handler.ts
+import { recordException } from '@adonis-agora/telescope'
+
+async report(error: unknown, ctx: HttpContext) {
+  recordException(error, { method: ctx.request.method(), url: ctx.request.url() })
+  return super.report(error, ctx)
+}
+```
+
+Exceptions group by `exceptionFamilyHash` = `name:message:topStackFrame`, so alerts
+and the dashboard's exception groups stay deterministic across processes.
+
+Source: `docs/concepts/capture.mdx` (Manual capture), `docs/packages/core.mdx`.
+
+### Pattern 3 — opt-in request-body capture
+
+By default a `request` entry has **no `body` field at all**. Turn it on with gates
+that run before redaction; a rejected body becomes a marker string like
+`[Skipped: 200000 bytes > 131072 bytes]`.
+
+```ts
+// config/telescope.ts
+export default defineConfig({
+  requestCapture: {
+    maxBodyBytes: 65_536,
+    skipBodyContentTypes: ['multipart/form-data'],
+    skipBody: ({ url }) => url.startsWith('/webhooks/'),
+  },
+})
+```
+
+Captured bodies still pass through central redaction — but a body never captured is
+the only body that definitely cannot leak.
+
+Source: `docs/packages/core.mdx` (Request body capture).
+
+### Pattern 4 — production storage
+
+Switch to the built-in Lucid driver when entries must survive restarts (see the
+`telescope-storage-retention` skill for the migration and pruning):
+
+```sh
+pnpm add @adonisjs/lucid
+node ace migration:run   # create_telescope_entries_table, shipped by configure
+```
+
+```ts
+export default defineConfig({
+  store: 'lucid',
+  stores: { lucid: storage.lucid() },   // or storage.lucid({ connection: 'pg' })
+})
+```
+
+Source: `docs/getting-started.mdx` (Step 4).
+
+## Common mistakes
+
+### HIGH Expecting a dashboard page from the core alone
+
+```ts
+// Wrong — nothing mounts a page; http://localhost:3333/telescope answers 404.
+// adonisrc.ts
+providers: [
+  () => import('@adonis-agora/telescope/telescope_provider'),
+  // ...app providers
+]
+```
+
+```ts
+// Correct — install @adonis-agora/telescope-ui and register its provider AFTER ui_provider.
+providers: [
+  () => import('@adonis-agora/telescope/telescope_provider'),
+  () => import('@adonis-agora/telescope/ui_provider'),                  // JSON API + SSE
+  () => import('@adonis-agora/telescope-ui/telescope_ui_dashboard_provider'), // the SPA
+]
+```
+
+Mechanism: the core `ui` subpath serves only `<path>/api/*`; the prefix root belongs
+to the separate SPA package, whose provider must also be registered after it.
+Source: `docs/packages/ui.mdx` (Install), `docs/packages/telescope-ui.mdx` (warn).
+
+### HIGH Assuming request bodies are captured by default
+
+```ts
+// Wrong — agents assume they can read the payload that broke checkout:
+const entry = await telescope.find(id)
+entry.content.body // undefined — bodies are opt-in
+```
+
+```ts
+// Correct — enable requestCapture explicitly (gates run before redaction).
+defineConfig({
+  requestCapture: { maxBodyBytes: 65_536 },
+})
+```
+
+Mechanism: the right default keeps passwords/card numbers out of storage; the entry
+records method/url/status/duration only until you opt in per environment.
+Source: `docs/packages/core.mdx` (Request body capture).
+
+### HIGH Hand-rolling the provider without the server-stack middleware
+
+```ts
+// Wrong — provider registered but TelescopeMiddleware missing: no requests recorded,
+// no exceptions captured, and nothing warns about it.
+providers: [
+  () => import('@adonis-agora/telescope/telescope_provider'),
+]
+```
+
+```sh
+# Correct — let the configure codemod wire both pieces.
+node ace configure @adonis-agora/telescope
+# verifies: telescope_provider present AND TelescopeMiddleware on the server stack
+```
+
+Mechanism: capture comes from `TelescopeMiddleware` on the `server` middleware
+stack; the provider alone starts only the boot-time watchers, so the timeline stays
+empty while everything looks installed.
+Source: `docs/reference/configuration.mdx` (Providers table), `docs/getting-started.mdx` Step 1.
+
+### MEDIUM Resolving TelescopeService via this.app inside a controller
+
+```ts
+// Wrong — a controller has no `app`; this does not compile.
+constructor(private app: ApplicationService) {}
+async index() {
+  const telescope = await this.app.container.make(TelescopeService)
+}
+```
+
+```ts
+// Correct — constructor injection through @inject().
+@inject()
+export default class InspectorController {
+  constructor(private telescope: TelescopeService) {}
+}
+```
+
+Mechanism: `@inject()` asks the container to build the controller's dependencies
+from their constructor types; `TelescopeService` arrives already resolved.
+Source: `docs/getting-started.mdx` (Step 3 note).
+
+See also: `telescope-ui-dashboard/SKILL.md` — mounting the page this setup lacks;
+`telescope-storage-retention/SKILL.md` — swapping the dev-only memory driver.