OpenTelemetry

Traceway's symbolicator ships as a standalone OpenTelemetry Collector processor, source_map_symbolicator. Add it to your collector pipeline and minified JavaScript stack traces in spans, span events, and log records are rewritten to original files, lines, columns, and function names before they reach any backend, Traceway or otherwise.

It's a drop-in replacement for Honeycomb's source_map_symbolicator processor (opens in a new tab): same component type, same attribute contract, same store layout, same configuration keys. Existing pipelines and instrumentation (for example @honeycombio/opentelemetry-web with GlobalErrorsInstrumentation) work unchanged. What you gain by swapping:

• A cache bounded by disk, not RAM. Maps and bundles compile once into the .tw resolver format and are memory-mapped from a local cache directory with an LRU byte cap. Resident memory tracks the hot set, restarts warm from disk.
• Pure Go, no cgo. No glibc base image requirement; runs in scratch.
• Function names via bundle scope analysis, the same approach Sentry's symbolic uses.

If you want to call the engine from your own Go code instead of a collector, see Library.

The same processor also auto-routes non-symbolic Dart AOT traces and stripped iOS/Swift traces to the Dart and iOS paths. The walkthrough below covers the JavaScript source-map workflow.

Building a collector with the processor

The processor is a public package of the published github.com/tracewayapp/traceway/backend module, exposing the standard NewFactory() entry point, so it plugs into the OpenTelemetry Collector Builder (opens in a new tab) like any other component. Because the package is not at the module root, the manifest entry carries an import line alongside gomod.

The repo's benchmarks/processor (opens in a new tab) is a complete, runnable example of all of this: a builder manifest, a collector config, and a run-local.sh that builds the collector and drives load through it. The steps below mirror it.

go install go.opentelemetry.io/collector/cmd/builder@v0.154.0

dist:
  name: otelcol-symbolicator
  description: OTel Collector with the Traceway symbolicator
  output_path: ./build
 
receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.154.0
 
processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.154.0
  - gomod: github.com/tracewayapp/traceway/backend v1.8.0
    import: github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor
 
exporters:
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.154.0

builder --config manifest.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
 
processors:
  source_map_symbolicator:
    source_map_store: file_store
    local_source_maps:
      path: /sourcemaps
    cache_dir: /var/cache/symbolicator
    cache_max_mb: 2048
  batch:
 
exporters:
  otlphttp:
    endpoint: https://otel.example.com
    headers:
      Authorization: Bearer <token>
 
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [source_map_symbolicator, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [source_map_symbolicator, batch]
      exporters: [otlphttp]

exporters:
  otlphttp:
    endpoint: https://traceway.example.com/api/otel
    headers:
      Authorization: Bearer <project token>

./build/otelcol-symbolicator --config config.yaml

Registering the factory programmatically

When you assemble a collector in Go instead of using the builder, register the factory like any other processor factory:

import "github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor"
 
factory := otelprocessor.NewFactory()
factories.Processors[factory.Type()] = factory

The component type is source_map_symbolicator, with traces and logs support at alpha stability.

Populating the source map store

The store holds your build output as-is: minified bundles next to their .map files, addressed by URL basename. Upload (or mount) the files your bundler emitted; no manifest or renaming is needed.

1. A frame URL like https://cdn.example.com/assets/app-3f9c.js:1:13337 is looked up in the store as app-3f9c.js.
2. The bundle's //# sourceMappingURL= comment is followed to find the map (inline data: URIs are supported).
3. Both compile into one resolver, cached thereafter.

Content-hashed filenames from different deploys coexist naturally. For stable filenames (app.js), either accept last-upload-wins or set the app.debug.source_map_uuid resource attribute in your web SDK; the processor then prefixes store lookups with that uuid, isolating each build under its own directory:

/sourcemaps/
  9c1d2b3a-.../(app.js, app.js.map)   # build A
  4e5f6a7b-.../(app.js, app.js.map)   # build B

Three store backends are built in:

# Local directory (default)
source_map_store: file_store
local_source_maps:
  path: /sourcemaps
 
# S3, credentials from the default AWS chain
source_map_store: s3_store
s3_source_maps:
  region: eu-central-1
  bucket: my-sourcemaps
  prefix: production
 
# GCS, credentials from Application Default Credentials
source_map_store: gcs_store
gcs_source_maps:
  bucket: my-sourcemaps
  prefix: production

What the processor reads and writes

For each span, span event, or log record carrying an exception:

Raw string parsing handles the stack formats browsers produce: V8 (including async, new, [as alias], and eval frames) and Firefox.

Configuration reference

Every attribute key from the table above is remappable (stack_trace_attribute_key, urls_attribute_key, symbolicator_failure_attribute_key, and so on), with the same configuration keys and defaults as Honeycomb's processor.

Failed fetches are negative-cached for one minute per bundle, so a missing upload cannot turn an error storm into a store-request storm.

Sizing the cache

• cache_dir unset: every resolver is rebuilt from the store on demand and held only in the in-memory LRU (source_map_cache_size entries). Fine for small corpora.
• cache_dir set: each map+bundle compiles to a .tw file once; subsequent loads are mmaps measured in microseconds. Budget with cache_max_mb, or cache_max_disk_pct: 50 to track the filesystem size. .tw files are typically a small multiple of the map's mappings field, far smaller than the parsed-in-RAM representation.

For the numbers behind that choice (throughput, memory, and what survives memory pressure), see Performance. For the full engine internals, see Architecture and JavaScript.