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

# Effect

> Install and configure the Monocle agent in your Effect application

<Warning>
  The Effect agent is experimental and under active development. APIs may change between releases.
</Warning>

This guide covers how to add Monocle observability to your [Effect](https://effect.website) application.

## Prerequisites

* Effect 3.21+
* `@effect/opentelemetry` 0.63+
* A Monocle account with an API key (not required for [Monocle Studio](/studio/overview))

## Installation

```bash theme={"theme":"vesper"}
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.

```typescript title="src/main.ts" theme={"theme":"vesper"}
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:

```bash theme={"theme":"vesper"}
npm install @opentelemetry/auto-instrumentations-node
```

```typescript title="src/register.ts" theme={"theme":"vesper"}
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { registerInstrumentations } from "@opentelemetry/instrumentation";

registerInstrumentations({
  instrumentations: [getNodeAutoInstrumentations()],
});
```

<Warning>
  **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:

  ```typescript title="src/main.ts" theme={"theme":"vesper"}
  import "./register.js";

  import { Effect, Layer } from "effect";
  // ...
  ```
</Warning>

You can also install individual instrumentations if you prefer to keep dependencies minimal:

```bash theme={"theme":"vesper"}
npm install @opentelemetry/instrumentation-http @opentelemetry/instrumentation-pg
```

```typescript title="src/register.ts" theme={"theme":"vesper"}
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.

```typescript theme={"theme":"vesper"}
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:

```typescript theme={"theme":"vesper"}
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.

<Warning>
  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.
</Warning>

## Dev Mode (Monocle Studio)

Enable `dev: true` to send telemetry to [Monocle Studio](/studio/overview) running locally. Dev mode uses faster batch delays (100ms) and points to `localhost:4200` by default. No API key required.

```typescript theme={"theme":"vesper"}
const TracingLive = MonocleLayer({
  dev: true,
  serviceName: "my-app",
});
```

See the [Monocle Studio docs](/studio/overview) to get started with local development.