Effect

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

Option	Description	Required
`serviceName`	Service name for identification in Monocle	Yes
`apiKey`	Monocle API key. Falls back to `MONOCLE_API_KEY` env var	No
`environment`	Environment name. Falls back to `MONOCLE_ENVIRONMENT`, `NODE_ENV`, then `development`	No
`serviceVersion`	Service version (e.g., git sha, semver). Defaults to `0.0.0`	No
`endpoint`	OTLP endpoint URL. Defaults to `https://ingest.monocle.sh`	No
`dev`	Enable 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.

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Other

Prerequisites

Installation

Setup

Configuration

Auto-Instrumentations

User Context

Dev Mode (Monocle Studio)

​Prerequisites

​Installation

​Setup

​Configuration

​Auto-Instrumentations

​User Context

​Dev Mode (Monocle Studio)

Prerequisites

Installation

Setup

Configuration

Auto-Instrumentations

User Context

Dev Mode (Monocle Studio)