feat(sdk): OpenTelemetry spans, without depending on OpenTelemetry - #38
Merged
Conversation
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.
Closes WebDecoy/app#740
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
The
Tracertype is a structural subset of OpenTelemetry's, sotrace.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, andwebdecoy.remote— whether this request cost a round trip to ingest or was settled locally.A tracer cannot break a request
startSpanreturning 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.