autotel-effect 4.0.1 → 5.0.0

package/README.md

@@ -73,9 +73,42 @@ In a server, merge the layer where you assemble services:
 appLayer.pipe(Layer.provideMerge(layer({ serviceName: 'my-api' })));
 ```
 
-HTTP spans from autotel's `node:http` instrumentation become parents of domain spans from `Effect.withSpan`.
+### 3. Join the surrounding trace with `withAutotel`
 
-### 3. Logs come with it
+Effect takes a span's parent from its own `Tracer.ParentSpan`, not from the
+ambient OpenTelemetry context, and marks a span as a root when it has none. So a
+bare `Effect.runPromise` inside an instrumented HTTP handler opens a **new
+trace** — the handler's span and the Effect's span end up in two separate
+traces, with nothing to say they belong together. `withAutotel` hands Effect the
+active autotel span as the parent:
+
+```typescript
+import { withAutotel } from 'autotel-effect';
+
+app.get('/api/todos', async () => {
+  // inside autotel's `node:http` span
+  return Effect.runPromise(withAutotel(program));
+});
+```
+
+It reads the active span when the effect **runs**, so a program assembled once
+at startup still joins the request it is run inside. That is also why this is
+not part of `layer()`: a layer is built once for the whole application, long
+before any request span exists.
+
+With it, HTTP spans from autotel's `node:http` instrumentation become parents of
+domain spans from `Effect.withSpan`.
+
+### Don't reach for `trace()` here
+
+autotel's `trace(name, fn)` wraps a function and ends its span when that
+function **returns**. A function that returns an `Effect` returns a description
+of work, not the work, so the span closes before anything runs and measures the
+construction rather than the effect. Use Effect's own instrumentation instead —
+`Effect.fn('name')(...)` or `Effect.withSpan('name')` — which is what `layer()`
+routes through autotel.
+
+### 4. Logs come with it
 
 One `layer()` call bridges both signals. `Effect.log*` becomes an OpenTelemetry
 **log record** (so it reaches any OTLP log backend, including autotel-devtools)
@@ -113,7 +146,7 @@ allows it); `pretty: true` swaps JSON for human-readable stdout; `console: false
 drops the stdout line and emits only the log record — use it when
 `captureConsole()` is on, or every Effect log is reported twice.
 
-### 4. Unit tests: provide nothing
+### 5. Unit tests: provide nothing
 
 Effect's default `Tracer` is already an in-memory native tracer, so handler tests
 need no layer at all — `Effect.withSpan` runs and exports nowhere:
@@ -127,12 +160,16 @@ that assert on exported spans.
 
 ## Trace shape
 
+With `Effect.runPromise(withAutotel(program))`:
+
 ```text
 HTTP GET /api/todos     (autotel node:http)
   └── todo.list         (Effect.withSpan)
         └── db.query    (another withSpan or instrumented client)
 ```
 
+Without `withAutotel`, `todo.list` is the root of a second, unrelated trace.
+
 ## Example
 
 See [`apps/example-effect`](../../apps/example-effect) in the autotel monorepo.

package/dist/index.cjs

@@ -31,6 +31,8 @@ let autotel = require("autotel");
 let autotel_logger = require("autotel/logger");
 let effect_Cause = require("effect/Cause");
 effect_Cause = __toESM(effect_Cause, 1);
+let effect_Effect = require("effect/Effect");
+effect_Effect = __toESM(effect_Effect, 1);
 let effect_Layer = require("effect/Layer");
 effect_Layer = __toESM(effect_Layer, 1);
 let effect_Logger = require("effect/Logger");
@@ -58,6 +60,23 @@ function layer(options) {
 	}));
 }
 /**
+* Runs `self` as a child of the autotel span active around it, so an
+* `Effect.withSpan` inside an instrumented handler lands in that request's
+* trace: `Effect.runPromise(withAutotel(program))`.
+*
+* Effect takes a span's parent from its own `Tracer.ParentSpan`, which the
+* ambient OpenTelemetry context does not supply. The active span is read when
+* the effect runs rather than when it is built, so a program assembled once at
+* startup still joins the request it runs inside - and why this is not part of
+* `layer()`, which is built once for the whole application.
+*/
+function withAutotel(self) {
+	return effect_Effect.suspend(() => {
+		const spanContext = (0, autotel.getActiveSpan)()?.spanContext();
+		return spanContext && autotel.otelTrace.isSpanContextValid(spanContext) ? _effect_opentelemetry_OtelTracer.withSpanContext(self, spanContext) : self;
+	});
+}
+/**
 * Routes Effect's `Effect.log*` through autotel instead of Effect's console
 * logger, emitting each log as an OpenTelemetry log record (so it reaches any
 * OTLP log backend, autotel-devtools included) and, unless disabled, a
@@ -113,3 +132,4 @@ function formatPart(part) {
 //#endregion
 exports.layer = layer;
 exports.loggerLayer = loggerLayer;
+exports.withAutotel = withAutotel;

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { BuiltinLoggerOptions } from "autotel/logger";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 //#region src/index.d.ts
 interface AutotelEffectLoggerOptions {
@@ -36,6 +37,18 @@ interface AutotelEffectLayerOptions {
  * instrumentation module with `node --import` or `tsx --import`.
  */
 declare function layer(options: AutotelEffectLayerOptions): Layer.Layer<never>;
