Everything you send to Monocle is stored under the same four levels. Knowing them makes setup, permissions, and billing much easier to reason about.
Organization billing, members, teams, integrations
└── Project one product or system, e.g. "Acme"
├── Environments production · staging · development
└── Services api · worker · web, each with its own DSNOrganization
The organization is your workspace. It owns the subscription, the members, the teams, and the integrations such as GitHub or Slack. Usage and billing are tracked at this level.
Project
A project groups everything that belongs to one product: its services, environments, issues, dashboards, uptime monitors, and status page. You can create as many projects as you want on every plan.
Access is granted per project through teams. See Access & Permissions.
Environment
Every project gets three environments when it is created: production, staging, and development. The environment selector at the top of the dashboard switches between them, and every page only shows data for the selected one.
Your app chooses its environment when it sends data. With the AdonisJS agent, this is the environment option, usually read from APP_ENV. Telemetry sent with any other environment name is rejected.
Service
A service is one deployable part of your project: an API, a background worker, a frontend. Traces crossing several services are stitched together, so you can follow a request from the browser to the database.
Create services from the Services page of your project. Services that send data without being registered, for example with a legacy API key, appear there as detected from telemetry and can be configured in one click.
DSN
A DSN (Data Source Name) is the connection string your SDK uses to send data to a service:
https://mk_live_xxxxxxxx@ingest.monocle.sh/00000000-0000-4000-8000-000000000001
└── secret key ──┘ └── ingest host ──┘ └────────── service ID ───────────┘Each service has its own DSN. Open the service, pick your SDK under SDK connection, and click Create DSN. You can copy it again from the same page later. Renaming a service does not change its DSN.
Projects created before DSNs used project-wide API keys. They keep working, but we recommend migrating to DSNs.
Telemetry signals
Monocle stores the three OpenTelemetry signals:
| Signal | What it is | Example |
|---|---|---|
| Traces | A tree of timed spans describing one request, job, or command | POST /orders → SQL query → Stripe call |
| Logs | Log lines, linked to the trace that produced them | Order 42 paid |
| Metrics | Numbers aggregated over time | CPU usage, heap size, event loop delay |
Exceptions are recorded on spans and grouped into issues, which you can resolve or link to GitHub and Linear issues.