The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: docs, website updated for flutter symbolication + symbol upload… (#208)
narrow-adventure690d4b0dc590
diff --git a/backend/app/symbolicator/dart/fixtures/flutter-macos-arm64-dart3.10.1/expected.txt b/backend/app/symbolicator/dart/fixtures/flutter-macos-arm64-dart3.10.1/expected.txtindex 4a1b158d..dd3af6e3 100644--- a/backend/app/symbolicator/dart/fixtures/flutter-macos-arm64-dart3.10.1/expected.txt+++ b/backend/app/symbolicator/dart/fixtures/flutter-macos-arm64-dart3.10.1/expected.txt@@ -1,14 +1,14 @@-chargeCard (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:20:3)-applyTax (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:30:10)-checkout (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:35:10)-main.<anonymous closure> (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:47:7)+chargeCard (/app/lib/main.dart:20:3)+applyTax (/app/lib/main.dart:30:10)+checkout (/app/lib/main.dart:35:10)+main.<anonymous closure> (/app/lib/main.dart:47:7)_rootRun (third_party/dart/sdk/lib/async/zone.dart:1525:13)_rootRun (third_party/dart/sdk/lib/async/zone.dart:1516:1)_CustomZone.run (third_party/dart/sdk/lib/async/zone.dart:1422:19)_runZoned (third_party/dart/sdk/lib/async/zone.dart:2034:6)runZonedGuarded (third_party/dart/sdk/lib/async/zone.dart:2020:12)-main (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:42:3)-main (/Users/dusanstanojevic/Documents/flutter-demo/app/lib/main.dart:38:1)+main (/app/lib/main.dart:42:3)+main (/app/lib/main.dart:38:1)_Closure.call (third_party/dart/sdk/lib/_internal/vm/lib/function.dart)_runMain.<anonymous closure> (lib/ui/hooks.dart:345:23)_Closure.call (third_party/dart/sdk/lib/_internal/vm/lib/function.dart)diff --git a/backend/app/symbolicator/dart/flat.go b/backend/app/symbolicator/dart/flat.goindex 46747357..e2cf1869 100644--- a/backend/app/symbolicator/dart/flat.go+++ b/backend/app/symbolicator/dart/flat.go@@ -203,7 +203,7 @@ func flatten(data *dwarf.Data, base map[string]uint64, buildID string) *flatBuilstart := uint32(len(f.frames))for _, sf := range sfs {f.frames = append(f.frames, flatFrame{- fileIdx: files.intern(sf.File),+ fileIdx: files.intern(normalizeFilePath(sf.File)),line: int32(sf.Line),col: int32(sf.Col),fnIdx: fns.intern(sf.Function),@@ -414,7 +414,7 @@ func (in *interner) intern(s string) int32 {var dwMagic = [4]byte{'T', 'W', 'D', 'F'}-const dwVersion = 1+const dwVersion = 3var ErrInvalidFlat = errors.New("dart: invalid flat data")diff --git a/backend/app/symbolicator/dart/normalize.go b/backend/app/symbolicator/dart/normalize.goindex d75e9622..e7a45d42 100644--- a/backend/app/symbolicator/dart/normalize.go+++ b/backend/app/symbolicator/dart/normalize.go@@ -47,3 +47,56 @@ func IsValidArch(arch string) bool {}return true}++func normalizeFilePath(path string) string {+ if path == "" {+ return path+ }+ if pkg, rest, ok := packageFromHosted(path); ok {+ return "package:" + pkg + "/" + rest+ }+ if pkg, rest, ok := packageFromPackagesDir(path); ok {+ return "package:" + pkg + "/" + rest+ }+ if strings.HasPrefix(path, "/") {+ if i := strings.LastIndex(path, "/lib/"); i != -1 {+ if j := strings.LastIndex(path[:i], "/"); j >= 0 {+ return path[j:]+ }+ return path[i:]+ }+ }+ return path+}++func packageFromPackagesDir(p string) (string, string, bool) {+ _, after, ok := strings.Cut(p, "/packages/")+ if !ok {+ return "", "", false+ }+ pkg, rest, ok := strings.Cut(after, "/")+ if !ok || pkg == "" || !strings.HasPrefix(rest, "lib/") {+ return "", "", false+ }+ return pkg, rest[len("lib/"):], true+}++func packageFromHosted(p string) (string, string, bool) {+ _, after, ok := strings.Cut(p, "/hosted/")+ if !ok {+ return "", "", false+ }+ _, after, ok = strings.Cut(after, "/")+ if !ok {+ return "", "", false+ }+ dir, rest, ok := strings.Cut(after, "/")+ if !ok || dir == "" || !strings.HasPrefix(rest, "lib/") {+ return "", "", false+ }+ pkg, _, ok := strings.Cut(dir, "-")+ if !ok || pkg == "" {+ return "", "", false+ }+ return pkg, rest[len("lib/"):], true+}diff --git a/backend/app/symbolicator/dart/normalize_test.go b/backend/app/symbolicator/dart/normalize_test.goindex bdd35691..8a887102 100644--- a/backend/app/symbolicator/dart/normalize_test.go+++ b/backend/app/symbolicator/dart/normalize_test.go@@ -32,6 +32,26 @@ func TestNormalizeArchSanitizesUnsafeInput(t *testing.T) {}}+func TestNormalizeFilePath(t *testing.T) {+ cases := map[string]string{+ "/Users/dusanstanojevic/Documents/test-app/lib/main.dart": "/test-app/lib/main.dart",+ "/Users/dusanstanojevic/Documents/flutter/packages/flutter/lib/src/material/ink_well.dart": "package:flutter/src/material/ink_well.dart",+ "/Users/x/.pub-cache/hosted/pub.dev/http-1.2.0/lib/src/client.dart": "package:http/src/client.dart",+ "/Users/x/.pub-cache/hosted/pub.dev/flutter_quick_video_encoder-1.7.2/lib/enc.dart": "package:flutter_quick_video_encoder/enc.dart",+ "/Users/x/.pub-cache/hosted/pub.dev/foo_bar-1.0.0-beta.1/lib/a.dart": "package:foo_bar/a.dart",+ "lib/ui/hooks.dart": "lib/ui/hooks.dart",+ "third_party/dart/sdk/lib/async/zone.dart": "third_party/dart/sdk/lib/async/zone.dart",+ "file:///private/tmp/dartfix/crash.dart": "file:///private/tmp/dartfix/crash.dart",+ "dart:isolate-patch/isolate_patch.dart": "dart:isolate-patch/isolate_patch.dart",+ "": "",+ }+ for in, want := range cases {+ if got := normalizeFilePath(in); got != want {+ t.Errorf("normalizeFilePath(%q) = %q, want %q", in, got, want)+ }+ }+}+func TestIsValidArch(t *testing.T) {for _, a := range []string{"arm64", "x64", "x86_64", "ia32", "arm", "riscv64"} {if !IsValidArch(a) {diff --git a/backend/app/symbolicator/otelprocessor/README.md b/backend/app/symbolicator/otelprocessor/README.mdindex d74e4ccf..4a8dad08 100644--- a/backend/app/symbolicator/otelprocessor/README.md+++ b/backend/app/symbolicator/otelprocessor/README.md@@ -87,6 +87,6 @@ The store holds your build output as-is: minified bundles next to their maps, ad## Links- [Traceway](https://tracewayapp.com), the MIT-licensed error tracking platform this engine comes from-- [Hosted docs for this processor](https://docs.tracewayapp.com/learn/collector-symbolicator), including the builder walkthrough-- [Symbolication pipeline internals](https://docs.tracewayapp.com/learn/symbolication-js), including the `.tw` format+- [Hosted docs for this processor](https://docs.tracewayapp.com/symbolicator/opentelemetry), including the builder walkthrough+- [Symbolication pipeline internals](https://docs.tracewayapp.com/symbolicator), including the `.tw` format- [Honeycomb's processor](https://github.com/honeycombio/opentelemetry-collector-symbolicator), whose configuration surface this matchesdiff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 124b2b60..20d10ff7 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -3,7 +3,7 @@## Navbar- The header navbar items must always be aligned to the left (next to the logo), not centered or spread across the header. This is achieved via CSS in `styles/custom.css`.-- Navbar order: Docs, Learn, Protocol, Self Host (controlled by key order in `pages/_meta.json`).+- Navbar order: Docs, Learn, Symbolicator, Protocol, Self Host (controlled by key order in `pages/_meta.json`).## SDK Selection (path-derived)diff --git a/docs/components/Redirect.jsx b/docs/components/Redirect.jsxnew file mode 100644index 00000000..4adafb5d--- /dev/null+++ b/docs/components/Redirect.jsx@@ -0,0 +1,16 @@+import { useEffect } from 'react'+import { useRouter } from 'next/router'++export default function Redirect({ to }) {+ const router = useRouter()++ useEffect(() => {+ router.replace(to)+ }, [to, router])++ return (+ <p>+ This page has moved. <a href={to}>Continue →</a>+ </p>+ )+}diff --git a/docs/pages/_meta.json b/docs/pages/_meta.jsonindex 7df41d20..0b6d1c50 100644--- a/docs/pages/_meta.json+++ b/docs/pages/_meta.json@@ -2,6 +2,7 @@"index": { "title": "Traceway", "type": "page", "display": "hidden" },"client": { "title": "Docs", "type": "page", "withIndexPage": true },"learn": { "title": "Learn", "type": "page" },+ "symbolicator": { "title": "Symbolicator", "type": "page" },"protocol": {"title": "Protocol","type": "page",diff --git a/docs/pages/client/flutter/index.mdx b/docs/pages/client/flutter/index.mdxindex 49678f67..9eca397b 100644--- a/docs/pages/client/flutter/index.mdx+++ b/docs/pages/client/flutter/index.mdx@@ -256,6 +256,28 @@ This replaces the region with a solid color (black by default) in the recording.- **Platform errors** — native platform channel errors.- **Uncaught async errors** — any unhandled exceptions in asynchronous code, captured via Dart's `Zone` mechanism.+## Release Symbolication (obfuscated builds)++A plain `flutter build --release` keeps readable stack traces, so there's nothing to do. If you harden a release with `--obfuscate` and/or `--split-debug-info`, the binary no longer carries names and traces arrive as bare instruction offsets. Upload the build's `.symbols` files and Traceway symbolicates those traces server-side.++The SDK ships an uploader. Configure it once in `pubspec.yaml`:++```yaml+traceway:+ url: https://your-traceway-host # omit on Traceway Cloud+ # upload_token: ... # prefer the env var in CI+```++The upload token is your project's upload token from the dashboard (the same one used for JS source maps), not the runtime token in your connection string. Then on every release:++```sh+flutter build apk --release --obfuscate --split-debug-info=build/symbols++TRACEWAY_UPLOAD_TOKEN=your-token dart run traceway:upload_symbols+```++The uploader auto-discovers `build/symbols`, so no flags are required. See [Dart symbolication](/symbolicator/dart) for the full reference (flags, Apple debug IDs, the upload API) and how resolution works.+## Test Your IntegrationAdd a button that throws an error to verify everything is wired up:diff --git a/docs/pages/client/js-sdk/debug-ids.mdx b/docs/pages/client/js-sdk/debug-ids.mdxindex f62479b4..78ecffe8 100644--- a/docs/pages/client/js-sdk/debug-ids.mdx+++ b/docs/pages/client/js-sdk/debug-ids.mdx@@ -94,4 +94,4 @@ OpenTelemetry currently has **no debug ID convention**: there is no semantic-con## Next Steps- [Source Maps](/client/js-sdk/sourcemap-upload): the upload CLI-- [Symbolication](/learn/symbolication-js): the full resolution pipeline+- [Symbolication](/symbolicator/javascript): the full resolution pipelinediff --git a/docs/pages/client/js-sdk/sourcemap-upload.mdx b/docs/pages/client/js-sdk/sourcemap-upload.mdxindex 40531eab..ce46d261 100644--- a/docs/pages/client/js-sdk/sourcemap-upload.mdx+++ b/docs/pages/client/js-sdk/sourcemap-upload.mdx@@ -126,7 +126,7 @@ The contract:| Auth failure | Missing or invalid token returns `401`. || Response | `200` with `{"uploaded": N}`, counting only the stored files (skipped files are excluded). || Debug IDs | Detected server-side in the uploaded content; no extra fields or flags needed. |-| Effect | Immediate. Cached resolvers for the uploaded filenames are evicted before the response, and precompiled [`.tw` resolvers](/learn/symbolication-js#the-tw-resolver-format) are rebuilt in the background so the first exception after a deploy finds a warm cache. |+| Effect | Immediate. Cached resolvers for the uploaded filenames are evicted before the response, and precompiled [`.tw` resolvers](/symbolicator#the-tw-resolver-format) are rebuilt in the background so the first exception after a deploy finds a warm cache. |The multipart filename becomes the stored name, and stack frames match against the basename of the frame's file, so send plain filenames without directory paths. `curl -F` already does this: it uses the basename of the local path.@@ -137,7 +137,7 @@ There is nothing to configure at runtime. When an exception is captured, Tracewa1. **By debug ID**, when the exception carries one for the frame's file. If your build uses [`@tracewayapp/bundler-plugin`](/client/js-sdk/debug-ids), every bundle and its map share an embedded unique ID, and the backend picks the map uploaded with that exact ID, immune to filename collisions and concurrent deploys. The upload endpoint detects debug IDs in uploaded files automatically; no CLI flags involved.2. **By filename** otherwise: the map you uploaded under the frame's filename is used. The most recent upload of each filename wins, so content-hashed bundle names (the default in Vite, Next, Angular, and most bundlers) keep every build's maps distinct automatically.-Uploads take effect immediately: the backend evicts any cached state for the uploaded filenames, so exceptions arriving right after a deploy resolve against the new maps. See [Symbolication](/learn/symbolication-js) for the full resolution pipeline.+Uploads take effect immediately: the backend evicts any cached state for the uploaded filenames, so exceptions arriving right after a deploy resolve against the new maps. See [Symbolication](/symbolicator/javascript) for the full resolution pipeline.The SDK's `version` option is unrelated to source maps: it is plain metadata shown on exceptions in the dashboard for filtering by build, and can be set or omitted independently of uploads.diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.jsonindex dc487514..6192d7ce 100644--- a/docs/pages/learn/_meta.json+++ b/docs/pages/learn/_meta.json@@ -4,9 +4,9 @@"traces": "Traces","ai-tracing": "AI Tracing","issues": "Issues",- "symbolication-js": "Symbolication (JS)",- "symbolicator-library": "Symbolicator as a Library",- "collector-symbolicator": "Collector Symbolicator",+ "symbolication-js": { "display": "hidden" },+ "symbolicator-library": { "display": "hidden" },+ "collector-symbolicator": { "display": "hidden" },"sessions": "Sessions","attributes": "Attributes","spans": "Spans",diff --git a/docs/pages/learn/collector-symbolicator.mdx b/docs/pages/learn/collector-symbolicator.mdxindex aafa39eb..62958a90 100644--- a/docs/pages/learn/collector-symbolicator.mdx+++ b/docs/pages/learn/collector-symbolicator.mdx@@ -1,215 +1,3 @@-# Symbolicator for the OTel Collector+import Redirect from "../../components/Redirect";-import { Callout, Steps } from "nextra/components";--Traceway's symbolicator also 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 is a drop-in replacement for [Honeycomb's `source_map_symbolicator` processor](https://github.com/honeycombio/opentelemetry-collector-symbolicator): 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](/learn/symbolication-js#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 [Symbolicator as a Go Library](/learn/symbolicator-library).--## 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](https://opentelemetry.io/docs/collector/custom-collector/) like any other component. Because the package is not at the module root, the manifest entry carries an `import` line alongside `gomod`.--<Steps>--### Install the builder--```bash-go install go.opentelemetry.io/collector/cmd/builder@latest-```--### Write the builder manifest--`builder-config.yaml`, with the Traceway processor next to whatever receivers and exporters you need:--```yaml-dist:- name: otelcol-symbolicator- description: OTel Collector with Traceway source map symbolication- output_path: ./dist--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-```--<Callout type="info">- The processor first ships in `v1.8.0`; use that tag or any newer one, and- keep the collector component versions aligned with each other as usual for- OCB manifests.-</Callout>--### Build it--```bash-builder --config builder-config.yaml-```--This produces `./dist/otelcol-symbolicator`, a self-contained collector binary.--### Configure the pipeline--`collector.yaml`:--```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]-```--To forward to Traceway, point the exporter at your Traceway server's OTLP base path and use a project token:--```yaml-exporters:- otlphttp:- endpoint: https://traceway.example.com/api/otel- headers:- Authorization: Bearer <project token>-```--### Run it--```bash-./dist/otelcol-symbolicator --config collector.yaml-```--</Steps>--## Registering the Factory Programmatically--When you assemble a collector in Go instead of using the builder, register the factory like any other processor factory:--```go-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:--```yaml-# 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:--| Attribute | Direction | Meaning |-| --------- | --------- | ------- |-| `exception.stacktrace` | read + rewritten | Raw stack in, symbolicated stack out |-| `exception.structured_stacktrace.{urls,functions,lines,columns}` | read + rewritten | Structured parallel arrays, preferred over string parsing when present |-| `exception.type`, `exception.message` | read | Used for the rewritten header line |-| `app.debug.source_map_uuid` | read (resource) | Optional store key prefix per build |-| `exception.stacktrace.original` and `.original` array variants | written | Originals, kept when `preserve_stack_trace: true` |-| `exception.symbolicator.failed` | written | `true` when any frame failed |-| `exception.symbolicator.error` | written | First failure, with a count hint when several frames failed |-| `exception.symbolicator.parsing_method` | written | `structured_stacktrace_attributes` or `processor_parsed` |-| `traceway.processor_type`, `traceway.processor_version` | written | Provenance stamps |--Raw string parsing handles the stack formats browsers produce: V8 (including `async`, `new`, `[as alias]`, and `eval` frames) and Firefox.--## Configuration Reference--| Key | Default | Description |-| --- | ------- | ----------- |-| `source_map_store` | `file_store` | `file_store`, `s3_store`, or `gcs_store` |-| `local_source_maps.path` | `.` | Root directory for `file_store` |-| `s3_source_maps.region` / `.bucket` / `.prefix` | | S3 location |-| `gcs_source_maps.bucket` / `.prefix` | | GCS location |-| `timeout` | `5s` | Per-fetch budget for store reads |-| `cache_dir` | `""` | Directory for the `.tw` disk cache; empty disables the disk tier |-| `cache_max_mb` | `2048` | Byte cap for the disk cache, LRU-evicted |-| `cache_max_disk_pct` | `0` | Cap as a percentage of the cache directory's filesystem; when both caps are set, the smaller wins |-| `source_map_cache_size` | `128` | Max resolvers held in memory (cheap mmap handles when the disk tier is on) |-| `preserve_stack_trace` | `true` | Keep originals under the `.original` keys |-| `build_uuid_attribute_key` | `app.debug.source_map_uuid` | Resource attribute used as a store key prefix |-| `language_attribute_key` | `telemetry.sdk.language` | Attribute checked against `allowed_languages` |-| `allowed_languages` | `[]` | When set, only records with a matching language are processed |--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 full engine internals (resolver format, scope analysis, cache policy), see [Symbolication (JS)](/learn/symbolication-js).+<Redirect to="/symbolicator/opentelemetry" />diff --git a/docs/pages/learn/hardware-requirements.mdx b/docs/pages/learn/hardware-requirements.mdxindex 62834d7a..10545f56 100644--- a/docs/pages/learn/hardware-requirements.mdx+++ b/docs/pages/learn/hardware-requirements.mdx@@ -93,7 +93,7 @@ On a memory-constrained host, the single most effective change is lowering `SOURcaching design (in-memory LRU, the precompiled `.tw` format, the optional disktier) exists specifically to keep that bounded. The full story is in[A deep dive into the source maps](https://tracewayapp.com/blog/deep-dive-into-the-sourcemaps),- with the in-product mechanics on the [Symbolication (JS)](/learn/symbolication-js) page.+ with the in-product mechanics on the [Symbolication (JS)](/symbolicator/javascript) page.</Callout>## Rules of thumbdiff --git a/docs/pages/learn/symbolication-js.mdx b/docs/pages/learn/symbolication-js.mdxindex 3769b25b..b0f836ac 100644--- a/docs/pages/learn/symbolication-js.mdx+++ b/docs/pages/learn/symbolication-js.mdx@@ -1,357 +1,3 @@-# Symbolication (JS)+import Redirect from "../../components/Redirect";-Symbolication is the process of translating minified production stack traces back into the original source locations your team actually wrote. Browsers report errors against the shipped bundle, so without symbolication an exception looks like this:--```-TypeError: Cannot read properties of undefined (reading 'name')-anonymous()- app.bundle.js:1:48211-anonymous()- app.bundle.js:1:13377-```--With source maps uploaded, Traceway stores it like this instead:--```-TypeError: Cannot read properties of undefined (reading 'name')-renderUserCard()- src/components/UserCard.tsx:42:17-handleClick()- src/pages/Profile.tsx:108:5-```--This page explains exactly how that translation works today, what is cached and when, how the pipeline is observable through metrics, where the current limits are, and how we verify the output. For how to upload source maps in the first place, see [Source Maps](/client/js-sdk/sourcemap-upload).--The engine described here is also usable outside Traceway's ingest: as an importable Go package ([Symbolicator as a Library](/learn/symbolicator-library)) and as a standalone OpenTelemetry Collector processor ([Collector Symbolicator](/learn/collector-symbolicator)).--## When Symbolication Runs--Symbolication happens **once, at ingest**, inside `POST /api/report`:--1. The report arrives from the JS SDK. If the project is a JS framework, each frame is resolved directly against object storage, with no version and no database lookup. When the exception carries a [debug ID](/client/js-sdk/debug-ids) for the frame's file, the map is addressed at `sourcemaps/{projectId}/by-debug-id/{debugId}.js.map`; otherwise it is addressed by the frame's filename at `sourcemaps/{projectId}/{filename}.map`, where the most recent upload of each filename wins.-2. Each stack trace in the report is resolved frame by frame.-3. The **resolved** trace is what gets hashed for grouping and stored in ClickHouse.--The same resolution runs for exceptions arriving over the OTLP endpoint when the resource reports a JavaScript SDK (`telemetry.sdk.language` of `webjs`, `nodejs`, `javascript`, or `typescript`).--Nothing is re-resolved when you view an issue. The trade-off: traces are immutable snapshots of the symbolication quality at the moment they arrived. Uploading better source maps improves future events, not past ones.--## The Frame Format--The JS SDK does not send the browser's raw `error.stack` string. Stack formats are not standardized: V8 (Chrome, Edge, Hermes) emits ` at funcName (file:line:col)`, while Firefox and JavaScriptCore (Safari) emit `funcName@file:line:col`. The SDK parses both families and normalizes every frame into a canonical two-line wire format: a function name line ending in `()`, then a location line indented by four spaces:--```-anonymous()- app.bundle.js:1:48211-```--The resolver recognizes location lines with a single regex:--```-^(\s{4})(.+):(\d+):(\d+)$-```--Anything that does not match (the error message, the name lines, blank lines) passes through untouched. This is the first invariant of the pipeline: **the resolver can only rewrite a line or leave it exactly as it was**. There is no failure mode that drops or corrupts a frame.--## The Resolution Pipeline--For each location line, in order:--### 1. Find the right source map--**By debug ID first.** If the exception payload carries a `debugIds` entry for the frame's file (injected at build time by [`@tracewayapp/bundler-plugin`](/client/js-sdk/debug-ids)), the map is addressed at `sourcemaps/{projectId}/by-debug-id/{debugId}.js.map` and the bundle at the same key without `.map`. This is content-addressed matching: the ID was embedded into the bundle and its map by the build, so the frame can never resolve against a map from a different build, regardless of filenames, CDNs, or concurrent deploys. If no artifact with that debug ID was uploaded, resolution falls back to filename matching below.--**By filename otherwise.** The frame's file name is reduced to its basename (any query string or fragment stripped first), and the map is addressed in object storage at a deterministic key:--| Frame file | Storage key |-|---|---|-| `app.bundle.js` | `sourcemaps/{projectId}/app.bundle.js.map` |-| `https://cdn.example.com/assets/app.bundle.js` | `sourcemaps/{projectId}/app.bundle.js.map` |-| `app.bundle.js?v=abc123` | `sourcemaps/{projectId}/app.bundle.js.map` |--The minified bundle, when the upload CLI found one next to the map, lives at the same key without the `.map` suffix and feeds function name resolution (next section).--No map in storage: the line passes through unchanged, and that filename enters a miss cooldown so subsequent exceptions skip the storage read entirely (see "When loading fails" below).--### 2. Get the resolver--The parsed lookup structure comes from the in-memory cache described below, optionally backed by a disk tier of precompiled [`.tw` files](#the-tw-resolver-format). First use pays a storage read plus a parse (or a memory-mapped `.tw` open, which skips the parse); everything after is a memory lookup.--### 3. Look up the position--Browser stack traces use 1-based columns; the source map spec uses 0-based. The resolver subtracts 1 before the lookup and adds 1 back when printing. This off-by-one matters more than it sounds: minified bundles put the entire program on line 1, so being one column off can land on a *different token entirely* and resolve to the wrong original file.--Here is a real lookup, taken verbatim from our test fixtures. The original file:--```js-// built with: terser -c -m --module original.js --source-map includeSources-function abcd() {}-export default abcd;-```--terser renames `abcd` to `t` and emits:--```js-function t(){}export default t;-```--with this source map:--```json-{- "version": 3,- "names": ["abcd"],- "sources": ["tests/fixtures/simple/original.js"],- "sourcesContent": ["...the original file, embedded..."],- "mappings": "AACA,SAASA,oBACMA"-}-```--A frame pointing at `minified.js:1:11` (the `t` in `function t`) resolves through the `mappings` (delta-encoded VLQ segments of generated position, source index, original position, name index) to `tests/fixtures/simple/original.js:2:10`, with the name token `abcd`.--### 4. Rewrite the lines--The location line becomes `original-file:line:column` (same indentation). If a function name was resolved, the *name line directly above it* (the `anonymous()` line) is rewritten to `abcd()`.--If the source map carries `"sources": [null]` entries (older uglify pipelines), the file name is rendered as `<unknown>` but the line, column, and name still resolve.--A maximum of **50 frames** per trace are resolved; deeper frames pass through minified.--## Function Names: Scope Analysis--Locations come straight from the source map and are exact. Function names are harder, because a source map's `names` token at a position is the identifier *at that token*, not the name of the *enclosing function* that a stack trace conventionally shows. Getting the enclosing function right requires scope analysis: parsing the minified bundle into an AST and mapping positions to function scopes. This is the same approach Sentry's symbolic takes, and it is why the upload CLI sends the minified bundle alongside each `.map`.--When a bundle is available, the resolver:--1. Parses it with a pure-Go JavaScript parser into every function in the file: declarations, function expressions, arrow functions, and class methods, each with the generated position of its name. If the bundle fails to parse as a script (ESM syntax), it is retried with module syntax neutralized.-2. Flattens the nested scopes into a sorted list of transitions: "from this generated position onward, the innermost enclosing function's name sits at line L, column C".-3. For each mapping in the source map, resolves the enclosing function's *name position* back through the map itself, yielding the original, pre-minification name.--Take preact's `create-element.js`, which the old name heuristic famously got wrong:--```js-export function createElement(type, props, children) {- let normalizedProps = {},- key, ref, i;- for (i in props) { // error around here (line 40)- ...- }-}-```--A frame inside that loop now resolves to `createElement`, because the scope walk knows which function *contains* the error position rather than guessing from nearby text.--When no bundle was uploaded (a map-only upload from an older CLI, or a `.map` with no sibling bundle in the build output), there is no scope information and **no name is resolved**: the name line stays whatever the SDK reported (typically `anonymous()`), while file, line, and column still resolve exactly. Two design decisions contain the remaining gaps:--1. **Names never affect grouping.** See the next section.-2. **Locations never depend on the bundle.** The file, line, and column shown are exact source map output, so the click-through is right even when the label is missing.--## How Symbolication Interacts with Grouping--Issue grouping hashes a normalized form of the **resolved** trace. Two normalization rules exist specifically because of JS symbolication:--**Function name lines are collapsed.** A line ending in `()` that sits directly above a frame location line becomes `<fn>` before hashing (anchoring on the location line below means Go traces, whose file lines are tab-indented, are never touched):--```-createElement() becomes: <fn>- ../src/create-element.js:40:9 stays: ../src/create-element.js:40:9-```--So these two traces, identical except for resolved names, produce the **same hash** and land in the same issue:--```-Error: boom Error: boom- normalizedProps() createElement()- ../src/create-element.js:40:9 ../src/create-element.js:40:9-```--This means name quality can keep improving (for example, by uploading bundles where you previously uploaded only maps) without re-bucketing your existing issues.--**Columns are kept.** Minified bundles put everything on line 1, so when no source map matched, the column is the only thing distinguishing two different errors. `bundle.min.js:1:48211` and `bundle.min.js:1:91567` therefore hash differently, on purpose.--One consequence to be aware of: a trace that fails symbolication (storage outage, see below) hashes differently than its symbolicated twin. During an outage the same logical error can transiently open a second issue group, which stops growing once storage recovers.--## What Is Cached, How, and When--Source maps for real applications are large (a 20 MB `.map` is unremarkable), and the compiled lookup structure is what actually serves frames. Traceway keeps **one in-memory cache** of built resolvers, keyed by the map's storage key, optionally backed by a **disk tier** of precompiled [`.tw` files](#the-tw-resolver-format) (see [Cache backends](#cache-backends-memory-and-disk)).--### What a cache entry contains--Building a resolver consumes the `.map` and the bundle and keeps only what lookups need:--| Field | Used for |-|---|---|-| token table (one 24-byte token per mapping) | position lookup via binary search |-| interned file names | original file names |-| interned function names | enclosing function names, pre-resolved per scope at build time |--Everything else is discarded: the raw map and bundle bytes, `sourcesContent`, the bundle's AST, and the scope transitions all exist **only for the duration of the build**. Scope analysis runs once per build, not per lookup, so serving a frame is a binary search over the token table. The entry's in-memory size is estimated from the token count plus the interned strings, which is what the byte cap counts.--### Cache policy--| Property | Value |-|---|---|-| Keying | map storage key: one entry per bundle filename per project, plus one per debug ID for [debug-ID artifacts](/client/js-sdk/debug-ids) |-| Capacity | `SOURCEMAP_CACHE_MAX_ENTRIES` (default 200) and `SOURCEMAP_CACHE_MAX_BYTES_MB` (default 500, estimated resolver size) |-| Eviction | least recently used, whenever either cap is exceeded |-| Loading | deduplicated (singleflight): concurrent requests for the same map share one storage read and one build |-| Load timeout | 5 seconds per storage read |-| Failures | negative-cached with an escalating cooldown (below) |-| Invalidation | uploading a file evicts its resolver and clears its cooldown immediately |--### The lifecycle, end to end--Say two exceptions referencing `app.bundle.js.map` arrive at the same time, on a cold cache:--1. Both miss the cache and race to a mutex. The winner registers itself as the **loader** for that key; the loser sees the in-flight registration and parks.-2. The loader reads the `.map` and the bundle from storage (S3 or local disk, 5 second budget per read), builds the resolver (parse map, parse bundle, pre-resolve scope names), throws the raw bytes away, and inserts the slim entry.-3. The parked request wakes and receives the exact same resolver instance. One read, one build, one copy in memory, no matter how many requests piled up.-4. Every subsequent exception is a pure memory hit, which also bumps the entry to the front of the LRU.-5. If the cache later exceeds a cap, the least recently used entries are dropped. A dropped resolver is not an error; the next exception that needs it repeats steps 1 to 3.-6. Re-uploading `app.bundle.js.map` (or `app.bundle.js`) evicts the cached resolver, so the next exception rebuilds from the new upload rather than serving the stale one.--### When loading fails--If the map does not exist, the read times out, storage errors, or the map fails to parse:--- The affected frames pass through **unchanged**, and the trace is stored as-is. Ingest is never blocked beyond the per-read budgets (5 seconds each for the map and the bundle) and never errors because of symbolication. A transient failure reading the *bundle* fails the build too, rather than silently caching a resolver without function names; the cooldown retries it within seconds.-- The failure is **negative-cached per filename**: while the cooldown is active, frames referencing that filename skip the storage read entirely. A missing map starts at a 1 minute cooldown; a transient failure (timeout, storage error, unparseable map) starts at 15 seconds, so brief storage hiccups recover fast. Each consecutive failure doubles the cooldown, capped at 15 minutes, so a project that never uploads maps converges to a few storage reads per hour per filename instead of one per minute.-- The cooldown clears the moment that filename is uploaded (the upload endpoint invalidates it in-process) or a load succeeds. In a multi-instance deployment, instances other than the one that served the upload retry within their remaining cooldown, at most 15 minutes.-- The negative cache is bounded at 10,000 filenames; expired entries are pruned when the bound is hit.-- Within a single trace, a failed map is attempted **once**, not once per frame, so a 50-frame trace cannot stack fifty timeouts.-- Traceway self-reports the failure into its own monitoring project, throttled to one exception per minute with a count of suppressed occurrences.--## Cache Backends: Memory and Disk--The in-memory cache described above is the default and always present. In both modes, a memory miss first checks object storage for a precompiled [`.tw` resolver](#the-tw-resolver-format) before rebuilding, and every rebuild writes the finished `.tw` back to object storage, so a given map is rebuilt once cluster-wide and every other instance (and every restart) downloads the compiled artifact instead of re-parsing. `SOURCEMAP_CACHE_TYPE=disk` adds a local cache of those `.tw` files in between, which changes what a *memory miss* costs. The full lookup order:--1. **In-memory LRU.** Both modes. A hit is a pure memory lookup.-2. **Local `.tw` file** under `SOURCEMAP_DISK_CACHE_PATH` (disk mode only). The file is memory-mapped and the resolver opens with validation only; on little-endian hosts (amd64, arm64) the token table is used directly from the mapped pages with zero copying or decoding. Counted in `disk.hits`.-3. **`.tw` from object storage.** Both modes. In disk mode it is written to the local directory (atomically, via temp file and rename) and then opened as in step 2; in memory mode it is opened on the heap. Counted in `store_hits`.-4. **Full rebuild** from the `.map` and bundle. Both modes. The finished resolver is serialized to `.tw` and written back to object storage (and, in disk mode, to the local directory). Counted in `builds`.--The local directory is itself an LRU bounded by bytes (`SOURCEMAP_DISK_CACHE_MAX_MB`, default 2048): least recently used `.tw` files are deleted when the cap is exceeded. The directory is scanned at startup, so the cache survives restarts with its recency order approximated from file mtimes; mtimes are refreshed on use at most once per 10 minutes to keep that approximation current without constant metadata writes. A `.tw` file that fails validation (truncated, corrupt, or written by an older format version) is deleted and rebuilt from the original artifacts; this is a recovery path, not an error.--Uploads warm the cache proactively in both modes: after `/api/sourcemaps/upload` stores the files, a background task deletes the stale `.tw` from object storage, evicts the cached resolver, and rebuilds it, so the first exception after a deploy finds a hot cache instead of paying the build.--When to enable it: the memory-only default is right for most deployments. The disk tier pays off when the set of actively-resolving maps is much larger than the memory cap (high eviction traffic): a re-entry becomes a local mmap open measured in microseconds instead of an object storage download, and the token tables live in page cache rather than on the process heap, so resident memory tracks the hot set instead of the cap.--## The `.tw` Resolver Format--Building a resolver is the expensive part of symbolication: parse the `.map` JSON, decode the VLQ `mappings`, parse the bundle, run scope analysis, pre-resolve every enclosing function name. `.tw` is the binary serialization of the *finished* resolver, so opening one skips all of that. It is designed to be memory-mapped and used in place.--All integers are little-endian. The layout:--```-offset size field-0 4 magic "TWSM"-4 4 format version (currently 1)-8 4 token count (N)-12 4 file name count (F)-16 4 function name count (G)-20 4 reserved (0)-24 24 × N token table-... 4 × (F+1) file name offsets-... var file name blob (concatenated UTF-8)-... 4 × (G+1) function name offsets-... var function name blob (concatenated UTF-8)-```--**Token table.** One 24-byte record per source map mapping, six 32-bit fields each: generated line, generated column, original line, original column, file name index, function name index. Lines and columns are stored exactly as the resolver uses them (original line/column already 1-based, generated 0-based), so no arithmetic happens at lookup time. The two indices are signed; `-1` means "no original file" (an unmapped segment) or "no enclosing function". Tokens are sorted by generated position, which is what makes a frame lookup a single binary search over the mapped file. Function names being materialized per token is the key property: scope analysis ran once, at build time, and its output is just an index into the name table.--**String tables.** Each table is `count + 1` offsets followed by one concatenated UTF-8 blob; string `i` spans `blob[offsets[i]:offsets[i+1]]`. Offsets must be monotonically non-decreasing. The names are interned, so a file referenced by ten thousand tokens is stored once.--**Opening.** `OpenTW` validates and does nothing else: magic and version match, every section lies within the file, offsets are monotonic, every token index is in range, and no trailing bytes follow the last table. On a little-endian host where the in-memory token struct matches the on-disk record layout (true on amd64 and arm64), the token table is reinterpreted directly from the mapped bytes: zero copies, zero decoding, and the OS page cache shares it across anything else mapping the same file. The only allocations are the interned strings. On other hosts the tokens are decoded record by record into a fresh slice.--**Versioning.** The format is versioned by a single integer with no migration path, deliberately: a `.tw` is a cache artifact, never the source of truth. Bumping the version makes every existing file fail validation, after which each is lazily rebuilt from its `.map` and bundle.--**Placement.** A `.tw` lives at the map's storage key with the `.map` suffix replaced by `.tw`: `sourcemaps/{projectId}/app.bundle.js.map` compiles to `sourcemaps/{projectId}/app.bundle.js.tw`, and debug-ID artifacts to `sourcemaps/{projectId}/by-debug-id/{debugId}.js.tw`. The local disk cache mirrors the same relative paths under `SOURCEMAP_DISK_CACHE_PATH`.--## Bundle Parsers--Function name resolution (the scope analysis above) requires parsing the minified bundle into an AST. Two parsers are available:--| Parser | Availability | Implementation |-|---|---|---|-| `goja` | always (default) | pure Go, via the [goja](https://github.com/dop251/goja) parser |-| `oxc` | opt-in build | Rust, via the [oxc](https://oxc.rs) parser behind a small C FFI shim |--`goja` ships in every build and needs nothing. It parses the bundle as a script and, when that fails on ESM syntax, neutralizes the module syntax and retries.--`oxc` is substantially faster on large bundles but requires a Rust toolchain at *build* time (the resulting binary is self-contained):--```bash-./scripts/build-oxc-shim.sh # cargo build --release of the FFI shim-cd backend && go build -tags oxc . # links the static library in-```--Select the parser at runtime with `SYMBOLICATOR_PARSER=oxc` (or `goja`). Selecting a parser that was not compiled in fails startup with the list of available parsers, rather than silently falling back.--The parser choice affects **build speed only, never output**: both parsers must produce identical scope transitions, and a parity test asserts oxc against goja across the fixture suite. Since parsing happens only when a resolver is built (and the result is cached, including into `.tw`), the parser matters most for deployments with heavy map churn or with the disk cache disabled. `scripts/benchmark-symbolicator.sh` benchmarks the two side by side.--## Configuration Reference--| Variable | Default | Description |-|----------|---------|-------------|-| `SYMBOLICATOR_PARSER` | `goja` | Bundle parser for function name resolution: `goja` or `oxc` (the latter only in `-tags oxc` builds) |-| `SOURCEMAP_CACHE_TYPE` | `memory` | `memory` for the in-memory LRU only, `disk` to add the local `.tw` tier |-| `SOURCEMAP_DISK_CACHE_PATH` | `./twcache` | Directory for local `.tw` files (disk mode only) |-| `SOURCEMAP_DISK_CACHE_MAX_MB` | `2048` | Byte cap for the local `.tw` directory, LRU-evicted (disk mode only) |-| `SOURCEMAP_CACHE_MAX_ENTRIES` | `200` | Max built resolvers held in memory |-| `SOURCEMAP_CACHE_MAX_BYTES_MB` | `500` | Max estimated in-memory size of all resolvers |--See [Capacity & Self-Monitoring](/server/capacity-monitoring) for sizing guidance.--## Observability--The backend self-reports cache metrics every 30 seconds (see [Capacity Monitoring](/server/capacity-monitoring) for the full operations view):--| Metric | Meaning |-|---|---|-| `traceway.sourcemap.entries` | built resolvers currently in memory |-| `traceway.sourcemap.bytes` | estimated total size of those entries |-| `traceway.sourcemap.negative_entries` | filenames currently under a miss/failure cooldown |-| `traceway.sourcemap.hits.delta` | cache hits since the last tick |-| `traceway.sourcemap.misses.delta` | builds triggered since the last tick |-| `traceway.sourcemap.evictions.delta` | LRU evictions since the last tick |-| `traceway.sourcemap.load_failures.delta` | failed builds (storage error, 5s timeout, unparseable map); each one is a trace stored unsymbolicated |-| `traceway.sourcemap.not_found.delta` | lookups that found no uploaded map for the frame's filename since the last tick |-| `traceway.sourcemap.negative_hits.delta` | frame lookups skipped by an active cooldown since the last tick |-| `traceway.sourcemap.parse_ms` | duration of the most recent resolver build |-| `traceway.sourcemap.store_hits.delta` | memory misses served by a `.tw` fetched from object storage since the last tick (both cache modes) |-| `traceway.sourcemap.builds.delta` | memory misses that required a full rebuild from `.map` + bundle since the last tick (both cache modes) |-| `traceway.sourcemap.disk.entries` / `disk.bytes` | local `.tw` files currently cached and their total size (disk tier only) |-| `traceway.sourcemap.disk.hits.delta` | memory misses served by a local `.tw` file since the last tick (disk tier only) |-| `traceway.sourcemap.disk.evictions.delta` | local `.tw` files evicted by the byte cap since the last tick (disk tier only) |--What healthy looks like: `misses.delta` near zero in steady state (every miss is a storage read plus a rebuild), `load_failures.delta` at zero (anything above zero means minified traces are reaching your issues), and `bytes` comfortably under the cap. A useful alert is `load_failures.delta` max greater than 0 over 5 minutes.--`not_found.delta` is a configuration signal rather than a failure signal: sustained nonzero values for a project that should be symbolicated mean exceptions reference filenames that were never uploaded, most commonly a missing upload step in CI or a `--directory` pointing at the wrong build output. `negative_hits.delta` shows the cooldown doing its job; high values alongside high `not_found.delta` are normal for JS projects that simply do not upload maps.--## Limitations Today--Honest list, in rough order of impact:--1. **Function names require the bundle.** The current upload CLI sends it automatically, but map-only uploads (older CLI versions, or maps whose sibling bundle was not in the build output) resolve locations without names.-2. **Symbolication is ingest-only.** Maps uploaded after an event arrived do not improve that event.-3. **Filename matching collides on stable names.** Without debug IDs, two bundles with the same filename in different directories collide, and the most recent upload wins. Content-hashed bundle names (the default in Vite, Next, Angular, and most bundlers) avoid this in practice, and [debug IDs](/client/js-sdk/debug-ids) eliminate it entirely by addressing maps by build content instead of by name.-4. **The 5 second load budget trades completeness for latency.** A map that takes longer to fetch produces an unsymbolicated trace (recorded in `load_failures.delta`) rather than a slow ingest.-5. **Failure cooldowns can delay recovery on other instances.** Uploading a map clears its cooldown instantly on the instance that handled the upload; in multi-instance deployments, the rest retry within their remaining cooldown, at most 15 minutes.-6. **Outages split grouping transiently.** Unsymbolicated and symbolicated versions of the same error hash differently.-7. **Maps with `null` sources are ambiguous.** Frames resolve as `<unknown>`, though line, column, and name still resolve.-8. **50 resolved frames per trace.** Deeper frames stay minified.-9. **Module-level code has no name.** Errors thrown outside any function (Hermes/Metro global prologue, top-level module code) resolve location-only rather than being labeled `<global>`.--## How We Verify It--The resolver is tested for parity against [getsentry/symbolic](https://github.com/getsentry/symbolic), the symbolication engine behind Sentry, using its own fixture suite (webpack, Metro, Hermes, preact, inlined functions, null-source maps). Every fixture frame's expected file, line, column, and name is asserted exactly, so any drift fails the build.--All frames match symbolic on **location**. With scope analysis, names now match too for frames inside a function, including the cases the old text-scanning heuristic got wrong (preact's `createElement` and `assign` among them). The remaining name gap is module-level code, where symbolic reports `<global>` and Traceway reports no name (limitation 9 above).--Two more invariants are tested directly: the `.tw` format round-trips (a resolver serialized and reopened answers every lookup identically, including from a memory-mapped file), and the `oxc` parser produces scope output identical to `goja` across the fixture suite, so the parser choice can never change symbolication results.--## Related Pages--- [Source Maps](/client/js-sdk/sourcemap-upload): uploading maps from CI-- [Issues](/learn/issues): grouping, lifecycle, and archiving-- [Capacity Monitoring](/server/capacity-monitoring): cache sizing and alerting+<Redirect to="/symbolicator/javascript" />diff --git a/docs/pages/learn/symbolicator-library.mdx b/docs/pages/learn/symbolicator-library.mdxindex 328cdb76..c4688e0b 100644--- a/docs/pages/learn/symbolicator-library.mdx+++ b/docs/pages/learn/symbolicator-library.mdx@@ -1,201 +1,3 @@-# Symbolicator as a Go Library+import Redirect from "../../components/Redirect";-import { Callout } from "nextra/components";--Traceway's JS symbolicator is an importable Go library. Everything the ingest pipeline uses to turn minified stack traces back into source locations (source map parsing, bundle scope analysis for function names, the `.tw` resolver format, and the mmap-backed disk cache) lives in public packages of the backend module, so you can use the engine in your own tooling without running Traceway at all.--It is pure Go by default: no cgo, no C libraries, works in a `scratch` image.--If you want this functionality inside an OpenTelemetry Collector pipeline instead of your own code, use the prebuilt [collector processor](/learn/collector-symbolicator). For how the engine works internally, see [Symbolication (JS)](/learn/symbolication-js).--## Installation--```bash-go get github.com/tracewayapp/traceway/backend@latest-```--<Callout type="info">- The symbolicator packages first ship in backend release `v1.8.0`, so- `@latest` resolves to a version that has them. The import paths below are- stable public packages; everything under `backend/app/symbolicator` is- importable.-</Callout>--| Package | Import path | Purpose |-| ------- | ----------- | ------- |-| `symbolicator` | `github.com/tracewayapp/traceway/backend/app/symbolicator` | The resolver: source map + bundle in, original locations out |-| `jsstack` | `github.com/tracewayapp/traceway/backend/app/symbolicator/jsstack` | Browser stack trace parsing (V8, Firefox, Safari formats) |-| `scopes` | `github.com/tracewayapp/traceway/backend/app/symbolicator/scopes` | Bundle parser selection (goja default, oxc optional) |-| `twcache` | `github.com/tracewayapp/traceway/backend/app/symbolicator/twcache` | Mmap-backed disk cache of compiled `.tw` resolvers |-| `otelprocessor` | `github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor` | The [OTel Collector processor](/learn/collector-symbolicator) wrapping the engine |--## Resolving a Single Frame--Build a resolver from a source map and (optionally) its minified bundle, then look positions up. The bundle is what enables function names through scope analysis; pass `nil` and you still get files, lines, and columns.--```go-package main--import (- "fmt"- "os"-- "github.com/tracewayapp/traceway/backend/app/symbolicator"-)--func main() {- mapBytes, err := os.ReadFile("dist/app.min.js.map")- if err != nil {- panic(err)- }- bundleBytes, _ := os.ReadFile("dist/app.min.js") // optional, enables function names-- resolver, err := symbolicator.NewResolver(mapBytes, bundleBytes)- if err != nil {- panic(err)- }-- // Lookup takes zero-based generated positions. A browser frame like- // "app.min.js:1:13337" is line 0, column 13336 here.- frame, ok := resolver.Lookup(0, 13336)- if !ok {- fmt.Println("no mapping at this position")- return- }- fmt.Printf("%s:%d:%d", frame.File, frame.Line, frame.Col) // src/render.ts:42:7- if frame.Fn != "" {- fmt.Printf(" in %s()", frame.Fn)- }- fmt.Println()-}-```--The coordinate conventions, precisely:--- `Lookup(genLine, genCol uint32)` takes **zero-based** positions, matching the source map spec's internal encoding.-- Browser stack traces print **one-based** positions, so subtract 1 from each before calling `Lookup`.-- The returned `StackTraceFrame` carries **one-based** `Line` and `Col`, ready to print.-- `Fn` is the enclosing original function name, or `""` when the bundle was not provided or the position is not inside a known scope.--## Symbolicating a Whole Stack Trace--`jsstack.ParseFrames` parses the raw `error.stack` formats browsers actually produce: V8 (`at fn (url:line:col)`, including `async`, `new`, `[as alias]`, and `eval` frames), Firefox, and Safari (`fn@url:line:col`). It returns frames with the one-based positions as printed.--```go-package main--import (- "fmt"-- "github.com/tracewayapp/traceway/backend/app/symbolicator"- "github.com/tracewayapp/traceway/backend/app/symbolicator/jsstack"-)--func symbolicateStack(rawStack string, resolverFor func(url string) *symbolicator.Resolver) {- for _, f := range jsstack.ParseFrames(rawStack) {- r := resolverFor(f.URL)- if r == nil {- continue- }- frame, ok := r.Lookup(f.Line-1, f.Col-1)- if !ok {- continue- }- fmt.Printf("%s at %s:%d:%d\n", f.Function, frame.File, frame.Line, frame.Col)- }-}-```--`resolverFor` is yours to implement: typically a map from bundle URL basename to the resolver built from that bundle's artifacts.--If you need Traceway's canonical frame format (function name on one line, ` file:line:col` on the next, the format described in [Symbolication (JS)](/learn/symbolication-js#the-frame-format)), use `jsstack.Canonicalize`:--```go-canonical, converted := jsstack.Canonicalize(rawStack)-```--It returns the input unchanged (`converted == false`) when the trace is not a recognizable browser stack, so it is safe to call on arbitrary text, including Go panics and already-canonical traces.--## Caching Compiled Resolvers: the `.tw` Format--Parsing a large source map and analyzing its bundle takes time you do not want to spend twice. A resolver serializes to Traceway's compact binary `.tw` format ([format details](/learn/symbolication-js#the-tw-resolver-format)) and loads back without reparsing anything:--```go-data := resolver.MarshalTW()-// persist data wherever you like, then later:-resolver2, err := symbolicator.OpenTW(data)-```--`OpenTW` validates the input fully and, when the byte slice is memory-mapped, resolves lookups directly against the mapping with zero copying. That is exactly what `twcache` does for you:--```go-package main--import (- "github.com/tracewayapp/traceway/backend/app/symbolicator"- "github.com/tracewayapp/traceway/backend/app/symbolicator/twcache"-)--// 2 GiB LRU of .tw files under /var/cache/tw; least recently used evicted first.-func newCache() (*twcache.Cache, error) {- return twcache.New("/var/cache/tw", 2<<30, nil)-}--func cachedResolver(cache *twcache.Cache, name string, mapBytes, bundleBytes []byte) (*symbolicator.Resolver, error) {- if r, err := cache.Open(name); err == nil {- return r, nil // mmap hit- }- built, err := symbolicator.NewResolver(mapBytes, bundleBytes)- if err != nil {- return nil, err- }- if r, err := cache.Write(name, built.MarshalTW()); err == nil {- return r, nil // persisted and mmapped- }- return built, nil // disk failed, serve the in-memory resolver-}-```--What `twcache` handles for you:--- Names are slash-separated paths relative to the cache directory and must stay inside it; subdirectories are fine (`project-a/app.min.js.tw`).-- Writes are atomic (temp file + rename), so a crash never leaves a partial `.tw` behind.-- Corrupt files are deleted on `Open` so your rebuild path replaces them.-- The LRU survives restarts: the directory is scanned on `New` and ordered by file mtime.-- `Remove(name)` invalidates after a re-deploy; `Stats()` reports entries, bytes, hits, and evictions.-- Resolvers stay valid after eviction deletes their file; the mapping is released only when the resolver is garbage collected.--`resolver.ApproxSize()` reports the retained footprint if you want to bound an in-memory cache on top.--## Choosing the Bundle Parser--Function-name resolution parses the minified bundle into scopes. Two parsers produce identical output (a parity test asserts this across the fixture suite, see [Bundle Parsers](/learn/symbolication-js#bundle-parsers)):--- **goja** (default): pure Go, zero setup.-- **oxc**: a Rust parser behind cgo, several times faster on large bundles. The `-tags oxc` build links a static library from the `scopes` package's own source directory (`oxc-shim/target/release/liboxc_shim.a`), which the read-only module cache that `go get` populates never contains. To enable it, build against a writable checkout: clone the repo, run `scripts/build-oxc-shim.sh` once, add a `replace github.com/tracewayapp/traceway/backend => /path/to/traceway/backend` directive to your `go.mod` (or vendor the module and build the shim inside `vendor/`), then compile with `-tags oxc`.--```go-import "github.com/tracewayapp/traceway/backend/app/symbolicator/scopes"--if err := scopes.SetParser("oxc"); err != nil {- // not compiled in; still on goja-}-```--`scopes.AvailableParsers()` lists what your binary was built with. The parser affects resolver build speed only, never output, so `.tw` files are interchangeable between the two.--## API Summary--| Symbol | Signature | Notes |-| ------ | --------- | ----- |-| `symbolicator.NewResolver` | `(sourceMap, bundle []byte) (*Resolver, error)` | `bundle` may be `nil` (no function names) |-| `(*Resolver).Lookup` | `(genLine, genCol uint32) (StackTraceFrame, bool)` | zero-based in, one-based out |-| `symbolicator.StackTraceFrame` | `{File string; Line, Col uint32; Fn string}` | `Fn` may be empty |-| `(*Resolver).MarshalTW` | `() []byte` | serialize to `.tw` |-| `symbolicator.OpenTW` | `(data []byte) (*Resolver, error)` | validates fully; zero-copy over mmapped data |-| `(*Resolver).ApproxSize` | `() int64` | retained footprint for cache accounting |-| `jsstack.ParseFrames` | `(trace string) []Frame` | `Frame{Function, URL string; Line, Col uint32}`, one-based |-| `jsstack.Canonicalize` | `(trace string) (string, bool)` | passthrough on non-browser input |-| `scopes.SetParser` | `(name string) error` | `"goja"` or `"oxc"` (with `-tags oxc`) |-| `twcache.New` | `(dir string, maxBytes int64, warn func(error)) (*Cache, error)` | scans `dir`, LRU bounded by `maxBytes` |-| `(*twcache.Cache).Open` / `.Write` / `.Remove` / `.Stats` | | mmap-backed `.tw` files by relative name |+<Redirect to="/symbolicator/library" />diff --git a/docs/pages/server/capacity-monitoring.mdx b/docs/pages/server/capacity-monitoring.mdxindex 2523aa64..8e843225 100644--- a/docs/pages/server/capacity-monitoring.mdx+++ b/docs/pages/server/capacity-monitoring.mdx@@ -95,7 +95,7 @@ Lookups that find no map (or fail to load one) are negative-cached per filenameUpgrading from 1.7? The flat storage layout is new in 1.8 and existing maps are migrated automatically at startup; see [Upgrading to 1.8](/server/upgrade-1-8).-In both modes, a memory miss first tries a precompiled `.tw` resolver from object storage before re-parsing the map and bundle, and rebuilds happen once cluster-wide because the resulting `.tw` is written back to storage. Optionally, `SOURCEMAP_CACHE_TYPE=disk` adds a local disk tier of those `.tw` files between the memory cache and object storage, so a miss becomes a local mmap open instead of a storage download. See [the `.tw` format](/learn/symbolication-js#the-tw-resolver-format) and [cache backends](/learn/symbolication-js#cache-backends-memory-and-disk) for the mechanics.+In both modes, a memory miss first tries a precompiled `.tw` resolver from object storage before re-parsing the map and bundle, and rebuilds happen once cluster-wide because the resulting `.tw` is written back to storage. Optionally, `SOURCEMAP_CACHE_TYPE=disk` adds a local disk tier of those `.tw` files between the memory cache and object storage, so a miss becomes a local mmap open instead of a storage download. See [the `.tw` format](/symbolicator#the-tw-resolver-format) and [cache tiers](/symbolicator#cache-tiers) for the mechanics.| Variable | Default | Description ||----------|---------|-------------|@@ -104,7 +104,7 @@ In both modes, a memory miss first tries a precompiled `.tw` resolver from objec| `SOURCEMAP_CACHE_TYPE` | `memory` | `disk` adds the local `.tw` tier || `SOURCEMAP_DISK_CACHE_PATH` | `./twcache` | Directory for local `.tw` files (disk mode only) || `SOURCEMAP_DISK_CACHE_MAX_MB` | `2048` | Byte cap for the local `.tw` directory, LRU-evicted (disk mode only) |-| `SYMBOLICATOR_PARSER` | `goja` | Bundle parser for function name resolution; `oxc` is faster on large bundles but requires a `-tags oxc` build (see [Bundle parsers](/learn/symbolication-js#bundle-parsers)) |+| `SYMBOLICATOR_PARSER` | `goja` | Bundle parser for function name resolution; `oxc` is faster on large bundles but requires a `-tags oxc` build (see [Bundle parsers](/symbolicator/javascript#bundle-parsers)) |Sizing guidance:diff --git a/docs/pages/server/storage.mdx b/docs/pages/server/storage.mdxindex 5d4409d2..960c7064 100644--- a/docs/pages/server/storage.mdx+++ b/docs/pages/server/storage.mdx@@ -7,7 +7,7 @@ What lives in blob storage:| Artifact | Keys | Written by ||----------|------|-----------|| Source maps and bundles | `sourcemaps/{projectId}/{filename}` and `sourcemaps/{projectId}/by-debug-id/{debugId}.js[.map]` | [`POST /api/sourcemaps/upload`](/client/js-sdk/sourcemap-upload), typically from CI |-| Compiled `.tw` resolvers | same keys with the `.map`/`.js` suffix replaced by `.tw` | the [symbolication cache](/learn/symbolication-js#cache-backends-memory-and-disk), automatically |+| Compiled `.tw` resolvers | same keys with the `.map`/`.js` suffix replaced by `.tw` | the [symbolication cache](/symbolicator#cache-tiers), automatically || Session recording segments | `recordings/{projectId}/...` | the [recording uploader](/server/capacity-monitoring) || AI trace payloads | `ai-traces/{projectId}/...` | OTLP ingest |@@ -76,5 +76,5 @@ Source maps are retained indefinitely in both modes: the most recent upload of e## Related Pages- [Source Maps](/client/js-sdk/sourcemap-upload): uploading maps from CI-- [Symbolication (JS)](/learn/symbolication-js): how `.tw` resolvers and the cache tiers use this storage+- [Symbolication](/symbolicator): how `.tw` resolvers and the cache tiers use this storage- [SQLite](/server/sqlite): single-container deployment with the same storage optionsdiff --git a/docs/pages/server/upgrade-1-8.mdx b/docs/pages/server/upgrade-1-8.mdxindex 9198e83f..33976e34 100644--- a/docs/pages/server/upgrade-1-8.mdx+++ b/docs/pages/server/upgrade-1-8.mdx@@ -47,6 +47,6 @@ Upgrade `@tracewayapp/sourcemap-upload` together with the backend:## Related pages-- [Symbolication](/learn/symbolication-js): the full resolution pipeline in 1.8+- [Symbolication](/symbolicator/javascript): the full resolution pipeline in 1.8- [Source Maps](/client/js-sdk/sourcemap-upload): CLI usage and CI examples- [Capacity & Self-Monitoring](/server/capacity-monitoring): cache sizing and the symbolication metricsdiff --git a/docs/pages/symbolicator/_meta.json b/docs/pages/symbolicator/_meta.jsonnew file mode 100644index 00000000..cea4972b--- /dev/null+++ b/docs/pages/symbolicator/_meta.json@@ -0,0 +1,8 @@+{+ "index": "Architecture",+ "javascript": "JavaScript",+ "dart": "Dart",+ "performance": "Performance",+ "opentelemetry": "OpenTelemetry",+ "library": "Library"+}diff --git a/docs/pages/symbolicator/dart.mdx b/docs/pages/symbolicator/dart.mdxnew file mode 100644index 00000000..eec5fb31--- /dev/null+++ b/docs/pages/symbolicator/dart.mdx@@ -0,0 +1,156 @@+# Dart++For Dart, the debug info is the build's `.symbols` file. Obfuscated Flutter release builds strip names and line tables out of the binary, so a crash reports against raw machine code. The frames carry nothing but an offset into a snapshot section:++```+*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***+pid: 1234, tid: 5678, name 1.ui+build_id: '8a5f0c2e1b7d4f93a6e0c8b1d2f3a4b5'+os: android arch: arm64 comp: yes sim: no+#00 abs 7f1c2a0040 virt 0000000000241040 _kDartIsolateSnapshotInstructions+0x12340+#01 abs 7f1c2a0a10 virt 0000000000241a10 _kDartIsolateSnapshotInstructions+0x12d10+```++With the build's `.symbols` file uploaded, that resolves into named source frames, inline calls expanded:++```+#0 UserRepository.fetch (package:app/data/user_repository.dart:88:14)+#1 _ProfilePageState.build.<anonymous closure> (package:app/ui/profile_page.dart:142:20)+#2 StatelessElement.build (package:flutter/src/widgets/framework.dart:5678:28)+```++This page covers the Dart-specific mechanics in the order you meet them: when a symbol upload is needed, how to set it up and upload with the SDK, the upload API, and then how a non-symbolic trace is recognized and resolved into source frames. For when symbolication runs, the cache, and the `.tw` format, see [Architecture](/symbolicator).++## Obfuscated builds and `.symbols` files++A plain `flutter build --release` keeps enough symbol information that crash traces are already readable (function names and `file:line`), and the SDK reports them as-is. You only need to upload symbols when you harden a build with **`--obfuscate`** and/or **`--split-debug-info`**:++- **`--obfuscate`** renames identifiers and strips names out of the binary, which shrinks the app and protects your source. Release traces then arrive as bare instruction offsets.+- **`--split-debug-info=<dir>`** writes the stripped debug information into a separate `.symbols` file per architecture, so it ships to you instead of inside the app.++```bash+flutter build apk --release --obfuscate --split-debug-info=build/symbols+```++This writes ELF files like `app.android-arm64.symbols`, one per architecture you ship (`arm64`, `arm`, `x64`). Each is a stripped ELF carrying DWARF debug info and a `.note.gnu.build-id` note, plus the `_kDartIsolateSnapshotInstructions` and `_kDartVmSnapshotInstructions` symbols that anchor the snapshot sections. The engine reads the build ID from that note and the section base addresses from those symbols; that's everything a lookup needs.++Apple platforms are the exception: Mach-O builds carry no GNU build-id note, so for iOS and macOS the debug ID is the build's Mach-O UUID instead (handled for you below).++## Uploading symbols with the Flutter SDK++The [`traceway`](https://pub.dev/packages/traceway) package ships an uploader that finds the `.symbols` files, derives each one's architecture and debug ID, and posts them. Configure it once, then run it on every release.++**One-time setup.** Add a `traceway:` block to your app's `pubspec.yaml`:++```yaml+traceway:+ url: https://your-traceway-host # omit on Traceway Cloud+ # upload_token: ... # prefer the env var, especially in CI+```++The upload token is your project's **upload token** from the dashboard, the same one used for JavaScript source maps. It is **not** the runtime token in your `Traceway.run()` connection string.++**Per release.** Build with the symbol flags, then run the uploader:++```sh+flutter build apk --release --obfuscate --split-debug-info=build/symbols++TRACEWAY_UPLOAD_TOKEN=your-token dart run traceway:upload_symbols+```++The uploader reads the URL and token from config or environment and auto-discovers `build/symbols`, so no flags are required. Each value resolves from a CLI flag first, then an environment variable, then `pubspec.yaml`:++| Value | Flag | Env var | `pubspec.yaml` key | Default |+|---|---|---|---|---|+| Upload token | `--token` | `TRACEWAY_UPLOAD_TOKEN` | `upload_token` | required |+| Instance URL | `--url` | `TRACEWAY_URL` | `url` | Traceway Cloud |+| Symbols directory | `--symbols-dir` | | `symbols_dir` | `build/symbols` |+| Apple app bundle | `--app` | | `app` | auto-discovered |++Pass `--dry-run` to resolve the config and list what would be uploaded without sending. Symbols are unique to each build, so upload on every release: a crash can only be symbolicated against the exact build it came from.++On Android the debug ID is read straight from each file's build-id note. On iOS and macOS the file doesn't carry one, so the uploader reads the Mach-O UUID from the built `.app` (the same value the runtime reports), auto-discovering it under `build/`. Point it explicitly when needed:++```sh+dart run traceway:upload_symbols --app build/macos/Build/Products/Release/YourApp.app+```++## The upload API++The uploader posts each file to a dedicated endpoint. This is the wire protocol it speaks (and why Apple builds need the SDK uploader rather than a raw HTTP call: the `debug_id` must come from the compiled `.app`):++```+POST /api/symbols/upload+Authorization: Bearer <upload token>+Content-Type: multipart/form-data+```++| Field | Required | Notes |+|---|---|---|+| `files` | yes | One or more `.symbols` files. Non-`.symbols` entries are ignored. 200 MB per file. |+| `arch` | sometimes | The architecture token (`arm64`, `arm`, `x64`, `ia32`). Optional when the filename ends in `-<arch>.symbols`, which Flutter's output already does. |+| `debug_id` | sometimes | Required only when the file has no build-id note (Apple). When the file does have one, this must match it if provided. |++The build ID is normalized (lowercased, hex digits only) and the arch too (`x86_64`/`amd64` collapse to `x64`, `aarch64` to `arm64`). The stored key is:++```+dartsymbols/{projectId}/{debugId}-{arch}.symbols+```++Because the key is content-addressed by build ID, releases never collide, and re-uploading the same build is idempotent.++## How a Dart trace is recognized++Dart symbolication keys off a **non-symbolic** trace, identified by frame lines of this shape:++```+#00 abs 7f1c2a0040 virt 0000000000241040 _kDartIsolateSnapshotInstructions+0x12340+```++Each frame names a snapshot section, `_kDartIsolateSnapshotInstructions` (the app's own code) or `_kDartVmSnapshotInstructions` (the Dart VM), and an offset into it. The parser pulls three things from the surrounding text:++| Field | Source line | Used for |+|---|---|---|+| build ID | `build_id: '...'` | matching the trace to an uploaded `.symbols` |+| architecture | `os: ... arch: ...` | picking the right per-arch `.symbols` |+| frames | `#N ... _kDart...Instructions+0xOFFSET` | the PC offsets to resolve |++A trace that is already symbolic, or carries no recognizable Dart frames, passes through untouched.++## How an offset resolves++The build's `.symbols` is compiled into a range-lookup resolver (the [`.tw`](/symbolicator#the-tw-resolver-format) form). Each frame then resolves through these steps:++1. **Compute the program counter.** The frame's offset is added to the base address of its section (isolate or VM), recovered from the snapshot instruction symbols. That absolute PC is what the lookup keys on.+2. **Look up the PC.** A binary search over the resolver's range table finds the PC's entry and its span of frames. DWARF inline information means one machine address can stand for several source frames, so a single `#N` offset can expand into a chain of inlined calls, innermost first.+3. **Render.** Resolved frames print as `#N Function (file:line:col)`. A frame with no match (a PC outside any known range, or symbols that weren't uploaded) keeps its raw form, `#N _kDartIsolateSnapshotInstructions+0xOFFSET`, so the trace is never worse than it arrived. A maximum of **50 frames** are emitted, inline expansions included.++If no symbols are found for the build, every frame falls back to its raw offset form.++## The flat format++Where the JavaScript `.tw` maps generated positions to original positions, the Dart `.tw` maps **PC ranges to inline frame spans**. Building it flattens the DWARF debug info into a structure tuned for the lookup above:++- A header carrying the isolate and VM base addresses and the table sizes.+- A range table, sorted by PC, where each entry covers a contiguous PC range and points at a run of frames (more than one when calls were inlined).+- A frame table of `(file, line, column, function)` records, with file and function names interned.++The general properties (memory-mapped, zero-copy on little-endian hosts, a versioned cache artifact rebuilt from the original debug info) are the same as every `.tw`; see [Architecture](/symbolicator#the-tw-resolver-format).++## How it differs from JavaScript++| | JavaScript | Dart |+|---|---|---|+| Raw artifact | source map + minified bundle | `.symbols` ELF (DWARF) |+| Frame input | file, line, column | PC offset into a snapshot section |+| Keyed by | filename or debug ID | build ID + architecture |+| Function names | bundle scope analysis | DWARF, directly |+| One frame in | one frame out | one *or more* frames out (inline expansion) |++The architecture dimension is the practical difference to remember: a single JavaScript build has one map per bundle, but a single Flutter build ships several `.symbols` files, and a trace only resolves against the one matching the device's arch. Upload all of them.++## Related pages++- [Flutter SDK](/client/flutter): capturing exceptions from a Flutter app+- [Architecture](/symbolicator): when symbolication runs, the cache tiers, and the `.tw` format+- [Performance](/symbolicator/performance): cache sizing and failure handlingdiff --git a/docs/pages/symbolicator/index.mdx b/docs/pages/symbolicator/index.mdxnew file mode 100644index 00000000..bc65d10b--- /dev/null+++ b/docs/pages/symbolicator/index.mdx@@ -0,0 +1,72 @@+# Architecture++Symbolication turns a minified or stripped production stack trace back into the source locations your team wrote. The runtime only ever reports positions into compiled output: a column in a shipped bundle, a program counter in stripped machine code. The debug info your build emitted is what maps those positions back to a file, line, and function. The symbolicator is the engine that does that mapping, and this page is how it fits together, independent of which language produced the trace.++The same engine runs three ways:++- **At ingest**, inside Traceway's `/api/report` and OTLP endpoints, so issues are stored already symbolicated.+- **As an [OpenTelemetry Collector processor](/symbolicator/opentelemetry)**, so traces are rewritten before they reach any backend.+- **As an importable [Go library](/symbolicator/library)**, so you can call it from your own tooling.++## When and where symbolication runs++Symbolication happens **once, at ingest**. A report arrives, each stack trace is resolved frame by frame, and the **resolved** trace is what gets hashed for grouping and stored. Nothing is re-resolved when you view an issue later.++The trade-off is that stored traces are immutable snapshots of the symbolication quality at the moment they arrived. Uploading better debug info improves future events, not past ones.++This is dispatched by the trace, not configured per project: a browser exception resolves against source maps, a Flutter exception against its symbols, and the engine picks the path from the SDK language and the shape of the trace. The collector processor and the library do the same work at a different point in the pipeline.++## The pipeline++Whatever the language, resolution is four steps:++1. **Fetch the raw debug info** for the build from a store.+2. **Compile it into a resolver** and serialize that to a [`.tw` file](#the-tw-resolver-format). This is the expensive step, and it happens once per build artifact.+3. **Cache the `.tw`** so later lookups skip the compile.+4. **Look up each frame** against the resolver and rewrite it.++Building is slow and happens once per artifact. Looking up is a binary search and happens once per frame. The `.tw` format is what lets those two costs live in different places, and even different processes.++## The `.tw` resolver format++Every language ships debug info in its own shape, but it all answers one question: given a position in the compiled output, what source location and function produced it? The engine compiles each shape into the same kind of artifact, a `.tw` file, built for fast range lookups and designed to be memory-mapped and used in place.++The structure is the same regardless of where the debug info came from:++- A **header** with a magic number, a format version, and the table sizes.+- A **range table** over the address space the runtime reports (a position in a generated file, a program counter in a code section), sorted by start. Each range points at the resolved frames it covers: file, line, column, and function. One range can carry several frames, because a single compiled address can stand for a chain of inlined calls.+- **Interned string tables** for file and function names, so a name referenced across thousands of ranges is stored once.++Because the ranges are sorted, a lookup is a single binary search. Because the layout is fixed and little-endian, opening a `.tw` validates its structure and then reads straight from the mapped pages, with no copying or decoding, and the OS page cache shares those pages across every process that maps the same file. Compiling the resolver (parsing the debug info, computing every range, interning every name) runs once at build time; opening the compiled result skips all of it.++A `.tw` is a cache artifact, never the source of truth. It's versioned by a single integer with no migration path: bump the version and every existing file fails validation and is lazily rebuilt from its original debug info. Each language has its own `.tw` encoding tuned to its debug format; the per-language specifics are on the [JavaScript](/symbolicator/javascript) and [Dart](/symbolicator/dart) pages.++## Cache tiers++A resolver is expensive to build and cheap to keep, so the engine caches the compiled `.tw`, not the raw debug info. A lookup walks the tiers from fastest to slowest:++1. **In-memory LRU.** Always present. A hit is a pure memory lookup.+2. **Local `.tw` file** (disk tier only). Memory-mapped and opened with validation; on little-endian hosts the tables are used straight from the mapped pages with zero copying.+3. **`.tw` from object storage.** A compiled artifact built earlier, by another instance or before a restart. In disk mode it's written to the local directory and then mapped; in memory mode it's opened on the heap.+4. **Full rebuild** from the raw debug info. The finished resolver is serialized to `.tw` and written back to object storage, so an artifact is compiled once cluster-wide and every other instance downloads the compiled form instead of re-parsing.++Concurrent requests for the same key are deduplicated: the first builds, the rest park and receive the same resolver. The disk directory is itself an LRU bounded by bytes, survives restarts (it's scanned at startup), and deletes any `.tw` that fails validation so the rebuild path replaces it.++Whether the disk tier earns its keep depends on your corpus size and churn. That's a tuning decision, covered with numbers on [Performance](/symbolicator/performance).++## The store++The store holds the raw debug info, addressed by a deterministic key, behind a single interface: fetch bytes for a key. It has several backends:++- **Object storage** (S3 or local disk) in Traceway's own ingest path.+- **`file_store`, `s3_store`, or `gcs_store`** in the [collector processor](/symbolicator/opentelemetry#populating-the-source-map-store).++Raw artifacts are fetched on demand and never kept on local disk by the engine. When a backend is S3 or GCS, the artifact is pulled into memory, compiled into a `.tw`, and the raw bytes are dropped. The only thing that lands on local disk is the compiled `.tw`, and only when the [disk cache tier](#cache-tiers) is enabled.++## Where to go next++- **[JavaScript](/symbolicator/javascript)** — source maps and bundle scope analysis.+- **[Dart](/symbolicator/dart)** — stripped Flutter traces and DWARF.+- **[Performance](/symbolicator/performance)** — memory vs disk cache, sizing, benchmarks, and the metrics to watch.+- **[OpenTelemetry](/symbolicator/opentelemetry)** — running the engine as a collector processor.+- **[Library](/symbolicator/library)** — calling the engine from your own Go code.diff --git a/docs/pages/symbolicator/javascript.mdx b/docs/pages/symbolicator/javascript.mdxnew file mode 100644index 00000000..cfcf3dde--- /dev/null+++ b/docs/pages/symbolicator/javascript.mdx@@ -0,0 +1,174 @@+# JavaScript++For JavaScript, the debug info is a source map plus the minified bundle it was built from. Browsers report errors against the shipped bundle, so without symbolication an exception looks like this:++```+TypeError: Cannot read properties of undefined (reading 'name')+anonymous()+ app.bundle.js:1:48211+anonymous()+ app.bundle.js:1:13377+```++With the map uploaded, Traceway resolves it to this:++```+TypeError: Cannot read properties of undefined (reading 'name')+renderUserCard()+ src/components/UserCard.tsx:42:17+handleClick()+ src/pages/Profile.tsx:108:5+```++This page covers the JavaScript-specific mechanics: how a frame is parsed, how it resolves against a source map, and how the minified bundle recovers function names. For when symbolication runs, the cache, and the `.tw` format, see [Architecture](/symbolicator). For uploading maps, see [Source Maps](/client/js-sdk/sourcemap-upload).++## The frame format++The JS SDK does not send the browser's raw `error.stack` string. Stack formats are not standardized: V8 (Chrome, Edge, Hermes) emits ` at funcName (file:line:col)`, while Firefox and JavaScriptCore (Safari) emit `funcName@file:line:col`. The SDK parses both families and normalizes every frame into a canonical two-line wire format: a function name line ending in `()`, then a location line indented by four spaces:++```+anonymous()+ app.bundle.js:1:48211+```++The resolver recognizes location lines with a single regex:++```+^(\s{4})(.+):(\d+):(\d+)$+```++Anything that doesn't match (the error message, the name lines, blank lines) passes through untouched. This is the first invariant of the pipeline: **the resolver can only rewrite a line or leave it exactly as it was**. There is no failure mode that drops or corrupts a frame.++## The resolution pipeline++For each location line, in order:++### 1. Find the right source map++**By debug ID first.** If the exception payload carries a `debugIds` entry for the frame's file (injected at build time by [`@tracewayapp/bundler-plugin`](/client/js-sdk/debug-ids)), the map is addressed at `sourcemaps/{projectId}/by-debug-id/{debugId}.js.map` and the bundle at the same key without `.map`. This is content-addressed matching: the ID was embedded into the bundle and its map by the build, so the frame can never resolve against a map from a different build, regardless of filenames, CDNs, or concurrent deploys. If no artifact with that debug ID was uploaded, resolution falls back to filename matching below.++**By filename otherwise.** The frame's file name is reduced to its basename (any query string or fragment stripped first), and the map is addressed in object storage at a deterministic key:++| Frame file | Storage key |+|---|---|+| `app.bundle.js` | `sourcemaps/{projectId}/app.bundle.js.map` |+| `https://cdn.example.com/assets/app.bundle.js` | `sourcemaps/{projectId}/app.bundle.js.map` |+| `app.bundle.js?v=abc123` | `sourcemaps/{projectId}/app.bundle.js.map` |++The minified bundle, when the upload CLI found one next to the map, lives at the same key without the `.map` suffix and feeds function name resolution (below).++No map in storage: the line passes through unchanged, and that filename enters a miss cooldown so subsequent exceptions skip the storage read entirely (see [Performance](/symbolicator/performance#when-loading-fails)).++### 2. Get the resolver++The parsed lookup structure comes from the [cache tiers](/symbolicator#cache-tiers). First use pays a storage read plus a parse (or a memory-mapped [`.tw`](/symbolicator#the-tw-resolver-format) open, which skips the parse); everything after is a memory lookup.++### 3. Look up the position++Browser stack traces use 1-based columns; the source map spec uses 0-based. The resolver subtracts 1 before the lookup and adds 1 back when printing. This off-by-one matters more than it sounds: minified bundles put the entire program on line 1, so being one column off can land on a *different token entirely* and resolve to the wrong original file.++Here is a real lookup, taken verbatim from our test fixtures. The original file:++```js+// built with: terser -c -m --module original.js --source-map includeSources+function abcd() {}+export default abcd;+```++terser renames `abcd` to `t` and emits:++```js+function t(){}export default t;+```++with this source map:++```json+{+ "version": 3,+ "names": ["abcd"],+ "sources": ["tests/fixtures/simple/original.js"],+ "sourcesContent": ["...the original file, embedded..."],+ "mappings": "AACA,SAASA,oBACMA"+}+```++A frame pointing at `minified.js:1:11` (the `t` in `function t`) resolves through the `mappings` (delta-encoded VLQ segments of generated position, source index, original position, name index) to `tests/fixtures/simple/original.js:2:10`, with the name token `abcd`.++### 4. Rewrite the lines++The location line becomes `original-file:line:column` (same indentation). If a function name was resolved, the *name line directly above it* (the `anonymous()` line) is rewritten to `abcd()`.++If the source map carries `"sources": [null]` entries (older uglify pipelines), the file name is rendered as `<unknown>` but the line, column, and name still resolve.++A maximum of **50 frames** per trace are resolved; deeper frames pass through minified.++## Function names: scope analysis++Locations come straight from the source map and are exact. Function names are harder, because a source map's `names` token at a position is the identifier *at that token*, not the name of the *enclosing function* that a stack trace conventionally shows. Getting the enclosing function right requires scope analysis: parsing the minified bundle into an AST and mapping positions to function scopes. This is the same approach Sentry's symbolic takes, and it's why the upload CLI sends the minified bundle alongside each `.map`.++When a bundle is available, the resolver:++1. Parses it with a [bundle parser](#bundle-parsers) into every function in the file: declarations, function expressions, arrow functions, and class methods, each with the generated position of its name. If the bundle fails to parse as a script (ESM syntax), it's retried with module syntax neutralized.+2. Flattens the nested scopes into a sorted list of transitions: "from this generated position onward, the innermost enclosing function's name sits at line L, column C".+3. For each mapping in the source map, resolves the enclosing function's *name position* back through the map itself, yielding the original, pre-minification name.++Take preact's `create-element.js`, which the old name heuristic famously got wrong:++```js+export function createElement(type, props, children) {+ let normalizedProps = {},+ key, ref, i;+ for (i in props) { // error around here (line 40)+ ...+ }+}+```++A frame inside that loop now resolves to `createElement`, because the scope walk knows which function *contains* the error position rather than guessing from nearby text.++When no bundle was uploaded (a map-only upload from an older CLI, or a `.map` with no sibling bundle in the build output), there is no scope information and **no name is resolved**: the name line stays whatever the SDK reported (typically `anonymous()`), while file, line, and column still resolve exactly. Locations never depend on the bundle, so the click-through is right even when the label is missing.++Resolved names never affect issue grouping, so name quality can keep improving (for example, by uploading bundles where you previously uploaded only maps) without re-bucketing existing issues. See [Issues](/learn/issues) for how grouping works.++## Bundle parsers++Scope analysis parses the minified bundle into an AST. Two parsers are available:++| Parser | Availability | Implementation |+|---|---|---|+| `goja` | always (default) | pure Go, via the [goja](https://github.com/dop251/goja) parser |+| `oxc` | opt-in build | Rust, via the [oxc](https://oxc.rs) parser behind a small C FFI shim |++`goja` ships in every build and needs nothing, which keeps the engine pure Go and runnable in a `scratch` image. `oxc` is substantially faster on large bundles but requires a Rust toolchain at build time:++```bash+./scripts/build-oxc-shim.sh # cargo build --release of the FFI shim+cd backend && go build -tags oxc . # links the static library in+```++The parser choice affects build speed only, never output: a parity test asserts oxc against goja across the fixture suite, and `.tw` files are interchangeable between them. Since parsing happens only when a resolver is built, the parser matters most for deployments with heavy map churn or with the disk cache disabled.++## Limitations today++In rough order of impact:++1. **Function names require the bundle.** The current upload CLI sends it automatically, but map-only uploads (older CLI versions, or maps whose sibling bundle was not in the build output) resolve locations without names.+2. **Filename matching collides on stable names.** Without debug IDs, two bundles with the same filename in different directories collide, and the most recent upload wins. Content-hashed bundle names (the default in Vite, Next, Angular, and most bundlers) avoid this in practice, and [debug IDs](/client/js-sdk/debug-ids) eliminate it entirely by addressing maps by build content instead of by name.+3. **Maps with `null` sources are ambiguous.** Frames resolve as `<unknown>`, though line, column, and name still resolve.+4. **50 resolved frames per trace.** Deeper frames stay minified.+5. **Module-level code has no name.** Errors thrown outside any function (Hermes/Metro global prologue, top-level module code) resolve location-only rather than being labeled `<global>`.++## How we verify it++The resolver is tested for parity against [getsentry/symbolic](https://github.com/getsentry/symbolic), the symbolication engine behind Sentry, using its own fixture suite (webpack, Metro, Hermes, preact, inlined functions, null-source maps). Every fixture frame's expected file, line, column, and name is asserted exactly, so any drift fails the build.++All frames match symbolic on **location**. With scope analysis, names now match too for frames inside a function, including the cases the old text-scanning heuristic got wrong (preact's `createElement` and `assign` among them). The remaining name gap is module-level code, where symbolic reports `<global>` and Traceway reports no name (limitation 5 above).++Two more invariants are tested directly: the `.tw` format round-trips (a resolver serialized and reopened answers every lookup identically, including from a memory-mapped file), and the `oxc` parser produces scope output identical to `goja` across the fixture suite, so the parser choice can never change symbolication results.++## Related pages++- [Source Maps](/client/js-sdk/sourcemap-upload): uploading maps from CI+- [Architecture](/symbolicator): when symbolication runs, the `.tw` format, and the cache tiers+- [Performance](/symbolicator/performance): cache sizing, failure handling, and metricsdiff --git a/docs/pages/symbolicator/library.mdx b/docs/pages/symbolicator/library.mdxnew file mode 100644index 00000000..0e3e6759--- /dev/null+++ b/docs/pages/symbolicator/library.mdx@@ -0,0 +1,201 @@+# Library++import { Callout } from "nextra/components";++Traceway's JS symbolicator is an importable Go library. Everything the ingest pipeline uses to turn minified stack traces back into source locations (source map parsing, bundle scope analysis for function names, the [`.tw` resolver format](/symbolicator#the-tw-resolver-format), and the mmap-backed disk cache) lives in public packages of the backend module, so you can use the engine in your own tooling without running Traceway at all.++It's pure Go by default: no cgo, no C libraries, works in a `scratch` image.++If you want this functionality inside an OpenTelemetry Collector pipeline instead of your own code, use the prebuilt [collector processor](/symbolicator/opentelemetry). For how the engine works internally, see [Architecture](/symbolicator) and [JavaScript](/symbolicator/javascript).++## Installation++```bash+go get github.com/tracewayapp/traceway/backend@latest+```++<Callout type="info">+ The symbolicator packages first ship in backend release `v1.8.0`, so+ `@latest` resolves to a version that has them. The import paths below are+ stable public packages; everything under `backend/app/symbolicator` is+ importable.+</Callout>++| Package | Import path | Purpose |+| ------- | ----------- | ------- |+| `symbolicator` | `github.com/tracewayapp/traceway/backend/app/symbolicator` | The resolver: source map + bundle in, original locations out |+| `jsstack` | `github.com/tracewayapp/traceway/backend/app/symbolicator/jsstack` | Browser stack trace parsing (V8, Firefox, Safari formats) |+| `scopes` | `github.com/tracewayapp/traceway/backend/app/symbolicator/scopes` | Bundle parser selection (goja default, oxc optional) |+| `twcache` | `github.com/tracewayapp/traceway/backend/app/symbolicator/twcache` | Mmap-backed disk cache of compiled `.tw` resolvers |+| `otelprocessor` | `github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor` | The [OTel Collector processor](/symbolicator/opentelemetry) wrapping the engine |++## Resolving a single frame++Build a resolver from a source map and (optionally) its minified bundle, then look positions up. The bundle is what enables function names through scope analysis; pass `nil` and you still get files, lines, and columns.++```go+package main++import (+ "fmt"+ "os"++ "github.com/tracewayapp/traceway/backend/app/symbolicator"+)++func main() {+ mapBytes, err := os.ReadFile("dist/app.min.js.map")+ if err != nil {+ panic(err)+ }+ bundleBytes, _ := os.ReadFile("dist/app.min.js") // optional, enables function names++ resolver, err := symbolicator.NewResolver(mapBytes, bundleBytes)+ if err != nil {+ panic(err)+ }++ // Lookup takes zero-based generated positions. A browser frame like+ // "app.min.js:1:13337" is line 0, column 13336 here.+ frame, ok := resolver.Lookup(0, 13336)+ if !ok {+ fmt.Println("no mapping at this position")+ return+ }+ fmt.Printf("%s:%d:%d", frame.File, frame.Line, frame.Col) // src/render.ts:42:7+ if frame.Fn != "" {+ fmt.Printf(" in %s()", frame.Fn)+ }+ fmt.Println()+}+```++The coordinate conventions, precisely:++- `Lookup(genLine, genCol uint32)` takes **zero-based** positions, matching the source map spec's internal encoding.+- Browser stack traces print **one-based** positions, so subtract 1 from each before calling `Lookup`.+- The returned `StackTraceFrame` carries **one-based** `Line` and `Col`, ready to print.+- `Fn` is the enclosing original function name, or `""` when the bundle was not provided or the position is not inside a known scope.++## Symbolicating a whole stack trace++`jsstack.ParseFrames` parses the raw `error.stack` formats browsers actually produce: V8 (`at fn (url:line:col)`, including `async`, `new`, `[as alias]`, and `eval` frames), Firefox, and Safari (`fn@url:line:col`). It returns frames with the one-based positions as printed.++```go+package main++import (+ "fmt"++ "github.com/tracewayapp/traceway/backend/app/symbolicator"+ "github.com/tracewayapp/traceway/backend/app/symbolicator/jsstack"+)++func symbolicateStack(rawStack string, resolverFor func(url string) *symbolicator.Resolver) {+ for _, f := range jsstack.ParseFrames(rawStack) {+ r := resolverFor(f.URL)+ if r == nil {+ continue+ }+ frame, ok := r.Lookup(f.Line-1, f.Col-1)+ if !ok {+ continue+ }+ fmt.Printf("%s at %s:%d:%d\n", f.Function, frame.File, frame.Line, frame.Col)+ }+}+```++`resolverFor` is yours to implement: typically a map from bundle URL basename to the resolver built from that bundle's artifacts.++If you need Traceway's canonical frame format (function name on one line, ` file:line:col` on the next, the format described in [JavaScript](/symbolicator/javascript#the-frame-format)), use `jsstack.Canonicalize`:++```go+canonical, converted := jsstack.Canonicalize(rawStack)+```++It returns the input unchanged (`converted == false`) when the trace is not a recognizable browser stack, so it's safe to call on arbitrary text, including Go panics and already-canonical traces.++## Caching compiled resolvers: the `.tw` format++Parsing a large source map and analyzing its bundle takes time you don't want to spend twice. A resolver serializes to Traceway's compact binary `.tw` format ([format details](/symbolicator#the-tw-resolver-format)) and loads back without reparsing anything:++```go+data := resolver.MarshalTW()+// persist data wherever you like, then later:+resolver2, err := symbolicator.OpenTW(data)+```++`OpenTW` validates the input fully and, when the byte slice is memory-mapped, resolves lookups directly against the mapping with zero copying. That is exactly what `twcache` does for you:++```go+package main++import (+ "github.com/tracewayapp/traceway/backend/app/symbolicator"+ "github.com/tracewayapp/traceway/backend/app/symbolicator/twcache"+)++// 2 GiB LRU of .tw files under /var/cache/tw; least recently used evicted first.+func newCache() (*twcache.Cache, error) {+ return twcache.New("/var/cache/tw", 2<<30, nil)+}++func cachedResolver(cache *twcache.Cache, name string, mapBytes, bundleBytes []byte) (*symbolicator.Resolver, error) {+ if r, err := cache.Open(name); err == nil {+ return r, nil // mmap hit+ }+ built, err := symbolicator.NewResolver(mapBytes, bundleBytes)+ if err != nil {+ return nil, err+ }+ if r, err := cache.Write(name, built.MarshalTW()); err == nil {+ return r, nil // persisted and mmapped+ }+ return built, nil // disk failed, serve the in-memory resolver+}+```++What `twcache` handles for you:++- Names are slash-separated paths relative to the cache directory and must stay inside it; subdirectories are fine (`project-a/app.min.js.tw`).+- Writes are atomic (temp file + rename), so a crash never leaves a partial `.tw` behind.+- Corrupt files are deleted on `Open` so your rebuild path replaces them.+- The LRU survives restarts: the directory is scanned on `New` and ordered by file mtime.+- `Remove(name)` invalidates after a re-deploy; `Stats()` reports entries, bytes, hits, and evictions.+- Resolvers stay valid after eviction deletes their file; the mapping is released only when the resolver is garbage collected.++`resolver.ApproxSize()` reports the retained footprint if you want to bound an in-memory cache on top.++## Choosing the bundle parser++Function-name resolution parses the minified bundle into scopes. Two parsers produce identical output (a parity test asserts this across the fixture suite, see [Bundle parsers](/symbolicator/javascript#bundle-parsers)):++- **goja** (default): pure Go, zero setup.+- **oxc**: a Rust parser behind cgo, several times faster on large bundles. The `-tags oxc` build links a static library from the `scopes` package's own source directory (`oxc-shim/target/release/liboxc_shim.a`), which the read-only module cache that `go get` populates never contains. To enable it, build against a writable checkout: clone the repo, run `scripts/build-oxc-shim.sh` once, add a `replace github.com/tracewayapp/traceway/backend => /path/to/traceway/backend` directive to your `go.mod` (or vendor the module and build the shim inside `vendor/`), then compile with `-tags oxc`.++```go+import "github.com/tracewayapp/traceway/backend/app/symbolicator/scopes"++if err := scopes.SetParser("oxc"); err != nil {+ // not compiled in; still on goja+}+```++`scopes.AvailableParsers()` lists what your binary was built with. The parser affects resolver build speed only, never output, so `.tw` files are interchangeable between the two.++## API summary++| Symbol | Signature | Notes |+| ------ | --------- | ----- |+| `symbolicator.NewResolver` | `(sourceMap, bundle []byte) (*Resolver, error)` | `bundle` may be `nil` (no function names) |+| `(*Resolver).Lookup` | `(genLine, genCol uint32) (StackTraceFrame, bool)` | zero-based in, one-based out |+| `symbolicator.StackTraceFrame` | `{File string; Line, Col uint32; Fn string}` | `Fn` may be empty |+| `(*Resolver).MarshalTW` | `() []byte` | serialize to `.tw` |+| `symbolicator.OpenTW` | `(data []byte) (*Resolver, error)` | validates fully; zero-copy over mmapped data |+| `(*Resolver).ApproxSize` | `() int64` | retained footprint for cache accounting |+| `jsstack.ParseFrames` | `(trace string) []Frame` | `Frame{Function, URL string; Line, Col uint32}`, one-based |+| `jsstack.Canonicalize` | `(trace string) (string, bool)` | passthrough on non-browser input |+| `scopes.SetParser` | `(name string) error` | `"goja"` or `"oxc"` (with `-tags oxc`) |+| `twcache.New` | `(dir string, maxBytes int64, warn func(error)) (*Cache, error)` | scans `dir`, LRU bounded by `maxBytes` |+| `(*twcache.Cache).Open` / `.Write` / `.Remove` / `.Stats` | | mmap-backed `.tw` files by relative name |diff --git a/docs/pages/symbolicator/opentelemetry.mdx b/docs/pages/symbolicator/opentelemetry.mdxnew file mode 100644index 00000000..23fab15e--- /dev/null+++ b/docs/pages/symbolicator/opentelemetry.mdx@@ -0,0 +1,226 @@+# OpenTelemetry++import { Callout, Steps } from "nextra/components";++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](https://github.com/honeycombio/opentelemetry-collector-symbolicator): 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](/symbolicator#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](/symbolicator/library).++The same processor also auto-routes non-symbolic Dart AOT traces to the [Dart](/symbolicator/dart) path. 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](https://opentelemetry.io/docs/collector/custom-collector/) 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`](https://github.com/tracewayapp/traceway/tree/main/benchmarks/processor) 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.++<Steps>++### Install the builder++Pin the builder to the collector version your manifest targets (this example uses 0.154.0, the version the benchmark pins):++```bash+go install go.opentelemetry.io/collector/cmd/[email protected]+```++### Write the builder manifest++`manifest.yaml`, the Traceway processor next to whatever receivers and exporters you need. This is `benchmarks/processor/manifest-traceway.yaml` without its local `replaces` directive:++```yaml+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+```++<Callout type="info">+ The processor first ships in `v1.8.0`; use that tag or any newer one, and keep+ the collector component versions aligned as OCB manifests require. The+ benchmark manifest adds a `replaces: github.com/tracewayapp/traceway/backend =>+ ../../../backend` line because it builds against the working tree; drop it when+ building against the published tag.+</Callout>++### Build it++```bash+builder --config manifest.yaml+```++This produces `./build/otelcol-symbolicator`, a self-contained collector binary. With the default `goja` parser it's pure Go and needs no cgo. For the faster `oxc` parser, follow `benchmarks/processor/run-local.sh`: run `scripts/build-oxc-shim.sh`, generate the sources with `builder --config manifest.yaml --skip-compilation`, then `cd build && CGO_ENABLED=1 go build -tags oxc .`.++### Configure the pipeline++`config.yaml`. The benchmark's env-parameterized version is `benchmarks/processor/config-traceway.yaml`:++```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]+```++To forward to Traceway, point the exporter at your Traceway server's OTLP base path and use a project token:++```yaml+exporters:+ otlphttp:+ endpoint: https://traceway.example.com/api/otel+ headers:+ Authorization: Bearer <project token>+```++### Run it++```bash+./build/otelcol-symbolicator --config config.yaml+```++For an end-to-end loop (build the collector, generate a corpus, drive load, sample memory), `benchmarks/processor/run-local.sh` runs the whole matrix.++</Steps>++## Registering the factory programmatically++When you assemble a collector in Go instead of using the builder, register the factory like any other processor factory:++```go+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:++```yaml+# 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:++| Attribute | Direction | Meaning |+| --------- | --------- | ------- |+| `exception.stacktrace` | read + rewritten | Raw stack in, symbolicated stack out |+| `exception.structured_stacktrace.{urls,functions,lines,columns}` | read + rewritten | Structured parallel arrays, preferred over string parsing when present |+| `exception.type`, `exception.message` | read | Used for the rewritten header line |+| `app.debug.source_map_uuid` | read (resource) | Optional store key prefix per build |+| `exception.stacktrace.original` and `.original` array variants | written | Originals, kept when `preserve_stack_trace: true` |+| `exception.symbolicator.failed` | written | `true` when any frame failed |+| `exception.symbolicator.error` | written | First failure, with a count hint when several frames failed |+| `exception.symbolicator.parsing_method` | written | `structured_stacktrace_attributes` or `processor_parsed` |+| `traceway.processor_type`, `traceway.processor_version` | written | Provenance stamps |++Raw string parsing handles the stack formats browsers produce: V8 (including `async`, `new`, `[as alias]`, and `eval` frames) and Firefox.++## Configuration reference++| Key | Default | Description |+| --- | ------- | ----------- |+| `source_map_store` | `file_store` | `file_store`, `s3_store`, or `gcs_store` |+| `local_source_maps.path` | `.` | Root directory for `file_store` |+| `s3_source_maps.region` / `.bucket` / `.prefix` | | S3 location |+| `gcs_source_maps.bucket` / `.prefix` | | GCS location |+| `timeout` | `5s` | Per-fetch budget for store reads |+| `cache_dir` | `""` | Directory for the `.tw` disk cache; empty disables the disk tier |+| `cache_max_mb` | `2048` | Byte cap for the disk cache, LRU-evicted |+| `cache_max_disk_pct` | `0` | Cap as a percentage of the cache directory's filesystem; when both caps are set, the smaller wins |+| `source_map_cache_size` | `128` | Max resolvers held in memory (cheap mmap handles when the disk tier is on) |+| `preserve_stack_trace` | `true` | Keep originals under the `.original` keys |+| `build_uuid_attribute_key` | `app.debug.source_map_uuid` | Resource attribute used as a store key prefix |+| `language_attribute_key` | `telemetry.sdk.language` | Attribute checked against `allowed_languages` |+| `allowed_languages` | `[]` | When set, only records with a matching language are processed |+| `parser` | `goja` | Bundle parser for function names: `goja` or `oxc` (the latter only in `-tags oxc` builds) |++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](/symbolicator/performance#benchmarks). For the full engine internals, see [Architecture](/symbolicator) and [JavaScript](/symbolicator/javascript).diff --git a/docs/pages/symbolicator/performance.mdx b/docs/pages/symbolicator/performance.mdxnew file mode 100644index 00000000..d2c318fb--- /dev/null+++ b/docs/pages/symbolicator/performance.mdx@@ -0,0 +1,113 @@+# Performance++The symbolicator has one performance decision that matters: where compiled resolvers live. Everything else (the `.tw` format, the lookup being a binary search, strings interned once) is fixed by the [architecture](/symbolicator). What you tune is the cache, and the choice is memory or disk.++## Memory vs disk++The in-memory LRU is always present and is the default. Compiled resolvers live on the heap, capped by entry count and estimated size. It's the right choice for most deployments: when the set of actively-resolving maps fits under the cap, every lookup after the first is a pure memory hit.++The disk tier adds a local cache of [`.tw` files](/symbolicator#the-tw-resolver-format) between memory and object storage. It changes what a *memory miss* costs. Instead of downloading and re-parsing, a miss becomes a local memory-mapped open measured in microseconds, and the token tables live in the OS page cache rather than on the process heap. The practical effect:++- **Resident memory tracks the hot set, not the corpus.** A thousand distinct builds on disk cost disk, not RAM. Memory mode has to hold every actively-used resolver in the heap at once.+- **Restarts warm instantly.** The local directory is scanned at startup, so a redeploy doesn't pay to rebuild everything.+- **Corpus size becomes a disk budget.** You bound it with a byte cap instead of hoping it fits in memory.++The disk tier earns its keep when the set of maps actively resolving is much larger than the memory cap, which is exactly when memory mode thrashes: high eviction traffic, every eviction a re-download and re-parse. If your corpus comfortably fits in RAM, the memory default is simpler and just as fast.++## Benchmarks++We load-tested both cache modes (and both [bundle parsers](/symbolicator/javascript#bundle-parsers)) against [Honeycomb's processor](https://github.com/honeycombio/opentelemetry-collector-symbolicator), across three scenarios, using the harness in [`benchmarks/processor`](https://github.com/tracewayapp/traceway/tree/main/benchmarks/processor). `hot` reuses a small set of maps so the cache stays warm. `churn` keeps swapping in fresh builds so the cache is under constant eviction pressure. `oom` pushes the corpus past what fits in RAM to see what falls over.++JavaScript, [full run](https://github.com/tracewayapp/traceway/actions/runs/27523441037):++| impl | scenario | max stacks/s | p99 ms (max) | peak RSS (MB) | avg CPU% | symb% | outcome |+|------|----------|-------------:|-------------:|--------------:|---------:|------:|---------|+| honeycomb | churn | 938 | 2961.886 | 4491 | 104 | 100 | survived |+| honeycomb | hot | 20735 | 373.363 | 125 | 183 | 100 | survived |+| honeycomb | oom | 938 | 2961.886 | 6844 | 90 | 99 | survived |+| traceway-goja-disk | churn | 29804 | 22.650 | 337 | 684 | 100 | survived |+| traceway-goja-disk | hot | 31962 | 9.250 | 340 | 686 | 100 | survived |+| traceway-goja-disk | oom | 29804 | 22.650 | 6950 | 172 | 100 | survived |+| traceway-goja-mem | churn | 3414 | 6341.875 | 1309 | 687 | 100 | survived |+| traceway-goja-mem | hot | 30568 | 10.594 | 313 | 677 | 100 | survived |+| traceway-goja-mem | oom | 3414 | 6341.875 | 7456 | 127 | 100 | died@236s |+| traceway-oxc-disk | churn | 29923 | 17.663 | 361 | 693 | 100 | survived |+| traceway-oxc-disk | hot | 30910 | 4.093 | 379 | 692 | 100 | survived |+| traceway-oxc-disk | oom | 29923 | 17.663 | 6851 | 163 | 100 | survived |+| traceway-oxc-mem | churn | 16755 | 128.841 | 584 | 657 | 100 | survived |+| traceway-oxc-mem | hot | 31915 | 12.495 | 311 | 687 | 100 | survived |+| traceway-oxc-mem | oom | 16755 | 128.841 | 7469 | 106 | 100 | died@40s |++Read the `churn` rows first, because that's where caching strategy shows. Disk mode holds around 30k stacks/s with a p99 near 20ms. Honeycomb does 938 stacks/s with a 3-second tail. Memory mode collapses too: goja-mem drops to 3,414 stacks/s with a 6-second p99, because it's recompiling maps it just evicted. Then look at `oom`: both memory-mode variants die, disk mode survives. On a hot working set everyone's fine and the gaps close, which is the point. Cache mode only matters once the corpus stops fitting.++Dart, [full run](https://github.com/tracewayapp/traceway/actions/runs/27522485099). Honeycomb isn't here because it doesn't do Dart:++| impl | scenario | max stacks/s | p99 ms (max) | peak RSS (MB) | avg CPU% | symb% | outcome |+|------|----------|-------------:|-------------:|--------------:|---------:|------:|---------|+| traceway-dart-disk | churn | 22915 | 398.521 | 138 | 303 | 100 | survived |+| traceway-dart-disk | hot | 24304 | 425.903 | 137 | 295 | 100 | survived |+| traceway-dart-disk | oom | 22915 | 398.521 | 103 | 172 | 100 | survived |+| traceway-dart-mem | churn | 8586 | 72.739 | 529 | 653 | 98 | survived |+| traceway-dart-mem | hot | 28605 | 5.509 | 361 | 672 | 100 | survived |+| traceway-dart-mem | oom | 8586 | 72.739 | 2165 | 109 | 100 | survived |++Dart trades a little differently. The ELF symbol files are large, so memory mode wins the hot path outright (28,605 stacks/s, 5.5ms p99) when everything fits. But watch the RSS column: disk mode stays pinned between 103 and 138 MB across every scenario, including `oom`, while memory mode climbs to 2,165 MB. Disk mode pays a steadier ~400ms tail for mmap page-ins and buys flat, predictable memory in return.++The one-sentence summary across both languages: if your corpus fits in RAM and stays there, memory mode is fastest; if it doesn't, or you can't promise it always will, disk mode is the one that keeps running.++## Sizing++In Traceway's ingest path, the cache is configured by environment variables:++| Variable | Default | Description |+|----------|---------|-------------|+| `SOURCEMAP_CACHE_TYPE` | `memory` | `memory` for the in-memory LRU only, `disk` to add the local `.tw` tier |+| `SOURCEMAP_DISK_CACHE_PATH` | `./twcache` | Directory for local `.tw` files (disk mode only) |+| `SOURCEMAP_DISK_CACHE_MAX_MB` | `2048` | Byte cap for the local `.tw` directory, LRU-evicted (disk mode only) |+| `SOURCEMAP_CACHE_MAX_ENTRIES` | `200` | Max built resolvers held in memory |+| `SOURCEMAP_CACHE_MAX_BYTES_MB` | `500` | Max estimated in-memory size of all resolvers |+| `SYMBOLICATOR_PARSER` | `goja` | Bundle parser for function names: `goja` or `oxc` (the latter only in `-tags oxc` builds) |++In the [collector processor](/symbolicator/opentelemetry) the same modes are configured by processor keys instead (`cache_dir`, `cache_max_mb`, `cache_max_disk_pct`, `source_map_cache_size`); see that page for the full reference. A `.tw` file is typically a small multiple of the map's `mappings` field, far smaller than the parsed-in-RAM representation, so a disk budget stretches much further than a memory budget for the same corpus. See [Capacity & Self-Monitoring](/server/capacity-monitoring) for the operations view.++## When loading fails++If a map doesn't exist, a read times out, storage errors, or an artifact fails to parse:++- The affected frames pass through **unchanged**, and the trace is stored as-is. Ingest is never blocked beyond the per-read budget (5 seconds) and never errors because of symbolication.+- The failure is **negative-cached per key**: while the cooldown is active, frames referencing it skip the storage read entirely. A missing artifact starts at a 1 minute cooldown; a transient failure (timeout, storage error, unparseable input) starts at 15 seconds, so brief hiccups recover fast. Each consecutive failure doubles the cooldown, capped at 15 minutes, so a project that never uploads converges to a few storage reads per hour instead of one per minute.+- The cooldown clears the moment that artifact is uploaded (the upload endpoint invalidates it in-process) or a load succeeds. In a multi-instance deployment, other instances retry within their remaining cooldown, at most 15 minutes.+- Within a single trace, a failed artifact is attempted **once**, not once per frame, so a 50-frame trace cannot stack fifty timeouts.+- Traceway self-reports the failure into its own monitoring project, throttled to one exception per minute with a count of suppressed occurrences.++## Observability++The backend self-reports cache metrics every 30 seconds:++| Metric | Meaning |+|---|---|+| `traceway.sourcemap.entries` | built resolvers currently in memory |+| `traceway.sourcemap.bytes` | estimated total size of those entries |+| `traceway.sourcemap.negative_entries` | keys currently under a miss/failure cooldown |+| `traceway.sourcemap.hits.delta` | cache hits since the last tick |+| `traceway.sourcemap.misses.delta` | builds triggered since the last tick |+| `traceway.sourcemap.evictions.delta` | LRU evictions since the last tick |+| `traceway.sourcemap.load_failures.delta` | failed builds; each one is a trace stored unsymbolicated |+| `traceway.sourcemap.not_found.delta` | lookups that found no uploaded artifact since the last tick |+| `traceway.sourcemap.negative_hits.delta` | lookups skipped by an active cooldown since the last tick |+| `traceway.sourcemap.parse_ms` | duration of the most recent resolver build |+| `traceway.sourcemap.store_hits.delta` | memory misses served by a `.tw` fetched from object storage (both cache modes) |+| `traceway.sourcemap.builds.delta` | memory misses that required a full rebuild (both cache modes) |+| `traceway.sourcemap.disk.entries` / `disk.bytes` | local `.tw` files cached and their total size (disk tier only) |+| `traceway.sourcemap.disk.hits.delta` | memory misses served by a local `.tw` file (disk tier only) |+| `traceway.sourcemap.disk.evictions.delta` | local `.tw` files evicted by the byte cap (disk tier only) |++What healthy looks like: `misses.delta` near zero in steady state, `load_failures.delta` at zero (anything above means unsymbolicated traces are reaching your issues), and `bytes` comfortably under the cap. A useful alert is `load_failures.delta` max greater than 0 over 5 minutes.++`not_found.delta` is a configuration signal, not a failure: sustained nonzero values for a project that should symbolicate mean exceptions reference artifacts that were never uploaded, most commonly a missing upload step in CI. `negative_hits.delta` shows the cooldown doing its job; high values alongside high `not_found.delta` are normal for projects that simply don't upload.++## Related pages++- [Architecture](/symbolicator): the cache tiers and the `.tw` format+- [OpenTelemetry](/symbolicator/opentelemetry#sizing-the-cache): cache keys for the collector processor+- [Capacity & Self-Monitoring](/server/capacity-monitoring): the operations viewdiff --git a/docs/styles/custom.css b/docs/styles/custom.cssindex 72166a14..300f8d76 100644--- a/docs/styles/custom.css+++ b/docs/styles/custom.css@@ -14,7 +14,7 @@--ink-4: #1d2430;--ink-5: #283041;--hair: rgba(255, 255, 255, 0.06);- --hair-2: rgba(255, 255, 255, 0.10);+ --hair-2: rgba(255, 255, 255, 0.1);/* Text */--fg-0: #f4f6fb;@@ -42,9 +42,14 @@/* Font aliases mirroring website var names(--font-display / --font-mono are populated by next/font in _app.jsx) */- --f-display: var(--font-display, "JetBrains Mono"), "IBM Plex Mono", ui-monospace, monospace;- --f-body: var(--font-body, "Inter"), ui-sans-serif, system-ui, -apple-system, sans-serif;- --f-mono: var(--font-mono, "IBM Plex Mono"), "JetBrains Mono", ui-monospace, monospace;+ --f-display:+ var(--font-display, "JetBrains Mono"), "IBM Plex Mono", ui-monospace,+ monospace;+ --f-body:+ var(--font-body, "Inter"), ui-sans-serif, system-ui, -apple-system,+ sans-serif;+ --f-mono:+ var(--font-mono, "IBM Plex Mono"), "JetBrains Mono", ui-monospace, monospace;}/* =========================================================================@@ -56,8 +61,12 @@ body {background: var(--ink-0) !important;color: var(--fg-1);color-scheme: dark;- font-family: var(--font-body, "Inter"), ui-sans-serif, system-ui,- -apple-system, sans-serif;+ font-family:+ var(--font-body, "Inter"),+ ui-sans-serif,+ system-ui,+ -apple-system,+ sans-serif;font-feature-settings: "cv02", "cv03", "cv04", "cv11";-webkit-font-smoothing: antialiased;}@@ -84,8 +93,12 @@ main h6,.nextra-content h4,.nextra-content h5,.nextra-content h6 {- font-family: var(--font-body, "Inter"), ui-sans-serif, system-ui,- -apple-system, sans-serif !important;+ font-family:+ var(--font-body, "Inter"),+ ui-sans-serif,+ system-ui,+ -apple-system,+ sans-serif !important;color: var(--fg-0) !important;font-weight: 600;letter-spacing: -0.015em;@@ -154,9 +167,7 @@ main a:hover,========================================================================= */.nextra-nav-container {- background: color-mix(in oklab, var(--ink-0) 75%, transparent) !important;- backdrop-filter: blur(14px) saturate(140%);- -webkit-backdrop-filter: blur(14px) saturate(140%);+ background: var(--ink-0) !important;border-bottom: 1px solid var(--hair);}@@ -175,6 +186,7 @@ main a:hover,.nextra-sidebar-container button {color: var(--fg-2) !important;font-family: var(--font-mono), ui-monospace, monospace;+ border: 1px solid transparent !important;}.nextra-sidebar-container a:hover,@@ -183,10 +195,20 @@ main a:hover,background: var(--ink-2) !important;}+.nextra-sidebar-container a.nx-bg-primary-100,.nextra-sidebar-container .nx-text-primary-600,.nextra-sidebar-container a[aria-current="page"] {- color: var(--a2) !important;- background: color-mix(in oklab, var(--a1) 14%, transparent) !important;+ color: var(--fg-0) !important;+ background: transparent !important;+ border-color: var(--fg-0) !important;+}++/* Expanded top-level folder containing the active page: Nextra fills it with the+ primary tint (nx-bg-primary-100 / dark:nx-bg-primary-400/10). Keep it+ transparent so only the active leaf is boxed, not its parent section. */+.nextra-sidebar-container button.nx-bg-primary-100 {+ color: var(--fg-0) !important;+ background: transparent !important;}/* Right TOC */@@ -322,7 +344,29 @@ main hr,========================================================================= */.nextra-nav-container nav > a:first-child {- margin-right: 20px !important;+ margin-right: 24px !important;+}++/* Top-nav menu links: match the marketing website header (JetBrains Mono,+ 14px / 500, h-9 px-3 rounded-md pills). Selector scoped to the page-nav+ anchors via nx-text-sm so the logo and GitHub icon link are untouched. */+.nextra-nav-container nav a.nx-text-sm {+ font-family: var(--font-display) !important;+ font-size: 14px !important;+ font-weight: 500 !important;+ padding: 0 12px !important;+ border-radius: var(--radius) !important;+ color: var(--fg-1) !important;+}++.nextra-nav-container nav a.nx-text-sm:hover {+ color: var(--fg-0) !important;+ background: var(--ink-2) !important;+}++.nextra-nav-container nav a.nx-text-sm.nx-text-primary-600,+.nextra-nav-container nav a.nx-text-sm[aria-current="true"] {+ color: var(--fg-0) !important;}.nextra-nav-container .nextra-search {@@ -365,8 +409,12 @@ main hr,opacity: 0.5;}-.muted { color: var(--fg-2); }-.dim { color: var(--fg-3); }+.muted {+ color: var(--fg-2);+}+.dim {+ color: var(--fg-3);+}.hair-rule {height: 1px;@@ -381,7 +429,9 @@ main hr,padding: 22px;}-.gridbg { position: relative; }+.gridbg {+ position: relative;+}/* Chips */.chip {@@ -404,8 +454,12 @@ main hr,background: var(--a2);flex-shrink: 0;}-.chip.ok .dot { background: var(--ok); }-.chip.crit .dot { background: var(--crit); }+.chip.ok .dot {+ background: var(--ok);+}+.chip.crit .dot {+ background: var(--crit);+}/* Buttons: !important on color values to beat `main a { color: var(--a2) !important }` */.btn {@@ -418,19 +472,27 @@ main hr,font-weight: 500;font-size: 14px;letter-spacing: -0.01em;- transition: transform 0.12s ease, background 0.2s, border-color 0.2s,- color 0.2s, filter 0.2s, box-shadow 0.2s;+ transition:+ transform 0.12s ease,+ background 0.2s,+ border-color 0.2s,+ color 0.2s,+ filter 0.2s,+ box-shadow 0.2s;border: 1px solid transparent;white-space: nowrap;cursor: pointer;text-decoration: none !important;}-.btn:active { transform: scale(0.97); }+.btn:active {+ transform: scale(0.97);+}.btn-primary {background: var(--fg-0);color: var(--ink-0) !important;- box-shadow: 0 1px 0 rgba(255, 255, 255, 0.6) inset,+ box-shadow:+ 0 1px 0 rgba(255, 255, 255, 0.6) inset,0 0 0 1px rgba(255, 255, 255, 0.12);}.btn-primary:hover {@@ -481,7 +543,7 @@ li:has(> .sdk-selector) > span:first-child {.sdk-selector {position: relative;width: 100%;- padding: 0 8px;+ padding: 0px;}.sdk-selector-trigger {@@ -498,7 +560,9 @@ li:has(> .sdk-selector) > span:first-child {background: var(--ink-2);color: var(--fg-0);cursor: pointer;- transition: border-color 0.15s, background 0.15s;+ transition:+ border-color 0.15s,+ background 0.15s;}.sdk-selector-trigger:hover {@@ -565,7 +629,9 @@ li:has(> .sdk-selector) > span:first-child {background: transparent;color: var(--fg-1);cursor: pointer;- transition: background 0.12s, color 0.12s;+ transition:+ background 0.12s,+ color 0.12s;}.sdk-selector-option:hover {@@ -631,7 +697,9 @@ li:has(> .sdk-selector) > span:first-child {border-radius: 12px;background: var(--ink-1);cursor: pointer;- transition: border-color 0.2s, background 0.2s;+ transition:+ border-color 0.2s,+ background 0.2s;text-align: left;font-family: inherit;}@@ -687,7 +755,9 @@ li:has(> .sdk-selector) > span:first-child {border-radius: 12px;background: var(--ink-1);text-decoration: none !important;- transition: border-color 0.2s, background 0.2s;+ transition:+ border-color 0.2s,+ background 0.2s;}.deployment-card:hover {diff --git a/docs/theme.config.jsx b/docs/theme.config.jsxindex 51631037..b701ef62 100644--- a/docs/theme.config.jsx+++ b/docs/theme.config.jsx@@ -37,7 +37,7 @@ export default {<imgsrc="/traceway-logo-white.png"alt="Traceway"- style={{ height: "32px" }}+ style={{ height: "28px" }}/>);},diff --git a/frontend/src/lib/components/issues/stack-trace-card.svelte b/frontend/src/lib/components/issues/stack-trace-card.svelteindex a23f034f..b4ae7aae 100644--- a/frontend/src/lib/components/issues/stack-trace-card.svelte+++ b/frontend/src/lib/components/issues/stack-trace-card.svelte@@ -10,6 +10,7 @@stackTrace: string;isMessage?: boolean;isJavaScript?: boolean;+ isFlutter?: boolean;firstSeen?: string;lastSeen?: string;totalCount?: number;@@ -22,6 +23,7 @@stackTrace,isMessage = false,isJavaScript = false,+ isFlutter = false,firstSeen,lastSeen,totalCount,@@ -33,7 +35,7 @@const tz = $derived(timezone ?? getTimezone());const showStats = $derived(firstSeen && lastSeen && totalCount !== undefined);const parsed = $derived(parseStackTrace(stackTrace));- const usePretty = $derived(isJavaScript && parsed.groups.length > 0);+ const usePretty = $derived((isJavaScript || isFlutter) && parsed.groups.length > 0);let expandedGroups = $state<Set<number>>(new Set());diff --git a/frontend/src/lib/components/setup/source-map-upload-card.svelte b/frontend/src/lib/components/setup/source-map-upload-card.svelteindex a6f7b416..df3e0c72 100644--- a/frontend/src/lib/components/setup/source-map-upload-card.svelte+++ b/frontend/src/lib/components/setup/source-map-upload-card.svelte@@ -13,6 +13,8 @@let projectWithToken = $derived(projectsState.currentProject);+ const isFlutter = $derived(projectWithToken?.framework === 'flutter');+const isReadonly = $derived(authState.getRoleForOrganization(projectsState.currentProject?.organizationId ?? 0) ==='readonly'@@ -24,12 +26,14 @@<CardHeader><CardTitle class="flex items-center gap-2"><KeyRound class="h-5 w-5" />- Source Map Upload+ {isFlutter ? 'Symbol Upload' : 'Source Map Upload'}</CardTitle>- <CardDescription>- Upload source maps to see original file names and line numbers in stack traces from- minified code.- </CardDescription>+ {#if !isFlutter}+ <CardDescription>+ Upload source maps to see original file names and line numbers in stack traces from+ minified code.+ </CardDescription>+ {/if}</CardHeader><CardContent><SourceMapSetup />diff --git a/frontend/src/lib/components/source-map-setup.svelte b/frontend/src/lib/components/source-map-setup.svelteindex 4fc7f95a..03fc5f39 100644--- a/frontend/src/lib/components/source-map-setup.svelte+++ b/frontend/src/lib/components/source-map-setup.svelte@@ -76,6 +76,8 @@ module.exports = {let copiedPluginInstall = $state(false);let copiedBundlerConfig = $state(false);let copiedCommand = $state(false);+ let copiedFlutterBuild = $state(false);+ let copiedFlutterUpload = $state(false);const pluginInstallCommand = 'npm install -D @tracewayapp/bundler-plugin';@@ -85,6 +87,9 @@ module.exports = {authState.getRoleForOrganization(project?.organizationId ?? 0) === 'readonly');+ const isFlutter = $derived(project?.framework === 'flutter');+ const artifactLabel = $derived(isFlutter ? 'debug symbols' : 'source maps');+const showBundlerSetup = $derived(project?.framework !== 'react-native');const uploadCommand = $derived(@@ -96,6 +101,17 @@ module.exports = {: '');+ const flutterBuildCommand =+ 'flutter build apk --release --obfuscate --split-debug-info=build/symbols';++ const flutterUploadCommand = $derived(+ project && sourceMapToken+ ? `dart run traceway:upload_symbols \\+ --token ${sourceMapToken} \\+ --url ${project.backendUrl}`+ : ''+ );+let regenerateDialogOpen = $state(false);async function generateToken() {@@ -142,6 +158,18 @@ module.exports = {copiedCommand = true;setTimeout(() => (copiedCommand = false), 2000);}++ async function copyFlutterBuild() {+ await navigator.clipboard.writeText(flutterBuildCommand);+ copiedFlutterBuild = true;+ setTimeout(() => (copiedFlutterBuild = false), 2000);+ }++ async function copyFlutterUpload() {+ await navigator.clipboard.writeText(flutterUploadCommand);+ copiedFlutterUpload = true;+ setTimeout(() => (copiedFlutterUpload = false), 2000);+ }</script>{#if sourceMapToken}@@ -169,13 +197,13 @@ module.exports = {</Button></div></div>- {#if showBundlerSetup}+ {#if isFlutter}<div>- <p class="mb-2 text-sm font-medium">Step 1: Install the bundler plugin</p>+ <p class="mb-2 text-sm font-medium">Step 1: Build with obfuscation enabled</p><div class="relative"><div class="absolute top-2 right-2 z-10">- <Button variant="outline" size="sm" onclick={copyPluginInstall}>- {#if copiedPluginInstall}+ <Button variant="outline" size="sm" onclick={copyFlutterBuild}>+ {#if copiedFlutterBuild}<Check class="mr-2 h-4 w-4 text-green-500" />Copied!{:else}@@ -189,31 +217,20 @@ module.exports = {? 'dark-code': 'light-code'}">- <Highlight language={bash} code={pluginInstallCommand} />+ <Highlight language={bash} code={flutterBuildCommand} /></div></div>+ <p class="mt-2 text-xs text-muted-foreground">+ This writes a per-architecture .symbols file into build/symbols. The example builds an+ Android APK; other targets emit their own symbol files in the same directory.+ </p></div><div>- <p class="mb-2 text-sm font-medium">Step 2: Add the plugin to your bundler</p>- <Tabs.Root- value={bundler}- onValueChange={(v) => {- if (v) bundler = v as Bundler;- }}- >- <Tabs.List class="mb-2">- {#each Object.entries(bundlerConfigs) as [value, config] (value)}- <Tabs.Trigger {value}>{config.label}</Tabs.Trigger>- {/each}- </Tabs.List>- </Tabs.Root>- <p class="mb-2 font-mono text-xs text-muted-foreground">- {bundlerConfigs[bundler].file}- </p>+ <p class="mb-2 text-sm font-medium">Step 2: Upload the symbols after each release build</p><div class="relative"><div class="absolute top-2 right-2 z-10">- <Button variant="outline" size="sm" onclick={copyBundlerConfig}>- {#if copiedBundlerConfig}+ <Button variant="outline" size="sm" onclick={copyFlutterUpload}>+ {#if copiedFlutterUpload}<Check class="mr-2 h-4 w-4 text-green-500" />Copied!{:else}@@ -227,50 +244,136 @@ module.exports = {? 'dark-code': 'light-code'}">- <Highlight- language={bundlerConfigs[bundler].language}- code={bundlerConfigs[bundler].code}- />+ <Highlight language={bash} code={flutterUploadCommand} /></div></div>+ <p class="mt-2 text-xs text-muted-foreground">+ Run from your project root after each release. The uploader auto-discovers build/symbols+ and pushes every architecture in one go; symbols are unique per build, so re-upload on+ each release. In CI, pass the token as <code class="font-mono">TRACEWAY_UPLOAD_TOKEN</code>+ instead of the flag.+ </p></div>- {/if}- <div>- <p class="mb-2 text-sm font-medium">- {showBundlerSetup ? 'Step 3: Upload after your production build' : 'Usage'}- </p>- <div class="relative">- <div class="absolute top-2 right-2 z-10">- <Button variant="outline" size="sm" onclick={copyUploadCommand}>- {#if copiedCommand}- <Check class="mr-2 h-4 w-4 text-green-500" />- Copied!- {:else}- <Copy class="mr-2 h-4 w-4" />- Copy- {/if}- </Button>+ {:else}+ {#if showBundlerSetup}+ <div>+ <p class="mb-2 text-sm font-medium">Step 1: Install the bundler plugin</p>+ <div class="relative">+ <div class="absolute top-2 right-2 z-10">+ <Button variant="outline" size="sm" onclick={copyPluginInstall}>+ {#if copiedPluginInstall}+ <Check class="mr-2 h-4 w-4 text-green-500" />+ Copied!+ {:else}+ <Copy class="mr-2 h-4 w-4" />+ Copy+ {/if}+ </Button>+ </div>+ <div+ class="overflow-x-auto rounded-lg text-sm {themeState.isDark+ ? 'dark-code'+ : 'light-code'}"+ >+ <Highlight language={bash} code={pluginInstallCommand} />+ </div>+ </div></div>- <div- class="overflow-x-auto rounded-lg text-sm {themeState.isDark- ? 'dark-code'- : 'light-code'}"- >- <Highlight language={bash} code={uploadCommand} />+ <div>+ <p class="mb-2 text-sm font-medium">Step 2: Add the plugin to your bundler</p>+ <Tabs.Root+ value={bundler}+ onValueChange={(v) => {+ if (v) bundler = v as Bundler;+ }}+ >+ <Tabs.List class="mb-2">+ {#each Object.entries(bundlerConfigs) as [value, config] (value)}+ <Tabs.Trigger {value}>{config.label}</Tabs.Trigger>+ {/each}+ </Tabs.List>+ </Tabs.Root>+ <p class="mb-2 font-mono text-xs text-muted-foreground">+ {bundlerConfigs[bundler].file}+ </p>+ <div class="relative">+ <div class="absolute top-2 right-2 z-10">+ <Button variant="outline" size="sm" onclick={copyBundlerConfig}>+ {#if copiedBundlerConfig}+ <Check class="mr-2 h-4 w-4 text-green-500" />+ Copied!+ {:else}+ <Copy class="mr-2 h-4 w-4" />+ Copy+ {/if}+ </Button>+ </div>+ <div+ class="overflow-x-auto rounded-lg text-sm {themeState.isDark+ ? 'dark-code'+ : 'light-code'}"+ >+ <Highlight+ language={bundlerConfigs[bundler].language}+ code={bundlerConfigs[bundler].code}+ />+ </div>+ </div>+ </div>+ {/if}+ <div>+ <p class="mb-2 text-sm font-medium">+ {showBundlerSetup ? 'Step 3: Upload after your production build' : 'Usage'}+ </p>+ <div class="relative">+ <div class="absolute top-2 right-2 z-10">+ <Button variant="outline" size="sm" onclick={copyUploadCommand}>+ {#if copiedCommand}+ <Check class="mr-2 h-4 w-4 text-green-500" />+ Copied!+ {:else}+ <Copy class="mr-2 h-4 w-4" />+ Copy+ {/if}+ </Button>+ </div>+ <div+ class="overflow-x-auto rounded-lg text-sm {themeState.isDark+ ? 'dark-code'+ : 'light-code'}"+ >+ <Highlight language={bash} code={uploadCommand} />+ </div></div></div>- </div>+ {/if}</div>{:else if isReadonly}<p class="text-sm text-muted-foreground">- An upload token is required to upload source maps. Ask an organization admin to generate one+ An upload token is required to upload {artifactLabel}. Ask an organization admin to generate onefrom the Connection page.</p>{:else}<div class="flex items-center justify-between gap-4">- <p class="text-sm text-muted-foreground">- Generate an upload token to start uploading source maps as part of your build process.- </p>+ {#if isFlutter}+ <p class="text-sm text-muted-foreground">+ Plain release builds already report readable traces. Only obfuscated builds (<code+ class="rounded bg-muted px-1 py-0.5 font-mono text-xs">--obfuscate</code+ >) need this: generate a token, then upload your <code+ class="rounded bg-muted px-1 py-0.5 font-mono text-xs">.symbols</code+ > after each release to resolve their stack traces.+ <a+ href="https://docs.tracewayapp.com/client/flutter"+ target="_blank"+ rel="noopener noreferrer"+ class="underline hover:text-foreground">Flutter docs</a+ >+ </p>+ {:else}+ <p class="text-sm text-muted-foreground">+ Generate an upload token to start uploading {artifactLabel} as part of your build process.+ </p>+ {/if}<Button variant="outline" size="sm" onclick={generateToken} disabled={generatingToken}>{#if generatingToken}<LoadingCircle class="mr-2 h-4 w-4" />diff --git a/frontend/src/lib/state/projects.svelte.ts b/frontend/src/lib/state/projects.svelte.tsindex 3a2161a9..e663063e 100644--- a/frontend/src/lib/state/projects.svelte.ts+++ b/frontend/src/lib/state/projects.svelte.ts@@ -50,6 +50,10 @@ export function isJsFramework(fw: Framework): boolean {return JS_FRAMEWORKS.includes(fw);}+export function supportsSymbolUpload(fw: Framework): boolean {+ return isJsFramework(fw) || fw === 'flutter';+}+export const JS_LANGUAGES = ['webjs', 'nodejs', 'javascript', 'typescript'];export function isJsLanguage(lang?: string | null): boolean {diff --git a/frontend/src/lib/utils/stack-trace-parser.ts b/frontend/src/lib/utils/stack-trace-parser.tsindex d8daee96..c6da95b9 100644--- a/frontend/src/lib/utils/stack-trace-parser.ts+++ b/frontend/src/lib/utils/stack-trace-parser.ts@@ -18,6 +18,17 @@ export type ParsedStackTrace = {groups: FrameGroup[];};+function isLibraryLocation(location: string): boolean {+ return (+ location.includes('node_modules') ||+ /^node:/.test(location) ||+ /^dart:/.test(location) ||+ /^third_party\//.test(location) ||+ /^package:(flutter(\/|_)|collection\/)/.test(location) ||+ /SnapshotInstructions\+0x/.test(location)+ );+}+function extractPackageName(location: string): string {const nodeModulesMatch = location.match(/node_modules\/([^/]+)/);if (nodeModulesMatch) return nodeModulesMatch[1];@@ -28,6 +39,9 @@ function extractPackageName(location: string): string {const dartMatch = location.match(/^(package:[^/]+|dart:[^/]+)/);if (dartMatch) return dartMatch[1];+ if (/^third_party\//.test(location)) return 'dart sdk';+ if (/SnapshotInstructions\+0x/.test(location)) return 'unresolved';+return 'library';}@@ -35,14 +49,42 @@ export function parseStackTrace(raw: string): ParsedStackTrace {const lines = raw.split('\n');const frames: StackFrame[] = [];let firstFrameIndex = -1;- let firstFuncNameIndex = -1;+ let messageEndIndex = -1;const locationPattern = /^\s*.+:\d+:\d+$/;+ const dartFramePattern = /^\s*#\d+\s+(.+?)\s+\((.+)\)\s*$/;+ const dartUnresolvedPattern = /^\s*#\d+\s+(\S+SnapshotInstructions\+0x[0-9a-fA-F]+)\s*$/;for (let i = 0; i < lines.length; i++) {+ const dartMatch = lines[i].match(dartFramePattern);+ if (dartMatch) {+ const location = dartMatch[2].trim();+ if (firstFrameIndex === -1) {+ firstFrameIndex = i;+ messageEndIndex = i;+ }+ frames.push({+ functionName: dartMatch[1].trim(),+ location,+ isLibrary: isLibraryLocation(location)+ });+ continue;+ }++ const unresolvedMatch = lines[i].match(dartUnresolvedPattern);+ if (unresolvedMatch) {+ if (firstFrameIndex === -1) {+ firstFrameIndex = i;+ messageEndIndex = i;+ }+ frames.push({ functionName: null, location: unresolvedMatch[1].trim(), isLibrary: true });+ continue;+ }+if (locationPattern.test(lines[i])) {const location = lines[i].trim();let functionName: string | null = null;+ let funcNameIndex = -1;for (let j = i - 1; j >= 0; j--) {const prevLine = lines[j].trim();@@ -52,29 +94,24 @@ export function parseStackTrace(raw: string): ParsedStackTrace {firstFrameIndex === -1 && !prevLine.endsWith('()') && prevLine.includes(': ');if (!messageLike) {functionName = prevLine;- if (firstFrameIndex === -1) firstFuncNameIndex = j;+ funcNameIndex = j;}}break;}- if (firstFrameIndex === -1) firstFrameIndex = i;+ if (firstFrameIndex === -1) {+ firstFrameIndex = i;+ messageEndIndex = funcNameIndex !== -1 ? funcNameIndex : i;+ }- frames.push({- functionName,- location,- isLibrary: location.includes('node_modules') ||- /^(package:flutter\/|dart:|package:collection\/|node:)/.test(location)- });+ frames.push({ functionName, location, isLibrary: isLibraryLocation(location) });}}- const errorEndIndex = firstFrameIndex === -1- ? lines.length- : firstFuncNameIndex !== -1 ? firstFuncNameIndex : firstFrameIndex;const errorMessage = firstFrameIndex === -1? raw.trim()- : lines.slice(0, errorEndIndex).join('\n').trim();+ : lines.slice(0, messageEndIndex).join('\n').trim();const groups: FrameGroup[] = [];diff --git a/frontend/src/routes/connection/+page.svelte b/frontend/src/routes/connection/+page.svelteindex 8b867fc9..422cf437 100644--- a/frontend/src/routes/connection/+page.svelte+++ b/frontend/src/routes/connection/+page.svelte@@ -13,7 +13,8 @@type ProjectWithToken,isJsFramework,isOtelFramework,- isCloudflareFramework+ isCloudflareFramework,+ supportsSymbolUpload} from '$lib/state/projects.svelte';import FrameworkIcon from '$lib/components/framework-icon.svelte';import Highlight from 'svelte-highlight';@@ -115,6 +116,9 @@ service:});const isJs = $derived(projectWithToken ? isJsFramework(projectWithToken.framework) : false);+ const showSymbolUpload = $derived(+ projectWithToken ? supportsSymbolUpload(projectWithToken.framework) : false+ );async function copyCode() {await navigator.clipboard.writeText(sdkCode);@@ -342,7 +346,7 @@ service:</div></CardContent></Card>- {#if isJs}+ {#if showSymbolUpload}<SourceMapUploadCard />{/if}{/if}diff --git a/frontend/src/routes/issues/[exceptionHash]/+page.svelte b/frontend/src/routes/issues/[exceptionHash]/+page.svelteindex 64044b19..7da59bb4 100644--- a/frontend/src/routes/issues/[exceptionHash]/+page.svelte+++ b/frontend/src/routes/issues/[exceptionHash]/+page.svelte@@ -40,6 +40,7 @@? isJsFramework(projectsState.currentProject.framework): false) || isJsLanguage(latestOccurrence?.attributes?.['telemetry.sdk.language']));+ const isFlutter = $derived(projectsState.currentProject?.framework === 'flutter');const hasMoreOccurrences = $derived(total > 10);const firstLineOfStackTrace = $derived(latestOccurrence?.stackTrace.split('\n')[0] || 'Exception');@@ -169,6 +170,7 @@stackTrace={latestOccurrence?.stackTrace ?? group.stackTrace}{isMessage}{isJavaScript}+ {isFlutter}firstSeen={group.firstSeen}lastSeen={group.lastSeen}totalCount={group.count}diff --git a/frontend/src/routes/issues/[exceptionHash]/[exceptionId]/+page.svelte b/frontend/src/routes/issues/[exceptionHash]/[exceptionId]/+page.svelteindex 6dae9f18..10a94c2c 100644--- a/frontend/src/routes/issues/[exceptionHash]/[exceptionId]/+page.svelte+++ b/frontend/src/routes/issues/[exceptionHash]/[exceptionId]/+page.svelte@@ -36,6 +36,7 @@? isJsFramework(projectsState.currentProject.framework): false) || isJsLanguage(occurrence?.attributes?.['telemetry.sdk.language']));+ const isFlutter = $derived(projectsState.currentProject?.framework === 'flutter');const firstLineOfStackTrace = $derived(occurrence?.stackTrace.split('\n')[0] || 'Exception');const hasMoreOccurrences = $derived(total > 10);const subtitleText = $derived(occurrence ? `Event from ${formatDateTime(occurrence.recordedAt, { timezone })}` : 'Loading...');@@ -175,6 +176,7 @@stackTrace={occurrence.stackTrace}{isMessage}{isJavaScript}+ {isFlutter}bind:showArchiveDialog={showArchiveDialog}bind:archiving={archiving}/>diff --git a/skills/traceway-setup/SKILL.md b/skills/traceway-setup/SKILL.mdindex 69d4d5f7..59a0fe4b 100644--- a/skills/traceway-setup/SKILL.md+++ b/skills/traceway-setup/SKILL.md@@ -13,7 +13,7 @@ Connect an existing project to a Traceway instance so it reports endpoints, span|---|---|---|| **Instance URL** | `https://traceway.example.com` | The URL of the Traceway dashboard || **Project token** | `abc123...` | Traceway dashboard -> Connection page |-| **Source map upload token** (optional, frontend only) | `def456...` | Traceway dashboard -> Connection page -> Source Maps |+| **Upload token** (optional; frontend source maps and obfuscated Flutter symbols) | `def456...` | Traceway dashboard -> Connection page -> Source Maps / Symbol Upload |Instance URL and project token may be provided in the invocation (e.g. `/traceway-setup with token abc123 and url https://traceway.example.com`). If either is missing:@@ -247,7 +247,7 @@ For the per-framework init code (plain JS, React, Vue, Svelte/SvelteKit, jQuery)**Mobile**, always the platform SDK, never OTel:-- **Flutter**: `flutter pub add traceway`, then `Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())`. For options, platform permissions, the navigator observer, screen recording, privacy masking, and the Flutter web caveat, read `flutter.md` in this skill directory. Docs: https://docs.tracewayapp.com/client/flutter+- **Flutter**: `flutter pub add traceway`, then `Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())`. Then check whether the release build is obfuscated (`--obfuscate --split-debug-info`): if it is, production crash stack traces arrive obfuscated and stay unreadable until the build's `.symbols` files are uploaded, so ask the user for the upload token (Step 0) and wire up the symbol upload. For options, platform permissions, the navigator observer, screen recording, privacy masking, the obfuscation check and symbol upload, and the Flutter web caveat, read `flutter.md` in this skill directory. Docs: https://docs.tracewayapp.com/client/flutter- **React Native**: `npm install @tracewayapp/react-native`, wrap the app in `TracewayProvider`. Docs: https://docs.tracewayapp.com/client/react-native- **Android**: `implementation("com.tracewayapp:traceway:<version>")`, call `Traceway.init(...)` at startup. Docs: https://docs.tracewayapp.com/client/android@@ -287,7 +287,7 @@ Metrics arrive within ~60s under their hostmetrics names (`system.cpu.utilizatio1. Start the app and hit a few endpoints (or trigger an error on purpose).2. Check the Traceway dashboard:- **Endpoints page**: routes appear grouped by pattern (e.g. `GET /api/users/:id`), not by literal URL, and status codes are non-zero.- - **Issues page**: thrown errors appear with stack traces. For frontend projects, stack traces are symbolicated to original files and lines.+ - **Issues page**: thrown errors appear with stack traces. For frontend projects, stack traces are symbolicated to original files and lines; for obfuscated Flutter builds, they resolve once the build's `.symbols` files have been uploaded.- **Endpoint detail -> Spans tab**: database queries and outgoing calls appear as children.- **Tasks page**: after triggering each background job once, it appears under one stable name.- **AI Traces page** (if Step 4 applied): model calls appear with token counts and cost.diff --git a/skills/traceway-setup/flutter.md b/skills/traceway-setup/flutter.mdindex df945b72..daaee627 100644--- a/skills/traceway-setup/flutter.md+++ b/skills/traceway-setup/flutter.md@@ -119,6 +119,50 @@ Every captured exception ships with the last ~10 seconds of context from two rol);```+## Symbol upload (obfuscated builds)++A plain `flutter build --release` keeps enough symbol information that crash stack traces are already readable (function names plus `file:line`), and the SDK reports them as-is. You only need symbol upload when the build is hardened with `--obfuscate` and/or `--split-debug-info=<dir>`: those flags strip and rename Dart symbols into per-architecture `.symbols` files, so production traces then arrive as bare instruction offsets and stay unreadable until Traceway resolves them server-side from the build's `.symbols` files (the same way it handles JavaScript source maps).++**First, check whether the build is obfuscated.** Look at how release artifacts are produced (the `flutter build` invocations in CI under `.github/`, in `fastlane/`, in a `Makefile`, or in shell scripts) and ask the user how they build for release. If neither `--obfuscate` nor `--split-debug-info` is passed, stack traces are already readable and symbol upload is unnecessary; skip the rest of this section. If obfuscation is (or will be) used, set up the upload.++**Then ask for the upload token.** Symbol uploads authenticate with the dedicated upload token (Connection page > Symbol Upload, the same token shown under Source Maps), NOT the project token from the connection string. Get it from Step 0; it is a CI secret, never committed. `readonly` members cannot generate one.++The `traceway` package ships an uploader (`dart run traceway:upload_symbols`) that finds the `.symbols` files, derives each one's architecture and debug ID, and posts them. Configure it once, then run it on every release.++**One-time setup.** Add a `traceway:` block to the app's `pubspec.yaml`:++```yaml+traceway:+ url: https://<instance> # omit on Traceway Cloud+ # upload_token: ... # prefer the env var below, especially in CI+```++The upload token resolves from `TRACEWAY_UPLOAD_TOKEN` (or `--token`) before the `upload_token` key, so keep it out of `pubspec.yaml` in CI.++**Per release.** Build with obfuscation and a known symbols directory, then run the uploader:++```bash+flutter build apk --release --obfuscate --split-debug-info=build/symbols++TRACEWAY_UPLOAD_TOKEN=<upload-token> dart run traceway:upload_symbols+```++The uploader auto-discovers `build/symbols` and uploads every architecture in one run, so no flags are required. Each value resolves from a CLI flag first (`--token`, `--url`, `--symbols-dir`), then an env var (`TRACEWAY_UPLOAD_TOKEN`, `TRACEWAY_URL`), then the `pubspec.yaml` block. Pass `--dry-run` to preview. Symbols are unique to each build, so upload on every release; a crash only resolves against the exact build it came from.++The build command above produces an Android APK; other targets (`appbundle`, `ios`, `macos`) emit their own `.symbols` files into the same directory, all picked up by a single uploader run. On Android the debug ID is read straight from each file's build-id note. iOS and macOS `.symbols` carry no such note, so the uploader reads the Mach-O UUID from the built `.app` (auto-discovered under `build/`, or point at it with `--app build/macos/Build/Products/Release/YourApp.app`); run the uploader on the same Mac that produced the build. There is no hand-written upload path for Apple builds because that UUID can only be read from the compiled app.++Wire the upload into the release pipeline right after the build step (CI, fastlane, or a build script), with the token from a secret:++```yaml+- name: Upload Flutter symbols+ run: dart run traceway:upload_symbols+ env:+ TRACEWAY_URL: ${{ secrets.TRACEWAY_URL }}+ TRACEWAY_UPLOAD_TOKEN: ${{ secrets.TRACEWAY_UPLOAD_TOKEN }}+```++Self-hosted instances must have blob storage (S3 or a persistent volume) configured, or uploaded symbols disappear when the container is recreated.+## Flutter webThe Flutter SDK does not support web (no error tracking, no screen recording there). For Flutter web apps, use the JS SDK in `web/index.html` instead:@@ -139,4 +183,4 @@ final res = await client.get(Uri.parse('https://api.example.com/users'));## Verify-Add a button that throws (`throw StateError('Test error from Traceway')`), tap it, and check the Issues page in the dashboard. With `screenCapture: true`, the recording appears alongside the stack trace.+Add a button that throws (`throw StateError('Test error from Traceway')`), tap it, and check the Issues page in the dashboard. With `screenCapture: true`, the recording appears alongside the stack trace. For an obfuscated release build, confirm the stack trace shows real frames rather than obfuscated offsets once the matching `.symbols` files have been uploaded.diff --git a/website/app/product/javascript-symbolication/page.tsx b/website/app/product/symbolication/page.tsxsimilarity index 53%rename from website/app/product/javascript-symbolication/page.tsxrename to website/app/product/symbolication/page.tsxindex 7cdbe98d..cf75596c 100644--- a/website/app/product/javascript-symbolication/page.tsx+++ b/website/app/product/symbolication/page.tsx@@ -1,12 +1,11 @@import Link from "next/link";import Image from "next/image";import type { Metadata } from "next";-import { ArrowRight, Github, BookOpen, Workflow } from "lucide-react";+import { Github, BookOpen, Workflow } from "lucide-react";import { Eyebrow } from "@/components/eyebrow";import { SectionHead } from "@/components/section-head";import { StatsStrip } from "@/components/stats-strip";-import { FeatureRow } from "@/components/feature-row";import { FaqList } from "@/components/faq-list";import { FinalCTA } from "@/components/final-cta";import { AuroraBackground } from "@/components/aurora-background";@@ -15,9 +14,9 @@ import { SymbolicationBeforeAfter } from "@/components/symbolication-before-afteimport { GITHUB_URL } from "@/lib/links";export const metadata: Metadata = {- title: "JavaScript Stack Trace Symbolication · Traceway",+ title: "Stack Trace Symbolication · Traceway",description:- "Open-source, OpenTelemetry-compatible source map symbolication. Resolve minified production errors back to the original file, line, and function at ingest. Pure Go, built to be fast.",+ "Open-source, OpenTelemetry-compatible symbolication for JavaScript source maps and Dart/Flutter obfuscation maps. Resolve minified production errors back to the original file, line, and function at ingest. Pure Go, built to be fast.",};const BUNDLERS = [@@ -31,7 +30,74 @@ const BUNDLERS = ["Cloudflare Workers",];-export default function JavaScriptSymbolicationPage() {+const LANGUAGE_TILES = [+ {+ src: "/images/frameworks/flutter.png",+ alt: "Flutter",+ w: 250,+ h: 250,+ size: 104,+ z: 30,+ pos: "left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2",+ engine: true,+ },+ {+ src: "/images/frameworks/javascript.png",+ alt: "JavaScript",+ w: 45,+ h: 45,+ size: 72,+ z: 20,+ pos: "left-[23%] top-[16%]",+ },+ {+ src: "/images/frameworks/node.png",+ alt: "Node",+ w: 52,+ h: 64,+ size: 68,+ z: 20,+ pos: "right-[19%] top-[14%]",+ },+ {+ src: "/images/frameworks/remix.png",+ alt: "Remix",+ w: 45,+ h: 45,+ size: 50,+ z: 10,+ pos: "left-1/2 top-[5%] -translate-x-1/2",+ },+ {+ src: "/images/frameworks/react.png",+ alt: "React",+ w: 45,+ h: 40,+ size: 56,+ z: 10,+ pos: "right-[17%] top-[50%]",+ },+ {+ src: "/images/frameworks/svelte.png",+ alt: "Svelte",+ w: 45,+ h: 45,+ size: 62,+ z: 20,+ pos: "left-[20%] bottom-[16%]",+ },+ {+ src: "/images/frameworks/nextjs.png",+ alt: "Next.js",+ w: 45,+ h: 45,+ size: 60,+ z: 20,+ pos: "right-[37%] bottom-[13%]",+ },+];++export default function SymbolicationPage() {return (<main className="relative"><section className="hero hero-product relative">@@ -69,12 +135,17 @@ export default function JavaScriptSymbolicationPage() {</p><div className="hero-cta-row justify-center"><Link- href="https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload"+ href="https://cloud.tracewayapp.com/register"className="btn btn-accent">- Upload your source maps <ArrowRight className="h-4 w-4" />+ Start for free</Link>- <Link href={GITHUB_URL} className="btn btn-ghost" target="_blank" rel="noopener noreferrer">+ <Link+ href={GITHUB_URL}+ className="btn btn-ghost"+ target="_blank"+ rel="noopener noreferrer"+ ><Github className="h-4 w-4" />View on GitHub</Link>@@ -90,103 +161,118 @@ export default function JavaScriptSymbolicationPage() {<SymbolicationBeforeAfter /><section className="wrap py-20">- <SectionHead- eyebrow="Performance"- title={- <>- Symbolication that <em>keeps up with ingest.</em>- </>- }- description="Most symbolicators re-parse source maps on every restart and hold them in RAM until the process dies. Ours compiles each map once, then memory-maps it from disk. Numbers below come from the benchmark workflows in the repo."- />- <StatsStrip- stats={[- { num: "<em><1</em>µs", label: "To open a compiled source map" },- { num: "<em><1</em>ms", label: "p99 lookup with a cold cache" },- { num: "<em>3</em>×", label: "Faster bundle parsing than SWC" },- { num: "<em>0</em>", label: "Maps re-parsed after a restart" },- ]}- />- <div className="mt-14 grid gap-12 md:grid-cols-2">- <div className="border-t border-hair pt-8">- <p className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">- Why it stays fast- </p>- <ul className="mt-4 space-y-3 text-[14px]" style={{ color: "var(--fg-2)" }}>- <li>- <strong style={{ color: "var(--fg-1)" }}>Parse once, compile to .tw.</strong>{" "}- Each map and bundle compiles into a binary format on first- use. Every lookup after that opens the file in under a- microsecond and binary-searches it.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Disk is the budget, not RAM.</strong>{" "}- Compiled maps are memory-mapped, so resident memory tracks- the hot set. A corpus of thousands of bundles costs disk- space, not heap.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Cold lookups don’t hurt.</strong>{" "}- An in-RAM LRU churns the garbage collector every time an old- release throws. The mmap cache holds p99 under a millisecond- on the long tail.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Restarts warm from disk.</strong>{" "}- Nothing is re-parsed when the process comes back. The cache- is already there.- </li>- </ul>+ <div className="grid items-center gap-12 md:grid-cols-[1fr_0.9fr] md:gap-14">+ <div className="order-2 md:order-1">+ <div+ className="relative hidden h-[360px] md:block"+ aria-hidden="true"+ >+ {LANGUAGE_TILES.map((t) => (+ <div+ key={t.alt}+ title={t.alt}+ className={`absolute grid place-items-center rounded-2xl border border-hair-2 bg-ink-0 ${t.pos}`}+ style={{+ width: t.size,+ height: t.size,+ zIndex: t.z,+ boxShadow: "0 12px 28px -16px rgba(10, 14, 24, 0.25)",+ }}+ >+ <Image+ src={t.src}+ alt=""+ width={t.w}+ height={t.h}+ style={{+ height: Math.round(t.size * (t.engine ? 0.56 : 0.5)),+ width: "auto",+ }}+ />+ </div>+ ))}+ </div>+ <div className="flex flex-wrap gap-3 md:hidden">+ {LANGUAGE_TILES.filter((t) => !t.engine).map((t) => (+ <div+ key={t.alt}+ title={t.alt}+ className="grid size-14 shrink-0 place-items-center rounded-2xl border border-hair-2 bg-ink-0"+ style={{+ boxShadow: "0 12px 28px -16px rgba(10, 14, 24, 0.25)",+ }}+ >+ <Image+ src={t.src}+ alt={t.alt}+ width={t.w}+ height={t.h}+ className="h-8 w-auto"+ />+ </div>+ ))}+ </div></div>- <div className="border-t border-hair pt-8">- <p className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">- The fine print+ <div className="order-1 md:order-2">+ <Eyebrow>Languages & throughput</Eyebrow>+ <h3+ className="mt-4 text-[22px] leading-tight text-pretty"+ style={{ color: "var(--fg-0)" }}+ >+ JavaScript, Dart, Flutter, and more coming soon.+ </h3>+ <p+ className="mt-4 text-[15px] text-pretty"+ style={{ color: "var(--fg-2)" }}+ >+ One engine reads JavaScript source maps and Dart and Flutter+ obfuscation maps through the same compiled cache, plus every JS+ framework that ships them, from React and Svelte to Next.js and+ Remix. Even on the cheapest box we tested, a 2 vCPU Hetzner{" "}+ <code>ccx13</code>, it clears{" "}+ <strong style={{ color: "var(--fg-0)" }}>+ over 32× the stack traces per second+ </strong>{" "}+ of Honeycomb’s symbolicator.+ <sup className="ml-0.5" style={{ color: "var(--a2)" }}>+ *+ </sup>+ </p>+ <p+ className="mt-5 text-[12px]"+ style={{ color: "var(--fg-3)", fontFamily: "var(--font-mono)" }}+ >+ * Measured running as an OpenTelemetry Collector. The full+ benchmark workflow lives in the repo.</p>- <ul className="mt-4 space-y-3 text-[14px]" style={{ color: "var(--fg-3)" }}>- <li>- <strong style={{ color: "var(--fg-1)" }}>Two parser engines.</strong>{" "}- The default build is pure Go and parses bundles with{" "}- <code>dop251/goja</code>. A build flag swaps in{" "}- <code>oxc</code>, which{" "}- <Link- href="https://oxc.rs/docs/guide/usage/parser.html"- target="_blank"- rel="noopener noreferrer"- className="underline decoration-dotted underline-offset-4 hover:text-[color:var(--a2)]"- >- parses 3x faster than SWC- </Link>- .- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Two cache modes.</strong>{" "}- Hold parsed maps in memory, or compile them to{" "}- <code>.tw</code> files and memory-map them from disk.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Not memory bound.</strong>{" "}- With oxc and the disk cache, the corpus is a disk budget: the- cache holds as many maps as the disk fits. Competing- symbolicators cache parsed maps in RAM, so their corpus caps- out at what the heap can hold.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>Benchmarked in the open.</strong>{" "}- Parser numbers come from <code>go test -bench</code> over- webpack, Metro, and Preact fixtures plus 1 MB and- 5 MB synthetic bundles. Cache numbers come from a sweep- of 1,000 to 12,000 bundles on a 2 vCPU box. Both- workflows are in the repo; run them on your fork.- </li>- <li>- <strong style={{ color: "var(--fg-1)" }}>MIT licensed, actually open source.</strong>{" "}- The parsers, the cache, the collector processor, and the- whole backend live in one public repo. No open core, no- enterprise tier where symbolication really lives.- </li>- </ul></div></div>++ <div className="mt-20">+ <SectionHead+ eyebrow="Performance"+ title={+ <>+ Symbolication that <em>keeps up with ingest.</em>+ </>+ }+ description="Most symbolicators re-parse source maps on every restart and hold them in RAM until the process dies. Ours compiles each map once, then memory-maps it from disk. The numbers below come straight from the benchmark workflow in the repo, run head to head against Honeycomb's symbolicator on Hetzner hardware."+ />+ <StatsStrip+ stats={[+ { num: "<em>30K+</em>", label: "Stacks/s, hot or cold" },+ {+ num: "<em>32</em>×",+ label: "Honeycomb's throughput under churn",+ },+ {+ num: "<em>18</em>ms",+ label: "Churn p99, where Honeycomb hits ~3s",+ },+ { num: "<em>361</em>MB", label: "Peak under churn, vs 4.5 GB" },+ ]}+ />+ </div></section><section className="wrap">@@ -200,14 +286,17 @@ export default function JavaScriptSymbolicationPage() {The same engine ships as an OpenTelemetry Collector processor.It’s a drop-in replacement for Honeycomb’s{" "}<code>source_map_symbolicator</code>: same component type, same- attribute contract, same config keys. Existing pipelines and- web instrumentation work unchanged.+ attribute contract, same config keys. Existing pipelines and web+ instrumentation work unchanged.</p><ul className="feat-bullets"><li>Symbolicates spans, span events, and log records</li><li>Cache bounded by disk size, not an entry count in RAM</li><li>Pure Go, so no glibc base image required</li>- <li>Works in any collector build, with or without Traceway behind it</li>+ <li>+ Works in any collector build, with or without Traceway behind+ it+ </li></ul></div><OtelPipelineTabs />@@ -217,7 +306,10 @@ export default function JavaScriptSymbolicationPage() {<section className="wrap pb-10"><divclassName="rounded-2xl px-6 py-8 md:px-10 md:py-10"- style={{ background: "var(--ink-1)", border: "1px solid var(--hair)" }}+ style={{+ background: "var(--ink-1)",+ border: "1px solid var(--hair)",+ }}><div className="grid gap-8 md:grid-cols-[1.2fr_1fr] items-center"><div>@@ -225,10 +317,13 @@ export default function JavaScriptSymbolicationPage() {<h3 className="mt-3 text-[22px] leading-tight">Read the parser. Run the benchmarks. Self-host all of it.</h3>- <p className="mt-3 text-[14px] max-w-[520px]" style={{ color: "var(--fg-2)" }}>+ <p+ className="mt-3 text-[14px] max-w-[520px]"+ style={{ color: "var(--fg-2)" }}+ >The symbolicator, the benchmark harnesses, and the rest of- Traceway live in one MIT-licensed repo. Nothing about how- your stack traces get resolved is a black box.+ Traceway live in one MIT-licensed repo. Nothing about how your+ stack traces get resolved is a black box.</p><div className="mt-5 flex flex-wrap gap-2">{BUNDLERS.map((b) => (@@ -244,27 +339,36 @@ export default function JavaScriptSymbolicationPage() {target="_blank"rel="noopener noreferrer"className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"- style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}+ style={{+ color: "var(--fg-1)",+ fontFamily: "var(--font-mono)",+ }}><Github className="h-3.5 w-3.5" />traceway →</Link><Link- href="https://github.com/tracewayapp/traceway/tree/main/backend/app/symbolicator/otelprocessor"+ href="https://docs.tracewayapp.com/symbolicator/opentelemetry"target="_blank"rel="noopener noreferrer"className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"- style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}+ style={{+ color: "var(--fg-1)",+ fontFamily: "var(--font-mono)",+ }}><Workflow className="h-3.5 w-3.5" />OTel processor →</Link><Link- href="https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload"+ href="https://docs.tracewayapp.com/symbolicator"target="_blank"rel="noopener noreferrer"className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"- style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}+ style={{+ color: "var(--fg-1)",+ fontFamily: "var(--font-mono)",+ }}><BookOpen className="h-3.5 w-3.5" />Documentation →@@ -284,7 +388,7 @@ export default function JavaScriptSymbolicationPage() {description="Upload your source maps once. Every production error after that points at the code you wrote."primary={{label: "Get Started",- href: "https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload",+ href: "https://docs.tracewayapp.com/symbolicator/javascript",}}secondary={{label: "Star on GitHub",@@ -319,6 +423,10 @@ export default function JavaScriptSymbolicationPage() {q: "Which bundlers and frameworks are supported?",a: "Anything that emits standard source maps: Vite, webpack, esbuild, Rollup, Metro, and the frameworks built on them. Inline sourceMappingURL data URIs are supported, and maps with missing source file names still resolve line, column, and function name.",},+ {+ q: "Does it symbolicate Dart and Flutter?",+ a: "Yes. The same engine reads Dart obfuscation maps and resolves obfuscated Flutter and Dart stack traces back to your original symbols. It runs through the same compiled-cache pipeline as JavaScript, and the benchmark above shows both cache modes surviving every load scenario, including the memory-starved OOM box.",+ },{q: "Are my source maps exposed publicly?",a: "No. Maps are uploaded to your Traceway instance's blob storage and used server-side only. They are never served to browsers, so you can keep .map files out of your deployed assets entirely.",diff --git a/website/components/site-footer.tsx b/website/components/site-footer.tsxindex bf6897b0..92343def 100644--- a/website/components/site-footer.tsx+++ b/website/components/site-footer.tsx@@ -27,7 +27,7 @@ const COLUMNS: Column[] = [{ label: "AI Tracing", href: "/product/ai-tracing" },{ label: "Performance", href: "/product/performance" },{ label: "Flutter Session Replay", href: "/product/flutter-session-replay" },- { label: "JavaScript Symbolication", href: "/product/javascript-symbolication" },+ { label: "Symbolicator", href: "/product/symbolication" },],},{diff --git a/website/components/site-header.tsx b/website/components/site-header.tsxindex 1cb33a81..e394d400 100644--- a/website/components/site-header.tsx+++ b/website/components/site-header.tsx@@ -88,9 +88,9 @@ const SPECIALIZED: NavItem[] = [icon: Smartphone,},{- title: "JavaScript Symbolication",- description: "Minified stack traces, resolved to your source.",- href: "/product/javascript-symbolication",+ title: "Symbolicator",+ description: "Minified JS and Dart stack traces, resolved to your source.",+ href: "/product/symbolication",icon: Braces,},];diff --git a/website/public/_redirects b/website/public/_redirectsindex 0897d5c4..5f3053ce 100644--- a/website/public/_redirects+++ b/website/public/_redirects@@ -1,5 +1,6 @@/product/issue-tracking /product/stack-traces 301/product/distributed-tracing /product/traces 301+/product/javascript-symbolication /product/symbolication 301/blog/engineering /blog 301/blog/android-sdk-1.0.0 /releases/android-sdk-1.0.0 301diff --git a/website/public/images/frameworks/flutter.png b/website/public/images/frameworks/flutter.pngnew file mode 100644index 00000000..f1b32df8Binary files /dev/null and b/website/public/images/frameworks/flutter.png differdiff --git a/website/public/images/frameworks/javascript.png b/website/public/images/frameworks/javascript.pngnew file mode 100644index 00000000..fff4d487Binary files /dev/null and b/website/public/images/frameworks/javascript.png differdiff --git a/website/public/images/frameworks/react.png b/website/public/images/frameworks/react.pngnew file mode 100644index 00000000..75b5163eBinary files /dev/null and b/website/public/images/frameworks/react.png differ