Most setup problems come down to one of the causes below. Go through them in order.
Check what the agent records
Before looking at Monocle, confirm the agent is producing spans. Enable debug to print every span to your console:
export default defineConfig({
// ...
debug: true,
})If no spans are printed when you make a request, the problem is on the application side. If spans are printed but nothing shows up in Monocle, the problem is the connection.
No data at all
MONOCLE_DSN is not set in the deployed environment
Without a DSN, the agent disables itself silently. Make sure the variable is set where the app
actually runs (your hosting provider, Docker image, or Kubernetes secret), not only in your
local .env.
The app runs in dev mode
The generated config sets dev: process.env.NODE_ENV === 'development'. In dev mode, telemetry
goes to Monocle Studio on localhost:4200 and the DSN is ignored. Make sure
NODE_ENV=production in your deployed environment.
The app runs with NODE_ENV=test
Telemetry is disabled automatically when NODE_ENV=test, so test suites never send data.
otel.ts is not the first import
OpenTelemetry must load before any other module so it can patch http, pg, redis, and the
rest. Check that import '../otel.js' is the very first line of bin/server.ts, and of
bin/console.ts for Ace commands. Without it, the agent starts but records almost nothing.
The agent is too old for DSNs
DSNs require a recent version of @monocle.sh/adonisjs-agent. With an older version,
MONOCLE_DSN is ignored and telemetry stays disabled. Upgrade the agent, or keep using your
previous API key until you can.
The app logs a flush error or a 401
Monocle answers 401 Unauthorized without details when it rejects data. On shutdown, the agent may log [monocle] Failed to flush telemetry during shutdown. Check, in this order:
| Cause | How to fix it |
|---|---|
| Unknown environment | APP_ENV must be exactly production, staging, or development. Values like prod or local are rejected. |
| Invalid or revoked DSN | Copy the DSN again from the service page. Deleting a service revokes its DSN. |
| Trial ended | Ingestion stops when the trial ends without a subscription. Pick a plan in Organization Settings → Billing. |
| DSN copied partially | A malformed DSN makes the agent throw at boot with Invalid Monocle DSN. Copy the full value again. |
Monocle caches connection checks for up to five minutes. After fixing a DSN, an environment, or your billing, data can take a few minutes to start flowing again.
Data shows up in the wrong place
Wrong environment
The environment comes from the environment option of config/monocle.ts, usually APP_ENV.
It falls back to NODE_ENV, then development. Use the environment selector at the top of the
dashboard to check the other environments.
Wrong or duplicated service
With a DSN, data always goes to the service the DSN belongs to, whatever your app calls itself.
With a legacy API key, the service name comes from serviceName, then OTEL_SERVICE_NAME, then
APP_NAME, then the app's package.json name without its npm scope, and appears as detected
from telemetry. Migrate to a DSN to pin it.
Some requests or commands are missing
Health check routes (/health, /ready, /metrics…), static files, and OPTIONS requests are
ignored by default. Scaffolding commands (make:*) and long-running workers (queue:work) are
not traced either. See HTTP and Mail, Queue &
CLI to change this.
Only a share of traces is recorded
Check samplingRatio and the sampling hook in config/monocle.ts. See Job
Sampling.
Still stuck?
Email us at support@monocle.sh with your agent version, your config/monocle.ts (without the DSN), and what you see in the console with debug: true.