Telescope (Node)

import { NexusTelescope } from '@inverge/nexus/telescope'

EntryTypeCopy Anchor Link

export type EntryType = | 'request' | 'command' | 'job' | 'schedule' | 'query' | 'model' | 'event' | 'middleware' | 'exception' | 'log' | 'http' | 'cache' | 'redis' | 'mail' | 'notification' | 'gate' | 'view' | 'dump' | 'batch' | 'span';

The entry vocabulary — identical across every Nexus SDK.

TelescopeOptionsCopy Anchor Link

apiKeyCopy Anchor Link

apiKey: string

baseUrlCopy Anchor Link

baseUrl?: string

serviceCopy Anchor Link

service?: string

Service name shown in traces. Default: NEXUS_SERVICE_NAME, else the package name.

releaseCopy Anchor Link

release?: string

sampleRateCopy Anchor Link

sampleRate?: number | null

null = the console's sample rate. Failed/slow/monitored work is always kept.

ignorePathsCopy Anchor Link

ignorePaths?: string[]

ignoreTypesCopy Anchor Link

ignoreTypes?: EntryType[]

redactKeysCopy Anchor Link

redactKeys?: string[]

captureBodiesCopy Anchor Link

captureBodies?: boolean

Record response bodies (JSON is parsed). Default true.

bodySizeLimitCopy Anchor Link

bodySizeLimit?: number

KB. Default 64.

maxEntriesCopy Anchor Link

maxEntries?: number

flushIntervalMsCopy Anchor Link

flushIntervalMs?: number

How often buffered journeys are shipped. Default 2000 ms.

timeoutMsCopy Anchor Link

timeoutMs?: number

Delivery timeout. Default 3000 ms.

enabledCopy Anchor Link

enabled?: boolean

Master switch (also NEXUS_TELESCOPE_ENABLED=false).

fetchCopy Anchor Link

fetch?: typeof globalThis.fetch

onErrorCopy Anchor Link

onError?: (e: unknown) => void

Called on delivery failures (default: silent).

InitOptionsCopy Anchor Link

instrumentCopy Anchor Link

instrument?: { server?: boolean; client?: boolean; console?: boolean; pg?: boolean | unknown; mysql2?: boolean | unknown; ioredis?: boolean | unknown; }

Auto-instrumentation; everything defaults to on.

NexusTelescopeCopy Anchor Link

init()Copy Anchor Link

static init(opts: InitOptions): NexusTelescope

Create (once) and return the process-wide recorder. Call before your app creates its server.

Parameters

Returns NexusTelescope

get()Copy Anchor Link

static get(): NexusTelescope | null

Returns NexusTelescope | null

recorderCopy Anchor Link

readonly recorder: Recorder

express()Copy Anchor Link

express(): (req: AnyReq, res: { once: (e: string, f: () => void) => void; }, next: () => void) => void

Express / Connect middleware: names the route and keeps the parsed body. Mount it first.

Returns (req: AnyReq, res: { once: (e: string, f: () => void) => void; }, next: () => void) => void

expressErrors()Copy Anchor Link

expressErrors(): (err: unknown, _req: unknown, _res: unknown, next: (e: unknown) => void) => void

Express error middleware — records the exception, then passes it on. Mount it last.

Returns (err: unknown, _req: unknown, _res: unknown, next: (e: unknown) => void) => void

fastify()Copy Anchor Link

fastify(): (app: { addHook: (name: string, fn: (...a: never[]) => unknown) => void; }) => Promise<void>

Fastify plugin: await app.register(telescope.fastify()).

Returns (app: { addHook: (name: string, fn: (...a: never[]) => unknown) => void; }) => Promise<void>

koa()Copy Anchor Link

koa(): (ctx: { req: AnyReq; _matchedRoute?: string | undefined; request?: { body?: unknown; } | undefined; }, next: () => Promise<unknown>) => Promise<void>

Koa middleware: app.use(telescope.koa()) (before the router).

Returns (ctx: { req: AnyReq; _matchedRoute?: string | undefined; request?: { body?: unknown; } | undefined; }, next: () => Promise<unknown>) => Promise<void>

prisma()Copy Anchor Link

prisma(): { name: string; query: { $allOperations({ model, operation, args, query }: { model?: string | undefined; operation: string; args: unknown; query: (a: unknown) => Promise<unknown>; }): Promise<unknown>; }; }

Prisma: const db = new PrismaClient().$extends(telescope.prisma()).

Returns { name: string; query: { $allOperations({ model, operation, args, query }: { model?: string | undefined; operation: string; args: unknown; query: (a: unknown) => Promise<unknown>; }): Promise<unknown>; }; }

job()Copy Anchor Link

job<T>(name: string, fn: () => Promise<T> | T, opts: { carrier?: Record<string, unknown>; queue?: string; attempts?: number; data?: unknown } = {}): Promise<T>

Run a queued job as its own journey. Pass the job's data as carrier so it joins the trace of the request that queued it (see {@link inject}).

new Worker('emails', (job) => telescope.job(job.name, () => send(job.data), { carrier: job.data, queue: 'emails' }));

Parameters

Returns Promise<T>

command()Copy Anchor Link

command<T>(name: string, fn: () => Promise<T> | T, args?: Record<string, unknown>): Promise<T>

A CLI command / script as a journey.

Parameters

Returns Promise<T>

schedule()Copy Anchor Link

schedule<T>(name: string, fn: () => Promise<T> | T, expression?: string): Promise<T>

A scheduled task (node-cron, agenda, …) as a journey.

Parameters

Returns Promise<T>

inject()Copy Anchor Link

inject(jobName?: string, queue?: string): Record<string, string>

Fields to merge into a job payload so its execution joins this trace, and records the dispatch in the current journey: queue.add('send', { ...data, ...telescope.inject('SendInvoice', 'emails') }).

Parameters

Returns Record<string, string>

span()Copy Anchor Link

span<T>(name: string, fn: () => T, content: Record<string, unknown> = {}): T

Parameters

Returns T

record()Copy Anchor Link

record(type: EntryType, content: Record<string, unknown>, opts?: { durationMs?: number; status?: string; name?: string; tags?: string[] }): void

Parameters

query()Copy Anchor Link

query(sql: string, bindings: unknown[] = [], durationMs?: number, connection?: string): void

Parameters

event()Copy Anchor Link

event(name: string, payload?: unknown, listeners?: string[]): void

Parameters

cache()Copy Anchor Link

cache(action: 'hit' | 'missed' | 'set' | 'forget', key: string, value?: unknown): void

Parameters

log()Copy Anchor Link

log(level: string, message: string, context?: Record<string, unknown>): void

Parameters

exception()Copy Anchor Link

exception(error: unknown, handled: boolean = true, context?: Record<string, unknown>): void

Parameters

user()Copy Anchor Link

user(user: { id: string | number; email?: string; name?: string } & Record<string, unknown>): void

The signed-in user of the current request: tags it Auth:<id>, links it to Nexus Sessions.

Parameters

tag()Copy Anchor Link

tag(tags: string[]): void

Parameters

traceparent()Copy Anchor Link

traceparent(): string | null

Returns string | null

flush()Copy Anchor Link

flush(): Promise<void>