autotel-effect 4.0.0 → 4.1.0

package/NOTICE

@@ -0,0 +1,9 @@
+autotel
+Copyright 2026 Jag Reehal
+
+This product is licensed under the Apache License, Version 2.0.
+See the LICENSE file for the full license text.
+
+"autotel" is a trademark of Jag Reehal. The Apache License, Version 2.0
+does not grant rights to use the "autotel" name. See TRADEMARKS.md for
+the trademark policy.

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)
@@ -94,6 +127,15 @@ Effect.log('charged').pipe(Effect.annotateLogs({ 'order.id': 'o-1' }));
 // {"level":"info","msg":"charged","order.id":"o-1","traceId":"...","spanId":"..."}
 ```
 
+Rich annotation values are flattened to the attribute shape the rest of autotel
+produces: a nested object becomes dot-notation keys, a `Date` becomes an ISO
+string, an `Error` becomes its message.
+
+```typescript
+Effect.annotateLogs({ order: { id: 7 }, at: new Date(0) });
+// attributes: { 'order.id': 7, at: '1970-01-01T00:00:00.000Z' }
+```
+
 Errors keep their stack: a `Cause` passed to `Effect.logError` (or an `Error`
 in the message parts) is logged as `err` rather than stringified into `msg`.
 
@@ -104,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:
@@ -118,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

@@ -21,14 +21,18 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+let _effect_opentelemetry_OtelLogger = require("@effect/opentelemetry/OtelLogger");
 let _effect_opentelemetry_OtelTracer = require("@effect/opentelemetry/OtelTracer");
 _effect_opentelemetry_OtelTracer = __toESM(_effect_opentelemetry_OtelTracer, 1);
 let _effect_opentelemetry_Resource = require("@effect/opentelemetry/Resource");
 _effect_opentelemetry_Resource = __toESM(_effect_opentelemetry_Resource, 1);
 let _opentelemetry_api_logs = require("@opentelemetry/api-logs");
+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");
@@ -56,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
@@ -82,12 +103,12 @@ function loggerLayer(options) {
 		if (options.console ?? true) log[method](metadata, body);
 		otelLogger().emit({
 			body,
-			severityNumber: LEVEL_TO_SEVERITY[logLevel],
+			severityNumber: (0, _effect_opentelemetry_OtelLogger.logLevelToSeverityNumber)(logLevel),
 			severityText: logLevel,
-			attributes: {
+			attributes: (0, autotel.flattenToAttributes)({
 				...metadata,
 				...Array.isArray(metadata.err) ? { err: metadata.err.join("\n") } : {}
-			}
+			})
 		});
 	})], { mergeWithExisting: options.mergeWithExisting ?? false });
 }
@@ -99,16 +120,6 @@ const LEVEL_TO_METHOD = {
 	Error: "error",
 	Fatal: "error"
 };
-const LEVEL_TO_SEVERITY = {
-	All: _opentelemetry_api_logs.SeverityNumber.UNSPECIFIED,
-	Trace: _opentelemetry_api_logs.SeverityNumber.TRACE,
-	Debug: _opentelemetry_api_logs.SeverityNumber.DEBUG,
-	Info: _opentelemetry_api_logs.SeverityNumber.INFO,
-	Warn: _opentelemetry_api_logs.SeverityNumber.WARN,
-	Error: _opentelemetry_api_logs.SeverityNumber.ERROR,
-	Fatal: _opentelemetry_api_logs.SeverityNumber.FATAL,
-	None: _opentelemetry_api_logs.SeverityNumber.UNSPECIFIED
-};
 function formatPart(part) {
 	if (typeof part === "string") return part;
 	if (part instanceof Error) return String(part);
@@ -121,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

@@ -1,8 +1,11 @@
+import { logLevelToSeverityNumber } from "@effect/opentelemetry/OtelLogger";
 import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
 import * as Resource from "@effect/opentelemetry/Resource";
-import { SeverityNumber, logs } from "@opentelemetry/api-logs";
+import { logs } from "@opentelemetry/api-logs";
+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";
@@ -27,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
@@ -53,12 +73,12 @@ function loggerLayer(options) {
 		if (options.console ?? true) log[method](metadata, body);
 		otelLogger().emit({
 			body,
-			severityNumber: LEVEL_TO_SEVERITY[logLevel],
+			severityNumber: logLevelToSeverityNumber(logLevel),
 			severityText: logLevel,
-			attributes: {
+			attributes: flattenToAttributes({
 				...metadata,
 				...Array.isArray(metadata.err) ? { err: metadata.err.join("\n") } : {}
-			}
+			})
 		});
 	})], { mergeWithExisting: options.mergeWithExisting ?? false });
 }
@@ -70,16 +90,6 @@ const LEVEL_TO_METHOD = {
 	Error: "error",
 	Fatal: "error"
 };
-const LEVEL_TO_SEVERITY = {
-	All: SeverityNumber.UNSPECIFIED,
-	Trace: SeverityNumber.TRACE,
-	Debug: SeverityNumber.DEBUG,
-	Info: SeverityNumber.INFO,
-	Warn: SeverityNumber.WARN,
-	Error: SeverityNumber.ERROR,
-	Fatal: SeverityNumber.FATAL,
-	None: SeverityNumber.UNSPECIFIED
-};
 function formatPart(part) {
 	if (typeof part === "string") return part;
 	if (part instanceof Error) return String(part);
@@ -90,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.0",
+  "version": "4.1.0",
   "description": "Bridge autotel and Effect v4: Effect.withSpan spans export through autotel's global TracerProvider",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "keywords": [
     "autotel",
@@ -53,7 +55,7 @@
     "@opentelemetry/api-logs": "^0.222.0",
     "@opentelemetry/sdk-logs": "^0.222.0",
     "@types/node": "^26.1.2",
-    "autotel": "7.6.1",
+    "autotel": "7.6.2",
     "effect": "4.0.0-rc.112",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",