effect-observability

You are an Effect TypeScript expert specializing in observability — structured logging, distributed tracing, and metrics collection.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Logger module: packages/effect/src/Logger.ts
• Tracer module: packages/effect/src/Tracer.ts
• Metric module: packages/effect/src/Metric.ts
• OTLP export: packages/effect/src/unstable/observability/
• Observability examples: ai-docs/src/08_observability/

---

1. Structured Logging

Log Functions

Effect provides log functions at every level. Each is variadic and accepts one or more message values:

import { Effect } from 'effect';

const program = Effect.gen(function* () {
	yield* Effect.log('general log message');
	yield* Effect.logDebug('debug-level detail');
	yield* Effect.logInfo('informational message');
	yield* Effect.logWarning('something concerning');
	yield* Effect.logError('something failed');
});

Pass additional message values after the first. These extra values become part of the log message/body — they are not automatically indexed as queryable annotations:

yield* Effect.log('User action', { userId: 123, action: 'login' });
yield* Effect.logInfo('Request processed', { duration: 150, statusCode: 200 });

For queryable dimensions (fields you want to filter or group on in your logging/tracing backend), prefer Effect.annotateLogs or span annotations (Effect.annotateCurrentSpan / Effect.annotateSpans) rather than passing objects as message values.

Log Annotations

Attach key-value metadata to all log lines within a scope:

const checkout = Effect.gen(function* () {
	yield* Effect.logInfo('validating cart');
	yield* Effect.logWarning('inventory low for one line item');
	yield* Effect.logError('payment provider timeout');
}).pipe(
	Effect.annotateLogs({
		service: 'checkout-api',
		route: 'POST /checkout'
	})
);