@adonis-agora/telescope-ui

@adonis-agora/telescope-ui is a separate, optional package: the React single-page console that renders everything Telescope captured. A thin AdonisJS provider serves the pre-built SPA under the same prefix the core UI provider mounts its JSON API on, behind the same auth guard.

Install

This is its own package (not a subpath). Install it alongside the core and its UI subpath:

npm i @adonis-agora/telescope @adonis-agora/telescope-ui

Then register the provider after the core telescope providers in adonisrc.ts (the SPA consumes the core UI's JSON API, so the core ui_provider must be enabled):

providers: [
  // …
  () => import('@adonis-agora/telescope/telescope_provider'),
  () => import('@adonis-agora/telescope/ui_provider'),   // JSON API + SSE under <path>/api/*
  () => import('@adonis-agora/telescope-ui'),            // serves the SPA at <path>
]

It needs the core UI to be enabled (that is the backend the SPA talks to); if config('telescope_ui').enabled is false it serves nothing. Open http://localhost:3333/telescope.

What it shows

The console holds no server-side state of its own — every view is a call to the core's read routes. Ten sections sit in the left sidebar, in this order:

Under those, a Watchers sub-nav lists every entry type as a colored dot. Clicking one jumps to Entries pre-filtered to that type. The list is the twelve built-in types plus any type an extension contributed that isn't already one of them.

The Queues, Profiles and AI-diagnosis surfaces are gated on what the install actually supports — the console asks <path>/api/meta and, when a capability is off, renders an empty state telling you which config key turns it on rather than a button that would fail.

Getting around

• Command palette — ⌘K on macOS, Ctrl-K elsewhere (the same chord closes it), or the ⌘K button in the header. Type to filter, arrow keys to move, Enter to go. It lists every section, a Entries: <type> jump for each entry type, and one entry per extension dashboard. It's a navigator, not a search over your entries.
• Retention indicator — a retention: 24h chip in the header, reading the same posture the Overview panel shows, so you can tell "nothing happened" apart from "it was already pruned". A ? badge appears next to it when some entry type is being sampled below 100%, because then the counts on screen undercount reality.
• Theme — a header toggle flips light and dark. The choice is remembered in localStorage under telescope-theme; the default is dark.
• Entry actions — an exception's detail view offers Diagnose with AI (and a Re-run that spends a fresh model call) when ai is configured; a request's detail view offers Replay request. Both are always user-initiated.

Exports

The Exports section is entirely client-side — there is no server export endpoint. It runs one ordinary <path>/api/entries query with the type, search and row limit you pick (up to 500, the same cap the API enforces), then hands the browser the result as a file:

• JSON — the entries as pretty-printed JSON.
• CSV — RFC 4180, columns id, type, createdAt, durationMs, tags, familyHash, traceId, summary.

What you get is the list projection, the same rows the Entries table shows, so an export carries no entry content — content is searched server-side but never written into the file. Files are named telescope-export-<type>-<timestamp>.<ext>, and the last ten exports of the session are listed underneath so you can see what you already pulled.

How it mounts

The provider serves the Vite build as static assets, on exactly two routes:

There is no separate trailing-slash route and no redirect between the two forms: AdonisJS treats <mount> and <mount>/ as the same route, and the shell's asset URLs are rewritten to absolute paths so they resolve either way.

<mount> defaults to config('telescope_ui').path (/telescope), so the SPA and the JSON API share a prefix and the SPA's <path>/api/* calls line up. The core provider's static API routes take precedence over this wildcard, so the API always wins. Both routes run the same authorize guard as the API, plus the dashboardAuth session guard when configured — a page navigation with no valid session is redirected to the login page rather than answered with JSON.

Configuration

The SPA reuses the core config/telescope_ui.ts block for its mount path and authorize guard, so it sits behind the exact same auth as the API it consumes. An optional nested dashboard block only toggles the SPA on/off and, if you want it served from a different prefix, overrides the mount:

import { defineConfig } from '@adonis-agora/telescope/ui'

export default defineConfig({
  path: '/telescope',
  credentials: { token: process.env.TELESCOPE_UI_TOKEN },
  dashboard: {
    enabled: true,
    // path: '/__telescope',   // override the SPA mount (defaults to `path` above)
  },
})

The console's mutating actions are gated by the core config, not this block: replay, cpuProfiling.armEnabled and queueActions.enabled are each off by default — see @adonis-agora/telescope/ui.

The client (build your own)

The package also exports a typed client at @adonis-agora/telescope-ui/client — the very one the console uses, with no React and no dependencies of its own — for embedding Telescope data in your own admin UI:

import { TelescopeClient } from '@adonis-agora/telescope-ui/client'

const client = new TelescopeClient({ baseUrl: '/telescope/api' })
const entries = await client.listEntries({ type: 'exception', size: 20 })

new TelescopeClient(options?) takes baseUrl (defaults to the base resolved for the current page), fetch (inject your own for tests) and size (the default page size, 50). Every request is sent same-origin, so it inherits whatever session already gates the dashboard.

Reading

Profiles, queues and schedules

Acting on an entry

Helpers

The same subpath exports the presentation helpers the console formats with, so your own UI can render numbers identically:

Plus the API-base resolution the SPA bootstraps with: resolveApiBase() returns the base injected into the shell by the provider, falling back to deriveApiBase(location.pathname) — which is just "the dashboard's own path, with /api appended unless it's already there". Pass an explicit baseUrl to TelescopeClient and neither is consulted.

ENTRY_TYPES is the tuple of the twelve built-in entry types (request, query, exception, client_exception, job, mail, cache, redis, event, log, http-client, diagnostic) — useful for building a type filter. Entry['type'] is a plain string, so a custom watcher or an extension can record types outside that list.

Every wire shape is exported as a type too — Entry, EntrySummary, EntriesQuery, StatsResult, TimeseriesReport, TraceSummary, Waterfall, NPlusOnePattern, PulseSummary, RetentionInfo, TelescopeMeta, Panel, DashboardSpec, CpuProfileContent, LiveQueues, LiveSchedules and the rest.

Peer dependencies

@adonis-agora/telescope (the backend) and @adonisjs/core (^7.3.0, optional peer). React, Tailwind CSS and Vite are dev-only — the published package ships the pre-built SPA, so there is no build step in your app. The console itself is built with Tailwind and Base UI; the /client subpath is plain TypeScript with no dependencies at all.