Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt

Use this file to discover all available pages before exploring further.

The Effect agent is experimental and under active development. APIs may change between releases.
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()],
});

​
User Context

To associate telemetry data with authenticated users, use Monocle.setUser(). This lets you filter traces and exceptions by user in the dashboard. 
import { Effect } from "effect";
import { Monocle } from "@monocle.sh/effect-agent";

const program = Effect.gen(function* () {
  yield* Monocle.setUser({
    id: "123",
    email: "john@example.com",
    name: "John Doe",
  });

  // ... rest of the effect
}).pipe(Effect.withSpan("handle-request"));
The name field takes priority in the Monocle UI, falling back to email, then id. You can also pass custom attributes: 
yield* Monocle.setUser({
  id: user.id,
  email: user.email,
  name: user.fullName,
  plan: "enterprise",
  role: "admin",
});
Custom attributes are stored as user.<key> on the span. Monocle.setUser is a no-op when called outside of a span. It will never throw.
Do not include sensitive data (passwords, tokens, API keys) in user attributes. These values are sent to Monocle and will be visible in trace viewers.

​
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.