effect(middleware-otel): add OtelTracerLayer bridge alongside legacy withTracing

Add @effect/opentelemetry integration via OtelTracerLayer({ tracerProvider,
resource }) — a thin bridge that lifts a consumer-supplied OTel
TracerProvider into an Effect Layer providing OtelTracer / OtelTracerProvider
/ Resource. Effect-shape consumers compose it into ARCPRuntimeLayer so
Effect.withSpan calls inside the runtime emit through the same provider
that withTracing (Transport-level §11 propagation) already uses. The
published 0.1.0 withTracing API is unchanged.

NodeSdk.layer intentionally not exposed: choosing SpanProcessor / exporter
/ propagator belongs to the consumer's observability stack, and the issue
forbids a new dependency on @opentelemetry/sdk-node.

First test infra in this package (vitest.config.ts + test/). Three tests:
layer composability smoke, span-export with parent/child shape through
BasicTracerProvider + InMemorySpanExporter, and a withTracing re-export
regression guard.

Closes #49
Closes #28

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Nick Ficano

packages/middleware/otel/package.json

@@ -44,13 +44,17 @@
   "peerDependencies": {
     "@arcp/core": "workspace:^",
     "@effect/opentelemetry": "^0.63.0",
-    "@opentelemetry/api": "^1.9.0"
+    "@opentelemetry/api": "^1.9.0",
+    "effect": "^3.21.2"
   },
   "devDependencies": {
     "@arcp/core": "workspace:*",
     "@effect/opentelemetry": "^0.63.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@types/node": "^22.7.5",
+    "effect": "^3.21.2",
     "typescript": "^5.6.2",
     "vitest": "^2.1.2"
   }

packages/middleware/otel/src/index.ts

