Quickstart

This guide takes you from an empty account to your first trace. It uses AdonisJS, the backend framework Monocle supports today. Your coding agent can do the setup for you, or you can follow the steps by hand.

Create a project

Sign up at monocle.sh, create your organization, then your first project. Monocle creates the production, staging, and development environments for you. New organizations start with a 14-day trial with every feature included.

The Connect your app step comes next, with two tabs: With your agent and By hand.

Set up with your agent

The agent setup works with Claude Code, Cursor, and Codex. It reads your repository, creates the services that are missing in your project, and installs the SDKs.

1. In the With your agent tab, click Copy prompt and paste the prompt in your agent, from the root of your repository. You can also click Claude Code, Cursor, or Codex to open the prompt there.
2. If your agent is not connected to the Monocle MCP server yet, it adds the server with npx add-mcp https://api.monocle.sh/mcp and asks you to restart it. Approve the access in your browser.
3. The agent decides which services to create, one per app you deploy. An AdonisJS app that serves its own frontend with Edge or Inertia is one service. A frontend deployed on its own is another service.
4. If a service has a frontend, the agent asks you whether to identify signed-in users and whether to send console warnings and errors as logs.
5. For each service, the agent calls the setup_service tool. The tool creates the service, or reuses the one with the same name, and returns its DSN with the install steps for the AdonisJS agent and the browser SDK.
6. The agent checks that each service reaches Monocle. For AdonisJS, it starts your app once with MONOCLE_DEV=false and requests a route.

Monocle shows Listening for telemetry from a new service… and marks each service Connected as its first data arrives. The agent ends with a summary of its changes and the steps left to you, such as setting APP_ENV where you deploy.

To add services later, open Services and click Set up with your agent.

Set up by hand

1. Create a DSN

   In the By hand tab, click Create my DSN. To add a service later, open Services, click Add service, open the service, choose AdonisJS under SDK connection, and click Create DSN.

2. Install the agent

   In your AdonisJS app, run:

   node ace add @monocle.sh/adonisjs-agent

   Then paste the DSN in your .env:

   MONOCLE_DSN=https://mk_live_xxxxxxxx@ingest.monocle.sh/00000000-0000-4000-8000-000000000001
   APP_ENV=production

3. Send traffic

   Deploy your app, or start it with NODE_ENV=production locally, and make a few requests. Traces, logs, and exceptions appear in Monocle within seconds, in the environment matching APP_ENV.

Getting started checklist

Until your project is fully set up, the sidebar shows a Getting started card with your progress and the next step. Click it to see every step:

Each step has a button to do it, such as Set up with your agent or Copy install command. A project step stays done once it is reached. The MCP step is personal, and it is the only step shown to members without manager access to the project.

Catch your first exception has a Send a test error button. It sends a MonocleTestError exception from the service that sent server data most recently. The error becomes an issue within a few seconds, and it never triggers alerts. The same button appears on the exceptions page until the project receives its first exception.

To hide the checklist, click Hide this checklist at the bottom of the list. To bring it back, open the Help menu in the sidebar and click Getting started. The checklist disappears once every step is done.

Nothing showing up?

Check the Troubleshooting page. The most common causes are a missing MONOCLE_DSN in the deployed environment, otel.ts no longer being the first import, and an APP_ENV other than production, staging, or development.

Go further