Observability

Observability in Effect

Overview

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.

Logging

Basic Logging

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

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

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

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

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))
)

Metrics

Counter - Track Occurrences

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

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

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

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

const statusCodes = Metric.frequency("http_status_codes")

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

Tagged Metrics

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

const program = Effect.gen(function* () {
  yield* Metric.increment(requestCount)
  yield* Metric.increment(requestCount)

  const snapshot = yield* Metric.value(requestCount)
  // snapshot.count === 2
})

Tracing

Creating Spans

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

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

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

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

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))
)

OpenTelemetry Integration

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)
)

Combining Observability

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
      }
    })
  )

Best Practices

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

Additional Resources

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