feat(sdk): OpenTelemetry spans, without depending on OpenTelemetry by cport1 · Pull Request #38 · WebDecoy/node

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 · 2026-08-22T16:40:31Z

Closes WebDecoy/app#740 — the last issue in milestone 26.

Injected, not imported

The issue specified an optional peer dependency. I did not do that, and the reason is worth stating: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import is expensive. A conditional import('@opentelemetry/api') bundles badly in both directions — the bundler either resolves it, adding weight for the majority who never use it, or fails on a module that is legitimately absent.

So the tracer is passed in:

import{trace}from'@opentelemetry/api';newWebDecoy({tracer: trace.getTracer('webdecoy')});

The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer() satisfies it directly with no adapter. This meets the issue's acceptance criteria more cleanly than a peer dep would: an app with OTel sees spans; an app without sees no behaviour change and no new dependency in its lockfile — not even an optional one.

What the spans say

Attributes are the questions an operator actually asks, not everything available: decision.id (which joins the span to its dashboard row), decision.conclusion, decision.allowed, decision.rule, rules.evaluated, and webdecoy.remote — whether this request cost a round trip to ingest or was settled locally.

A tracer cannot break a request

startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op. Observability that can take the request path down is worse than none, and a misconfigured exporter must not become a 500 on a customer's site. Four of the eight tests are hostile tracers.

The no-op span is also why there are no null checks at the call sites — every if (span) is a branch that gets forgotten on the path that mattered, and a span left unended leaks.

There's a test that the span is ended on the ERROR path specifically: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than obviously absent.

Verification

463 tests, 20/20 turbo tasks, three edge entry points still clean — the last of which is the point.

A span around protect() and a child around rule evaluation, carrying the decision id (which joins a span to its dashboard row), the conclusion, the deciding rule, and whether the request cost a round trip to ingest. The tracer is INJECTED, not imported. An optional peer dependency was the obvious route and the wrong one: this package is dependency-free and passes an edge-compatibility gate, and Workers and Vercel Edge are exactly where a stray transitive import hurts. A conditional import('@opentelemetry/api') bundles badly too -- the bundler either resolves it, adding weight for the majority who do not use it, or fails on a module that is legitimately absent. The Tracer type is a structural subset of OpenTelemetry's, so trace.getTracer('webdecoy') satisfies it with no adapter. Omit it and there are no spans, no dependency and no behaviour change, which is the majority case and should cost them nothing. A tracer cannot break a request. startSpan returning nothing, throwing, or returning a span whose every method throws all degrade to a no-op -- observability that can take the request path down is worse than none. The no-op span also means call sites need no null checks, and an `if (span)` is a branch that gets forgotten on the path that mattered. Eight tests, four of them hostile tracers. Also asserts the span is ended on the ERROR path: a leaked span holds memory and never reaches the exporter, so the trace is silently incomplete rather than absent. ClosesWebDecoy/app#740

cport1 merged commit 1975cb5 into mainAug 22, 2026
2 checks passed

cport1 deleted the feat/otel-spans branch August 22, 2026 16:42