Abstract
A minified stack trace identifies deployed JavaScript, not necessarily the source a developer needs to edit. smapped-traces adds source-map resolution to an OpenTelemetry pipeline. It connects build-time map collection, client-side debug IDs, and server-side resolution before forwarding the trace to a collector. [1]
1. The problem
A browser exception may report a line and column in a compressed bundle. Keeping that string in telemetry preserves what the browser emitted, but does not reconstruct the original module location. The resolver needs the map corresponding to the exact deployed artifact.
A URL alone can be an unreliable artifact identity when assets move or a path is reused between releases. The project uses debug IDs supplied by the build to associate stack frames with stored maps. Both the build and the trace-processing service must agree on that store and identity. [1]
2. The design
Build integrations collect maps into a SourceMapStore. The client exporter enriches exception stacks from bundler debug-ID globals. A server handler reads the corresponding maps, resolves source locations, and forwards the resulting spans through the chosen OpenTelemetry exporter. Next.js and Vite integrations cover collection at build time. [1]
Storage is an explicit interface, with local SQLite, an HTTP store adapter, and S3-compatible storage options. The handler uses standard Request and Response objects so it can run separately from the application framework. This makes symbolication a deployable part of the telemetry path instead of a responsibility left to the final dashboard. [1]
3. Alternatives
The relevant distinction is the requirement each approach serves.
3.1 Forwarding the original exception.stacktrace
- The constraint
- OpenTelemetry defines a stacktrace attribute, but recording its string value does not itself load build artifacts or apply a JavaScript source map. [2]
- Our approach
- smapped-traces adds artifact lookup and mapping before the selected exporter sends spans onward. [1]
- The tradeoff
- Raw stacks remain useful when code is unminified or the downstream backend already performs the required resolution.
3.2 Sentry source-map uploads
- The constraint
- Sentry already supports debug-ID-based source-map resolution. Its documented build integration uploads the artifacts for Sentry's processing pipeline. [3]
- Our approach
- smapped-traces makes the resolver and store part of an application's OpenTelemetry path, allowing it to forward resolved traces to its chosen collector. [1]
- The tradeoff
- A team already using Sentry's complete error workflow may have no reason to operate a separate resolver and artifact store.
4. Boundaries & adoption
The map must exist and match the debug ID. Instrumentation cannot recover original source that was never collected or retained. Plan artifact retention around the releases that can still emit telemetry, and verify the build actually injects a supported debug-ID mapping. [1]
The documented Next.js integration requires Next.js 16+, and the core targets OpenTelemetry SDK v2+. Treat map storage and any ingestion endpoint as application infrastructure with deliberate access controls. This library supplies resolution, not an entire observability backend.
5. References
Sources reviewed September 12, 2026. Mathematic source links retain the reviewed revision.
- [1]smapped-traces: pipeline, packages, stores, debug IDs, and requirements Mathematic Inc. · b811c4ad
- [2]OpenTelemetry: exception semantic conventions opentelemetry.io
- [3]