observability

Effect provides built-in observability:

• Logging - Structured, leveled logging
• Metrics - Counters, gauges, histograms
• Tracing - Distributed tracing with spans

All three integrate seamlessly with Effect's execution model.

Basic Logging

```typescript

import { Effect } from "effect"

const program = Effect.gen(function* () {

yield* Effect.log("Starting process")

yield* Effect.logDebug("Debug information")

yield* Effect.logInfo("Processing item")

yield* Effect.logWarning("Resource running low")

yield* Effect.logError("Failed to connect")

yield* Effect.logFatal("Critical system failure")

})

```

Log Levels

```typescript

import { LogLevel, Logger } from "effect"

// Set minimum log level

const filtered = program.pipe(

Logger.withMinimumLogLevel(LogLevel.Info)

)

// Available levels (lowest to highest):

// Trace, Debug, Info, Warning, Error, Fatal, None

```

Structured Logging

```typescript

// Log with structured data

yield* Effect.log("User action").pipe(

Effect.annotateLogs({

userId: "123",

action: "login",

ip: "192.168.1.1"

})

)

// Annotations apply to all logs in scope

const program = Effect.gen(function* () {

yield* Effect.log("First log") // Has userId annotation

yield* Effect.log("Second log") // Has userId annotation

}).pipe(

Effect.annotateLogs({ userId: "123" })

)

```

Log Spans

```typescript

// Add timing/context spans

const program = Effect.gen(function* () {

yield* Effect.log("Processing")

yield* processItems()

yield* Effect.log("Complete")

}).pipe(

Effect.withLogSpan("request-handler")

)

// Logs include: [request-handler 45ms] Processing

```

Custom Logger

```typescript

import { Logger } from "effect"

const JsonLogger = Logger.make(({ logLevel, message, annotations, date }) => {

console.log(JSON.stringify({

level: logLevel.label,

message: String(message),

timestamp: date.toISOString(),

...annotations

}))

})

const program = Effect.gen(function* () {

yield* Effect.log("Hello")

}).pipe(

Effect.provide(Logger.replace(Logger.defaultLogger, JsonLogger))

)

```

Counter - Track Occurrences

```typescript

import { Metric } from "effect"

const requestCount = Metric.counter("http_requests_total", {

description: "Total HTTP requests"

})

const program = Effect.gen(function* () {

yield* Metric.increment(requestCount)

yield* Metric.incrementBy(requestCount, 5)

})

const tracked = handleRequest.pipe(

Metric.trackAll(requestCount)

)

```

Gauge - Track Current Value

```typescript

const activeConnections = Metric.gauge("active_connections", {

description: "Current active connections"

})

const program = Effect.gen(function* () {

yield* Metric.set(activeConnections, 10)

yield* Metric.incrementBy(activeConnections, 1)

yield* Metric.decrementBy(activeConnections, 1)

})

```

Histogram - Track Distributions

```typescript

const requestDuration = Metric.histogram("http_request_duration_ms", {

description: "Request duration in milliseconds",

boundaries: [10, 50, 100, 250, 500, 1000]

})

yield* Metric.observe(requestDuration, 125)

const tracked = handleRequest.pipe(

Metric.trackDuration(requestDuration)

)

```

Summary - Statistical Summary

```typescript

const responseSizes = Metric.summary("response_size_bytes", {

description: "Response payload sizes",

maxAge: "1 minute",

maxSize: 100,

quantiles: [0.5, 0.9, 0.99]

})

yield* Metric.observe(responseSizes, 1024)

```

Frequency - Count by Tag

```typescript

const statusCodes = Metric.frequency("http_status_codes")

yield* Metric.observe(statusCodes, "200")

yield* Metric.observe(statusCodes, "404")

yield* Metric.observe(statusCodes, "500")

```

Tagged Metrics

```typescript

const requestCount = Metric.counter("requests").pipe(

Metric.tagged("service", "api"),

Metric.tagged("version", "v1")

)

// Dynamic tags

const taggedCount = Metric.counter("requests").pipe(

Metric.taggedWithLabels(["method", "endpoint"])

)

yield* Metric.increment(taggedCount).pipe(

Metric.taggedWithLabels(["GET", "/users"])

)

```

Reading Metrics

```typescript

const program = Effect.gen(function* () {

yield* Metric.increment(requestCount)

yield* Metric.increment(requestCount)

const snapshot = yield* Metric.value(requestCount)

// snapshot.count === 2

})

```

Creating Spans

```typescript

import { Effect } from "effect"

const traced = handleRequest.pipe(

Effect.withSpan("handle-request")

)

const traced = handleRequest.pipe(

Effect.withSpan("handle-request", {

attributes: {

"http.method": "GET",

"http.url": "/api/users"

}

})

)

```

Nested Spans

```typescript

const program = Effect.gen(function* () {

yield* fetchUser(id).pipe(Effect.withSpan("fetch-user"))

yield* processData(data).pipe(Effect.withSpan("process-data"))

yield* saveResult(result).pipe(Effect.withSpan("save-result"))

}).pipe(

Effect.withSpan("main-operation")

)

// Creates: main-operation

// ├── fetch-user

// ├── process-data

// └── save-result

```

Adding Span Attributes

```typescript

import { Tracer } from "effect"

const program = Effect.gen(function* () {

yield* Effect.annotateCurrentSpan("user.id", userId)

yield* Effect.annotateCurrentSpan("event", "user_validated")

const result = yield* processUser(userId)

yield* Effect.annotateCurrentSpan("result.status", result.status)

})

```

Span Status

```typescript

const program = Effect.gen(function* () {

try {

return yield* riskyOperation

} catch (error) {

yield* Effect.setSpanStatus({

code: "error",

message: error.message

})

return yield* Effect.fail(error)

}

}).pipe(Effect.withSpan("risky-operation"))

```

Custom Tracer

```typescript

import { Tracer } from "effect"

const ConsoleTracer = Tracer.make({

span: (name, parent, context, links, startTime) => ({

attribute: (key, value) => console.log([${name}] ${key}=${value}),

end: (endTime, exit) => console.log([${name}] ended),

event: (name, startTime, attributes) => console.log([${name}] event: ${name}),

status: (status) => console.log([${name}] status: ${status.code})

})

})

const program = myEffect.pipe(

Effect.provide(Tracer.layer(ConsoleTracer))

)

```

```typescript

import { NodeSdk } from "@effect/opentelemetry"

import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"

const TracingLive = NodeSdk.layer(() => ({

resource: { serviceName: "my-service" },

spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter())

}))

const program = myEffect.pipe(

Effect.provide(TracingLive)

)

```

```typescript

const handleRequest = (req: Request) =>

Effect.gen(function* () {

yield* Effect.log("Request received").pipe(

Effect.annotateLogs({ path: req.path, method: req.method })

)

yield* Metric.increment(requestCount)

const result = yield* processRequest(req)

yield* Effect.annotateCurrentSpan("response.status", result.status)

yield* Metric.observe(requestDuration, result.duration)

return result

}).pipe(

Effect.withSpan("handle-request", {

attributes: {

"http.method": req.method,

"http.url": req.path

}

})

)

```

1. Use structured logging - Add context via annotations
2. Name spans descriptively - Use verb-noun format
3. Add meaningful attributes - Enable debugging/analysis
4. Track key metrics - Request count, latency, errors
5. Use appropriate log levels - Debug in dev, Info in prod

For comprehensive observability documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Built-in Logging" for logging APIs
• "Metrics" for metric types
• "Tracing" for distributed tracing