+/**
+ * Runs `self` as a child of the autotel span active around it, so an
+ * `Effect.withSpan` inside an instrumented handler lands in that request's
+ * trace: `Effect.runPromise(withAutotel(program))`.
+ *
+ * Effect takes a span's parent from its own `Tracer.ParentSpan`, which the
+ * ambient OpenTelemetry context does not supply. The active span is read when
+ * the effect runs rather than when it is built, so a program assembled once at
+ * startup still joins the request it runs inside - and why this is not part of
+ * `layer()`, which is built once for the whole application.
+ */
+declare function withAutotel<A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 /**
  * Routes Effect's `Effect.log*` through autotel instead of Effect's console
  * logger, emitting each log as an OpenTelemetry log record (so it reaches any
@@ -47,4 +60,4 @@ declare function layer(options: AutotelEffectLayerOptions): Layer.Layer<never>;
  */
 declare function loggerLayer(options: Omit<AutotelEffectLayerOptions, 'logs'> & AutotelEffectLoggerOptions): Layer.Layer<never, never, never>;
 //#endregion
-export { AutotelEffectLayerOptions, AutotelEffectLoggerOptions, layer, loggerLayer };
+export { AutotelEffectLayerOptions, AutotelEffectLoggerOptions, layer, loggerLayer, withAutotel };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { BuiltinLoggerOptions } from "autotel/logger";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 //#region src/index.d.ts
 interface AutotelEffectLoggerOptions {
@@ -36,6 +37,18 @@ interface AutotelEffectLayerOptions {
  * instrumentation module with `node --import` or `tsx --import`.
  */
 declare function layer(options: AutotelEffectLayerOptions): Layer.Layer<never>;
+/**
+ * Runs `self` as a child of the autotel span active around it, so an
+ * `Effect.withSpan` inside an instrumented handler lands in that request's
+ * trace: `Effect.runPromise(withAutotel(program))`.
+ *
+ * Effect takes a span's parent from its own `Tracer.ParentSpan`, which the
+ * ambient OpenTelemetry context does not supply. The active span is read when
+ * the effect runs rather than when it is built, so a program assembled once at
+ * startup still joins the request it runs inside - and why this is not part of
+ * `layer()`, which is built once for the whole application.
+ */
+declare function withAutotel<A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 /**
  * Routes Effect's `Effect.log*` through autotel instead of Effect's console
  * logger, emitting each log as an OpenTelemetry log record (so it reaches any
@@ -47,4 +60,4 @@ declare function layer(options: AutotelEffectLayerOptions): Layer.Layer<never>;
  */
 declare function loggerLayer(options: Omit<AutotelEffectLayerOptions, 'logs'> & AutotelEffectLoggerOptions): Layer.Layer<never, never, never>;
 //#endregion
-export { AutotelEffectLayerOptions, AutotelEffectLoggerOptions, layer, loggerLayer };
+export { AutotelEffectLayerOptions, AutotelEffectLoggerOptions, layer, loggerLayer, withAutotel };

package/dist/index.js

@@ -2,9 +2,10 @@ import { logLevelToSeverityNumber } from "@effect/opentelemetry/OtelLogger";
 import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import * as Resource from "@effect/opentelemetry/Resource";
 import { logs } from "@opentelemetry/api-logs";
-import { flattenToAttributes } from "autotel";
+import { flattenToAttributes, getActiveSpan, otelTrace } from "autotel";
 import { createBuiltinLogger } from "autotel/logger";
 import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as References from "effect/References";
@@ -29,6 +30,23 @@ function layer(options) {
 	}));
 }
 /**
+* Runs `self` as a child of the autotel span active around it, so an
+* `Effect.withSpan` inside an instrumented handler lands in that request's
+* trace: `Effect.runPromise(withAutotel(program))`.
+*
+* Effect takes a span's parent from its own `Tracer.ParentSpan`, which the
+* ambient OpenTelemetry context does not supply. The active span is read when
+* the effect runs rather than when it is built, so a program assembled once at
+* startup still joins the request it runs inside - and why this is not part of
+* `layer()`, which is built once for the whole application.
+*/
+function withAutotel(self) {
+	return Effect.suspend(() => {
+		const spanContext = getActiveSpan()?.spanContext();
+		return spanContext && otelTrace.isSpanContextValid(spanContext) ? OtelTracer.withSpanContext(self, spanContext) : self;
+	});
+}
+/**
 * Routes Effect's `Effect.log*` through autotel instead of Effect's console
 * logger, emitting each log as an OpenTelemetry log record (so it reaches any
 * OTLP log backend, autotel-devtools included) and, unless disabled, a
@@ -82,4 +100,4 @@ function formatPart(part) {
 	}
 }
 //#endregion
-export { layer, loggerLayer };
+export { layer, loggerLayer, withAutotel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-effect",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "description": "Bridge autotel and Effect v4: Effect.withSpan spans export through autotel's global TracerProvider",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "@opentelemetry/api-logs": "^0.222.0",
     "@opentelemetry/sdk-logs": "^0.222.0",
     "@types/node": "^26.1.2",
-    "autotel": "7.6.2",
+    "autotel": "7.7.0",
     "effect": "4.0.0-rc.112",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",