Setup Otel

Step 1: Install Dependencies

Start with the same package set used in Effect tracing examples.

Recommended baseline (adjust to runtime requirements):

bun add @effect/opentelemetry @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

Optional for early smoke tests:

• @opentelemetry/sdk-trace-web for browser targets
• @opentelemetry/sdk-metrics when metrics export is also requested

Step 2: Add Telemetry Environment Fields

Follow repository rules: do not read process.env directly in new code.

1. Add fields to src/env.ts (AppEnv).
2. Add corresponding entries to .env.example.
3. Use AppEnv values when building telemetry configuration.

Suggested fields:

• otelServiceName
• otelExporterOtlpEndpoint
• otelTracesSampler
• otelTracesSamplerArg

Step 3: Create A Telemetry Layer

Create a dedicated module such as src/telemetry.ts and keep setup at the boundary.

Console exporter variant (smoke-test friendly):

import { NodeSdk } from "@effect/opentelemetry";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";

export const NodeSdkLive = NodeSdk.layer(() => ({
  resource: {
    serviceName: "example-service",
  },
  spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
}));

OTLP exporter variant (backend integration):

import { NodeSdk } from "@effect/opentelemetry";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

export const NodeSdkLive = NodeSdk.layer(() => ({
  resource: {
    serviceName: "example-service",
  },
  spanProcessor: new BatchSpanProcessor(
    new OTLPTraceExporter({
      url: "http://localhost:4318/v1/traces",
    }),
  ),
}));

Step 4: Provide Telemetry At One Boundary

Merge/provide telemetry once at bootstrap. Do not scatter Effect.provide(...) calls throughout domain modules.

import { Effect, Layer } from "effect";

const RuntimeLayer = Layer.mergeAll(AppEnv.Default, NodeSdkLive, AppLayer);

const runnable = program.pipe(
  Effect.provide(RuntimeLayer),
);

Step 5: Validate End-To-End

1. Add one small span in application code with Effect.withSpan(...).
2. Trigger one request/job path.
3. Confirm spans arrive in the configured exporter/backend.
4. Confirm parent-child hierarchy and timing are plausible.

Local smoke check using console exporter:

• Run app and inspect emitted spans in terminal output.
• Verify span names and attributes match operation names.

Local visualization check using OTLP backend:

• Start a local OTLP-compatible stack (e.g. Grafana Tempo + Grafana).
• Send traces to OTLP endpoint.
• Query and inspect trace waterfall, durations, and nesting.

Step 6: Set Initial Sampling Policy

Recommended default:

• Development: near 100% sampling for debugging.
• Production: lower ratio with parent-based sampler.
• Incident windows: temporarily increase sampling for affected paths.

Handoff

• After setup is complete, use observability-tracing-otel for span architecture and instrumentation.
• Use observability-wide-events for wide structured event contracts.

Troubleshooting

• No spans exported:
  • Confirm exporter URL, protocol, and network reachability.
  • Confirm telemetry layer is provided at runtime bootstrap.
  • Confirm service executes code paths wrapped by spans.
• Spans exist but no hierarchy:
  • Check context propagation across async and concurrency boundaries.
  • Ensure nested effects are wrapped with child spans intentionally.
• High telemetry cost/noise:
  • Reduce span volume and tune sampling rate.
• Sensitive data leaks:
  • Remove raw payloads and secrets from attributes/log fields.
• Missing trace/log correlation:
  • Align span attributes and log keys (operation, IDs, status).
  • Ensure logging includes trace context where supported.

Verification Checklist

• Dependencies installed and locked.
• Telemetry env fields routed through AppEnv.
• Telemetry layer exists and is provided once at app boundary.
• At least one trace visible in console or backend.
• Trace hierarchy and durations look correct.
• Sensitive fields are not exported.

References

• https://effect.website/docs/observability/tracing/
• https://effect-ts.github.io/effect/docs/opentelemetry
• https://effect-ts.github.io/effect/effect/Tracer.ts.html
• https://opentelemetry.io/docs/specs/otel/trace/api/
• https://opentelemetry.io/docs/specs/semconv/
• https://opentelemetry.io/docs/languages/js/getting-started/nodejs/
• https://www.npmjs.com/package/@effect/opentelemetry