@@ -41,6 +41,10 @@ import {
 import type { WithTracingOptions } from "./types.js";
 
 export type { WithTracingOptions } from "./types.js";
+export {
+  OtelTracerLayer,
+  type OtelTracerLayerOptions,
+} from "./otel-effect.js";
 
 // Per ARCP §15 (IANA / extension namespace), all envelope extensions must be
 // in the `x-vendor.<vendor>.<name>` namespace. The OTel propagation carrier

packages/middleware/otel/src/otel-effect.ts

@@ -0,0 +1,133 @@
+/**
+ * Effect-shape integration for `@arcp/middleware-otel`.
+ *
+ * Slice #49 of the Effect migration. This module sits alongside the legacy
+ * Transport-level {@link withTracing} wrapper (preserved unchanged in
+ * `./index.ts`) and exposes a small, compositional bridge from
+ * `@effect/opentelemetry` into an ARCP runtime built with
+ * {@link makeARCPServerRuntime} / {@link ARCPRuntimeLayer}.
+ *
+ * Scope of this module
+ * --------------------
+ * Two distinct concerns are at play:
+ *
+ *   1. **Wire-level propagation.** Stamping the W3C `traceparent` carrier
+ *      into `envelope.extensions["x-vendor.opentelemetry.tracecontext"]` so
+ *      that ARCP §11 spans link across hops. That contract is owned by
+ *      {@link withTracing} (Transport wrapper) and is unchanged.
+ *
+ *   2. **Effect-workflow tracing.** Letting spans opened by `Effect.withSpan`
+ *      and `Effect.useSpan` inside an ARCP runtime appear in the same OTel
+ *      trace as the spans emitted by (1). That is what this module adds.
+ *
+ * Why we don't expose a `NodeSdk.layer` here
+ * ------------------------------------------
+ * `@effect/opentelemetry`'s `NodeSdk.layer` constructs a full Node tracer
+ * provider from `@opentelemetry/sdk-trace-node`, `@opentelemetry/resources`,
+ * and a user-supplied `SpanProcessor`. That decision (which exporter, which
+ * batching strategy, which propagator, etc.) belongs to the consumer's
+ * observability stack, not to a middleware package. Forcing a particular
+ * SDK shape would also force a hard dependency on `@opentelemetry/sdk-node`
+ * — which the issue explicitly forbids ("No new dependency on
+ * `@opentelemetry/sdk-node`; consumer brings their own SDK; we only bridge").
+ *
+ * Instead we expose {@link OtelTracerLayer}, a thin bridge that takes an
+ * already-constructed OTel `TracerProvider` (whatever the consumer wired up
+ * — `NodeTracerProvider`, `WebTracerProvider`, `@vercel/otel`, a no-op
+ * provider for tests, or `trace.getTracerProvider()` after global registration)
+ * and lifts it into an Effect {@link Layer} that satisfies the
+ * `OtelTracer.OtelTracer` and `OtelTracer.OtelTracerProvider` requirements
+ * for any downstream effect that calls `Effect.withSpan(...)`.
+ *
+ * Usage
+ * -----
+ * ```ts
+ * import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+ * import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+ * import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+ * import { Layer } from "effect";
+ * import { ARCPRuntimeLayer } from "@arcp/runtime";
+ * import { OtelTracerLayer } from "@arcp/middleware-otel";
+ *
+ * const provider = new NodeTracerProvider();
+ * provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
+ * provider.register(); // also makes withTracing happy for §11 propagation
+ *
+ * const MainLayer = Layer.provideMerge(
+ *   ARCPRuntimeLayer(serverOptions),
+ *   OtelTracerLayer({
+ *     tracerProvider: provider,
+ *     resource: { serviceName: "arcp-runtime" },
+ *   }),
+ * );
+ * ```
+ *
+ * The legacy {@link withTracing} wrapper continues to work side-by-side: it
+ * pulls the active OTel context from `@opentelemetry/api` (which the global
+ * provider above satisfies), so a single registered provider feeds both the
+ * Transport-level `arcp.send` / `arcp.recv` spans and the Effect-workflow
+ * spans opened inside the runtime.
+ */
+import * as OtelResource from "@effect/opentelemetry/Resource";
+import * as OtelTracer from "@effect/opentelemetry/Tracer";
+import type * as OtelApi from "@opentelemetry/api";
+import { Layer } from "effect";
+
+/**
+ * Configuration for {@link OtelTracerLayer}.
+ *
+ * Both fields are required: the bridge needs a real OTel `TracerProvider`
+ * to delegate span creation to, and a `resource` (service name / version /
+ * attributes) so that `provider.getTracer(serviceName, serviceVersion)`
+ * resolves to a stable tracer per the OTel spec.
+ */
+export interface OtelTracerLayerOptions {
+  /**
+   * The OpenTelemetry `TracerProvider` to bridge into Effect. Typically the
+   * same provider passed to `provider.register()` so that the legacy
+   * {@link withTracing} Transport wrapper (which reads from the global API)
+   * and Effect-workflow spans share a single export pipeline.
+   */
+  readonly tracerProvider: OtelApi.TracerProvider;
+
+  /**
+   * Resource attributes used to name the bridged tracer. `serviceName` is
+   * required; `serviceVersion` and `attributes` are optional and forwarded
+   * to `@effect/opentelemetry`'s `Resource.layer` unchanged.
+   */
+  readonly resource: {
+    readonly serviceName: string;
+    readonly serviceVersion?: string;
+    readonly attributes?: OtelApi.Attributes;
+  };
+}
+
+/**
+ * Build an Effect {@link Layer} that bridges Effect's tracer to a
+ * consumer-supplied OTel `TracerProvider`.
+ *
+ * The resulting layer eliminates the `OtelTracer.OtelTracer`,
+ * `OtelTracer.OtelTracerProvider`, and `OtelResource.Resource`
+ * requirements for downstream effects, and replaces the default
+ * Effect tracer with one that emits OTel spans through the supplied
+ * provider. Compose it via `Layer.provideMerge` into an
+ * `ARCPRuntimeLayer`-built program; no other plumbing is required.
+ *
+ * This is purely an Effect-shape addition. The Transport-level
+ * `withTracing` wrapper exported from `./index.ts` is unchanged and
+ * continues to be the right tool for §11 wire propagation.
+ */
+export const OtelTracerLayer = (
+  options: OtelTracerLayerOptions,
+): Layer.Layer<never> => {
+  const providerLayer = Layer.succeed(
+    OtelTracer.OtelTracerProvider,
+    options.tracerProvider,
+  );
+  const resourceLayer = OtelResource.layer(options.resource);
+  const tracerLayer = OtelTracer.layer;
+  return Layer.provide(
+    tracerLayer,
+    Layer.merge(providerLayer, resourceLayer),
+  );
+};

packages/middleware/otel/test/otel-effect.test.ts

@@ -0,0 +1,118 @@
+// Behavior + smoke coverage for `otel-effect.ts`. These tests stay scoped
+// to the middleware package by driving `OtelTracerLayer` against an
+// in-memory `BasicTracerProvider` + `InMemorySpanExporter` from
+// `@opentelemetry/sdk-trace-base`. We assert:
+//
+//   1) `OtelTracerLayer` is a valid Effect Layer with no leftover
+//      requirements (smoke test — proves the bridge can be composed into
+//      `ARCPRuntimeLayer` without further plumbing).
+//   2) Spans opened via `Effect.withSpan` inside the resulting program are
+//      exported through the consumer-supplied `TracerProvider`, with the
+//      configured `serviceName` recorded on the tracer and the expected
+//      parent/child structure preserved (the §11 acceptance scenario,
+//      reduced to a single Effect-shape workflow).
+//   3) The legacy `withTracing` re-export still works (regression guard
+//      for the published 0.1.0 surface — no behavior change in slice #49).
+
+import {
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+  BasicTracerProvider,
+} from "@opentelemetry/sdk-trace-base";
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+
+import { OtelTracerLayer, withTracing } from "../src/index.js";
+
+describe("OtelTracerLayer", () => {
+  it("composes into a runnable program with no leftover requirements", async () => {
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+
+    const layer = OtelTracerLayer({
+      tracerProvider: provider,
+      resource: { serviceName: "arcp-runtime-test" },
+    });
+
+    // If the layer leaves any requirements the type-system would already
+    // have failed; this provideLayer call is the runtime smoke-test.
+    const program = Effect.succeed("ok").pipe(
+      Effect.withSpan("smoke"),
+      Effect.provide(layer),
+    );
+
+    const result = await Effect.runPromise(program);
+    expect(result).toBe("ok");
+
+    await provider.shutdown();
+  });
+
+  it("exports Effect spans through the supplied OTel TracerProvider with the configured serviceName", async () => {
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+      spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+
+    const layer = OtelTracerLayer({
+      tracerProvider: provider,
+      resource: {
+        serviceName: "arcp-runtime",
+        serviceVersion: "0.1.0",
+      },
+    });
+
+    // session.handshake → job.submit → handler (per #49 acceptance shape,
+    // reduced to a single Effect workflow — wire-level propagation across
+    // session boundaries is covered by `withTracing` and is out of scope
+    // for this Effect-shape bridge).
+    const program = Effect.gen(function* () {
+      yield* Effect.succeed(undefined).pipe(
+        Effect.withSpan("job.submit"),
+      );
+      yield* Effect.succeed(undefined).pipe(Effect.withSpan("handler"));
+    }).pipe(Effect.withSpan("session.handshake"), Effect.provide(layer));
+
+    await Effect.runPromise(program);
+
+    // SimpleSpanProcessor flushes per-span synchronously, but force a
+    // flush to be defensive against batching changes upstream.
+    await provider.forceFlush();
+    const spans = exporter.getFinishedSpans();
+
+    const names = spans.map((s) => s.name).sort();
+    expect(names).toEqual(["handler", "job.submit", "session.handshake"]);
+
+    // Tracer name = serviceName (per @effect/opentelemetry's layerTracer);
+    // assert the bridge actually delegated to provider.getTracer(...).
+    for (const s of spans) {
+      expect(s.instrumentationScope.name).toBe("arcp-runtime");
+      expect(s.instrumentationScope.version).toBe("0.1.0");
+    }
+
+    // Verify the parent/child structure: session.handshake is the root,
+    // and both job.submit and handler hang off it.
+    const byName = new Map(spans.map((s) => [s.name, s]));
+    const root = byName.get("session.handshake");
+    const submit = byName.get("job.submit");
+    const handler = byName.get("handler");
+    expect(root?.parentSpanContext).toBeUndefined();
+    expect(submit?.parentSpanContext?.spanId).toBe(
+      root?.spanContext().spanId,
+    );
+    expect(handler?.parentSpanContext?.spanId).toBe(
+      root?.spanContext().spanId,
+    );
+
+    await provider.shutdown();
+  });
+
+  it("re-exports the legacy withTracing wrapper unchanged", () => {
+    // Regression guard: slice #49 must not alter the published 0.1.0
+    // surface. We only assert the export is a callable function — its
+    // behavior is exercised by consumers (no tests previously existed
+    // in this package).
+    expect(typeof withTracing).toBe("function");
+  });
+});

packages/middleware/otel/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+    environment: "node",
+    pool: "threads",
+    testTimeout: 10_000,
+    hookTimeout: 10_000,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html", "lcov"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/index.ts", "src/**/*.d.ts"],
+    },
+  },
+});