The agent is configured in config/monocle.ts. The file is created for you by node ace add. This page lists every option and the most common customizations.
Default configuration
This is the file generated by node ace add:
import { defineConfig } from '@monocle.sh/adonisjs-agent'
import env from '#start/env'
export default defineConfig({
// Send telemetry to Monocle Studio instead of Monocle cloud
dev: process.env.NODE_ENV === 'development',
dsn: env.get('MONOCLE_DSN'),
environment: env.get('APP_ENV'),
})| Option | Description |
|---|---|
dev | When true, telemetry goes to Monocle Studio on localhost:4200 and the DSN is ignored. |
dsn | Connection string of your service. Falls back to the MONOCLE_DSN environment variable. |
serviceVersion | Version of the deployed code. When unset or a placeholder, the agent detects it. |
environment | Monocle environment: production, staging, or development. Falls back to NODE_ENV, then development. |
apiKey and serviceName still work for existing setups but are deprecated for Monocle cloud.
See Migrate to DSN.
Neither APP_NAME nor APP_VERSION is generated or required. To pin a version, set MONOCLE_VERSION or APP_VERSION in the environment, or set serviceVersion explicitly. See the detection order.
With a DSN, the collector uses the service name attached to the DSN. In Studio, without a DSN, or for extra OTLP destinations, the agent uses serviceName, then OTEL_SERVICE_NAME, then APP_NAME, then the app's package.json name without its npm scope. If no name is available, it uses unknown_service.
Existing apps need no change. The old serviceVersion: env.get('APP_VERSION') line still works with its existing validator. Placeholder versions such as 0.0.1 are skipped.
Full reference
Every other option is optional. The values below are the defaults.
import { defineConfig } from '@monocle.sh/adonisjs-agent'
import env from '#start/env'
export default defineConfig({
dev: process.env.NODE_ENV === 'development',
dsn: env.get('MONOCLE_DSN'),
environment: env.get('APP_ENV'),
// Custom ingestion endpoint (default: https://ingest.monocle.sh)
endpoint: 'https://ingest.monocle.sh',
// Skip OPTIONS/CORS preflight requests (default: true)
ignoreOptionsRequests: true,
// Enable gzip compression (default: true)
compression: true,
// Trace batching configuration
batch: {
maxExportBatchSize: 512,
scheduledDelayMillis: 5000,
exportTimeoutMillis: 30000,
maxQueueSize: 2048,
},
// Host metrics: CPU, memory, network (default: enabled)
hostMetrics: {
enabled: true,
},
// Sampling ratio (0.0 to 1.0). Use 0.1 for high-traffic production.
// Default: 1.0 (100% of traces sampled)
samplingRatio: 1.0,
// Adonis features (enabled by default when the corresponding libraries are available)
mail: { enabled: true },
queue: { enabled: true },
cli: { enabled: true },
// Install and register optional integrations below as needed
integrations: [],
})Customizing instrumentations
You can configure individual OpenTelemetry instrumentations by passing options keyed by their package name.
export default defineConfig({
// ...
instrumentations: {
'@opentelemetry/instrumentation-http': {
// Add URLs to ignore (merged with defaults by default)
ignoredUrls: ['/internal/*', '/api/ping'],
// Set to false to replace default ignored URLs instead of merging
mergeIgnoredUrls: true,
// Ignore static files like css, js, images (default: true)
ignoreStaticFiles: true,
},
// Disable a specific instrumentation entirely
'@opentelemetry/instrumentation-pg': { enabled: false },
},
})Default ignored URLs include /health, /healthz, /ready, /readiness, /metrics, /favicon.ico and other common health check paths.
Sampling
Use samplingRatio to keep a fixed share of traces, or the sampling(ctx) hook for per-job rules, for example keeping 1% of a noisy job while still recording every failure. See Job Sampling.
Sending to other OTLP backends
You can send telemetry to additional OTLP backends alongside Monocle. The Monocle destination is always injected automatically.
import { defineConfig, destinations } from '@monocle.sh/adonisjs-agent'
export default defineConfig({
// ...
destinations: [
destinations.otlp({
name: 'grafana',
url: 'https://otlp-gateway.grafana.net/otlp',
headers: {
Authorization: `Basic ${btoa('instance_id:api_key')}`,
},
}),
],
})Each destination receives the full telemetry data (traces, metrics, logs).
Disabling telemetry
Outside of dev mode, telemetry is disabled when no DSN is set. Leave MONOCLE_DSN empty in any environment that should not report to Monocle:
MONOCLE_DSN=Telemetry is also disabled automatically when NODE_ENV=test, so your test suite never sends data.
Debugging the agent
Set debug: true to also print every span to the console, which helps checking what the agent records before looking at Monocle:
export default defineConfig({
// ...
debug: true,
})For more on missing data, see Troubleshooting.