Skip to main content
This guide covers how to add Monocle observability to your Effect application.

​
Prerequisites

  • Effect 3.21+
  • @effect/opentelemetry 0.63+
  • A Monocle account with an API key (not required for Monocle Studio)

​
Installation

npm install @monocle.sh/effect-agent
Peer dependencies: effect >= 3.21.0, @effect/opentelemetry >= 0.63.0

​
Setup

MonocleLayer returns an Effect Layer that you compose with the rest of your application layers. It configures OTLP exporters for traces, metrics, and logs.
src/main.ts
import { Effect, Layer } from "effect";
import { NodeRuntime } from "@effect/platform-node";
import { MonocleLayer } from "@monocle.sh/effect-agent";

const TracingLive = MonocleLayer({
  serviceName: "my-app",
  apiKey: process.env.MONOCLE_API_KEY,
  environment: "production",
});

const MainLive = Layer.mergeAll(DbLive, TracingLive);

program.pipe(Effect.provide(MainLive), NodeRuntime.runMain);
That’s it. All spans (Effect.withSpan), logs (Effect.log), and metrics are automatically exported to Monocle.

​
Configuration

OptionDescriptionRequired
serviceNameService name for identification in MonocleYes
apiKeyMonocle API key. Falls back to MONOCLE_API_KEY env varNo
environmentEnvironment name. Falls back to MONOCLE_ENVIRONMENT, NODE_ENV, then developmentNo
serviceVersionService version (e.g., git sha, semver). Defaults to 0.0.0No
endpointOTLP endpoint URL. Defaults to https://ingest.monocle.shNo
devEnable dev mode for Monocle Studio (see below)No
When no apiKey is provided (neither in config nor in MONOCLE_API_KEY) and dev mode is off, MonocleLayer returns an empty layer. No telemetry is sent.

​
Auto-Instrumentations

MonocleLayer handles the OTLP export and exception enrichment, but does not register OpenTelemetry auto-instrumentations (HTTP, PostgreSQL, Redis, etc.). These need to be set up separately. The simplest approach is the @opentelemetry/auto-instrumentations-node meta-package, which patches all supported libraries automatically: 
npm install @opentelemetry/auto-instrumentations-node
src/register.ts
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { registerInstrumentations } from "@opentelemetry/instrumentation";

registerInstrumentations({
  instrumentations: [getNodeAutoInstrumentations()],
});
The import order is critical.This file must be imported before any library it instruments (http, pg, redis, etc.). Import it as the very first line in your entrypoint:
src/main.ts
import "./register.js";

import { Effect, Layer } from "effect";
// ...
You can also install individual instrumentations if you prefer to keep dependencies minimal: 
npm install @opentelemetry/instrumentation-http @opentelemetry/instrumentation-pg
src/register.ts
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { PgInstrumentation } from "@opentelemetry/instrumentation-pg";
import { registerInstrumentations } from "@opentelemetry/instrumentation";

registerInstrumentations({
  instrumentations: [new HttpInstrumentation(), new PgInstrumentation()],
});

​
Dev Mode (Monocle Studio)

Enable dev: true to send telemetry to Monocle Studio running locally. Dev mode uses faster batch delays (100ms) and points to localhost:4200 by default. No API key required. 
const TracingLive = MonocleLayer({
  dev: true,
  serviceName: "my-app",
});
See the Monocle Studio docs to get started with local development.