Configuration

Periscope reads config/periscope.ts during application boot. Wrap the object with defineConfig for type checking, default resolution, and strict validation:

import { defineConfig } from '@rikology/adonisjs-periscope/periscope_config'

export default defineConfig({
  applicationName: 'billing-api',
})

Unknown keys and invalid values fail boot with a PeriscopeConfigError that reports every detected problem. Nested objects merge over the defaults. Arrays replace their defaults rather than extending them.

Runtime switches

PERISCOPE_ENABLED has final precedence. 1 and true force recording on; 0 and false force it off. Matching ignores case and surrounding whitespace. Any other value is ignored and normal config resolution applies.

When recording is disabled, the provider installs no watcher, logger, process, model, or dashboard hooks.

Storage

storage: {
  driver: 'sqlite-local',
  maxEntries: 10_000,
  retention: {
    hours: 48,
    keepExceptions: true,
    perType: {
      query: { hours: 12 },
      mail: { hours: 168 },
    },
  },
}

Driver selection:

• sqlite-local stores a dedicated SQLite database under tmp/ and requires no Lucid setup.
• database uses the application’s Lucid connection and requires the shipped migration.
• memory is process-local and disappears on exit. Maintenance commands reject it because Ace runs in a separate process.
• custom calls storage.factory({ app, config }). See Authoring adapters.

For shared databases, assign a unique applicationName to every application. See Operations for deployment and pruning guidance.

Recording

Caps limit a noisy batch; storage.maxEntries limits the whole store. Sampling drops or keeps the entire batch, preserving request correlation:

recording: {
  sampleRate: 0.1,
  caps: { default: 50, query: 100, mail: 5 },
  keepAlways: (batch) =>
    batch.hasEntryOfType('exception') ||
    batch.hasTag('important') ||
    batch.hasEntryWhere((entry) => Number(entry.content.durationMs) > 1_000),
}

Monitored tags also retain sampled-out batches. Use exact tags; tag matching is not substring-based.

Redaction

Redaction arrays replace the shipped defaults. Spread the exported constants to extend them:

import {
  DEFAULT_REDACT_HEADERS,
  DEFAULT_REDACT_KEYS,
  DEFAULT_REDACT_VALUE_PATTERNS,
  REDACT_EMAIL_PATTERN,
  defineConfig,
} from '@rikology/adonisjs-periscope/periscope_config'

export default defineConfig({
  redact: {
    keys: [...DEFAULT_REDACT_KEYS, 'internal_reference'],
    headers: [...DEFAULT_REDACT_HEADERS, 'x-internal-token'],
    valuePatterns: [...DEFAULT_REDACT_VALUE_PATTERNS, REDACT_EMAIL_PATTERN],
  },
})

Filter hooks run before redaction and therefore see raw values. Tag hooks run after redaction. Exports do not run a second redaction pass; review exported files as sensitive artifacts.

Hooks

hooks: {
  filter: [(entry) => entry.type !== 'log'],
  tag: [
    (entry) =>
      entry.type === 'request' ? ['application-traffic'] : [],
  ],
}

Hook failures are safeguarded so diagnostic customization cannot break application work.

Watchers

Every watcher accepts enabled. A disabled watcher subscribes to nothing. Core framework watchers are enabled by default; infrastructure integrations and capture of application-owned payloads are opt-in.

Globs in request.ignorePaths and event.ignore use * for any run of characters. The log watcher cannot recover messages already filtered by Pino, so its effective floor is the stricter of the application logger level and watchers.log.level.

See Watchers and troubleshooting for the signal catalogue and Authoring adapters for queue, scheduler, notification, socket, custom watcher, store, and fanout contracts.

Dashboard

Changing dashboard.path does not weaken the production gate. For deliberate production exposure, replace dashboard.authorize with an application-specific policy and follow the dashboard security checklist.

The default fanout reaches only clients connected to the worker that recorded an entry. Durable storage still makes entries visible to polling clients on other workers. See Multi-process live updates.

Validation and merge rules

• Unknown keys are errors, including misspelled watcher and entry-type names.
• Nested objects merge over defaults.
• Arrays replace defaults and are copied during resolution.
• recording.caps precedence is an explicit entry type, then the supplied default, then the built-in type default.
• storage.retention.perType accepts only known entry types and requires a positive hours value.
• storage.factory is required only for driver: 'custom'.
• dashboard.path must start with /.
• Integer limits reject negative, fractional, infinite, and unsafe values.