Deployments

Monocle records a deployment each time a new version of a service starts running in an environment. Detection needs no setup as soon as your telemetry carries a version. You can also declare deployments from your CI or from GitHub to add their exact time, status, author, and CI run.

Detected deployments

Monocle reads the service.version resource attribute on the entry spans of each service: root spans, SERVER and CONSUMER spans, and spans with a remote parent. Every request and job starts with one of them. When a new version shows up in an environment, Monocle records a detected deployment at the time it first saw that version.

A detected time is a first observation. It is not the moment your deploy finished. To record that moment, declare the deployment.

Detection has limits:

• The first version Monocle sees for a service is its baseline. It doesn't create a deployment.
• Several versions running at the same time, during a rolling deploy or a canary, don't create extra deployments.
• A version that takes most of the traffic back after another version replaced it is a new deployment. A rollback from B to A is detected this way. A few requests from an old version, such as a browser tab opened before the deploy, don't create a deployment. A rollback of a service with very little traffic is visible only if you declare it.
• Detection follows traffic. A service that receives no requests at night is seen when traffic resumes.
• A service that sends only logs is not detected. Declare its deployments instead.
• More than 20 new versions of one service in one hour pause detection for that service. See Detection paused.

How Monocle reads the version

The Monocle agents for AdonisJS and Effect set service.version for you. They use the first value they find:

1. The serviceVersion option of your configuration.
2. The MONOCLE_VERSION environment variable.
3. The APP_VERSION environment variable.
4. The revision exposed by your platform: Vercel, Render, Railway, Heroku, Coolify (SOURCE_COMMIT), Dokku (GIT_REV), or Cloud Run (K_REVISION).
5. The commit SHA exposed by a supported CI provider, such as GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, or Buildkite.
6. The current commit of the local .git directory. The agents read the files directly and don't run git.

The agents skip empty values and the placeholders 0.0.0, 0.0.1, 1.0.0, unknown, dev, and latest. Monocle ignores the same placeholders when an older SDK sends them. Without a usable version, the agents send no service.version.

To pin a version, set MONOCLE_VERSION or APP_VERSION. No config line is needed. The AdonisJS configurator no longer generates or requires APP_NAME or APP_VERSION. Existing apps need no change. An old serviceVersion: env.get('APP_VERSION') line still works, and an APP_VERSION=0.0.1 placeholder is skipped.

The service name in Monocle comes from the service attached to the DSN. In Studio or without a DSN, the AdonisJS agent uses serviceName, then OTEL_SERVICE_NAME, then APP_NAME, then the app's package.json name without its npm scope, or unknown_service if none is available.

The agents also send the commit in vcs.ref.head.revision, the repository in vcs.repository.url.full, and the platform deployment ID in deployment.id when they find them. monocle.service.version.source names the source of the version, such as platform:railway or git.

For browser apps, add the Vite plugin. With another OpenTelemetry SDK, set service.version yourself. See resource attributes.

Declare deployments

A declaration adds what detection can't know: when the deploy started and finished, its status, who deployed, and a link to the CI run. Declare deployments in one of three ways:

• Run monocle deploy at the end of your CI job.
• Call the Deployments API.
• Connect GitHub Deployments. This also covers Vercel, Render, and Railway.

A declaration and a detected deployment of the same version, in the same environment, merge when they are less than 60 minutes apart. The order doesn't matter. The merged deployment shows as declared, keeps its first observed time, and sits on charts at the declared time.

Monocle finds the version of a declaration by its version, or by its commit SHA. A service versioned in semver that sends vcs.ref.head.revision matches a declaration that only has the SHA.

Create a deploy key

The CLI and the API authenticate with a deploy key. A deploy key can only declare deployments. It can't send telemetry or upload source maps.

1. Open Project settings, then Deploy keys.
2. Click Create deploy key and name it after the CI that uses it.
3. Copy the key. Monocle shows it only once.
4. Store it as the MONOCLE_API_KEY secret of your CI.

Project API keys created before deploy keys also work. DSNs and browser keys are refused, because they can be public.

GitHub Deployments

GitHub creates a deployment when a GitHub Actions job targets an environment. Vercel, Render, and Railway create them too for the repositories they deploy. Monocle records these deployments as declared, without any CI step.

1. Connect the GitHub integration and link the repository to your project.
2. Accept the Deployments: read permission of the Monocle GitHub App, from its installation settings on GitHub. An owner of the GitHub account accepts it once.
3. Deploy. Each GitHub environment appears in Project settings, under GitHub deployments, after its first deployment status.
4. Choose the Monocle environment and the service of each GitHub environment.

A GitHub environment maps itself when the project has one service and an environment with the same slug, ignoring case. It shows as Auto. Monocle ignores the deployments of a GitHub environment that is Not mapped.

What you see in Monocle

• Chart markers. Deployments appear under the time axis of the charts on the Overview, Requests, endpoint, Exceptions, Issues, Logs, and Traces pages. A hollow marker is detected, a filled marker is declared. Click a marker to open the deployment. The Deployments toggle in the chart header hides the markers and remembers your choice. Failed and canceled deployments have no marker.
• Deployments page. Running now lists, for each service, the versions seen over the last 15 minutes, their share of HTTP requests when several run at once, and the last deployment. The history below lists every deployment with a Detected or Declared badge. Filter it by service, source, version, or commit.
• Deployment panel. The timeline, the commit and CI run, the versions observed around the deployment, and links to the traces, logs, and issues of that version.
• Version badges. Exception occurrences, issues, logs, and spans show their version. Click the badge to open the deployment of that version, or the explorer filtered on it.
• Overview. The Recent deployments card lists the latest deployments of the environment.

Ask your AI assistant

The Monocle MCP server has two deployment tools. list_deployments lists the deployments of the environment, with filters on services, source, and version. get_deployment returns one deployment, its timeline, the previous deployment, and the versions observed around it. Both tools say whether a deployment is detected or declared, so your assistant doesn't present a first observation as a deploy time.

Troubleshooting

When a service has no usable version, Running now shows the reason next to it.

ARG GIT_SHA
ENV MONOCLE_VERSION=$GIT_SHA