Monitoring

Readable stack traces

Production code is minified or compiled. Without symbols, a stack trace reads a.b.c:1:4823 and tells you nothing. Symbolication maps those frames back to your real files and lines.

This is the step most teams skip and then wonder why monitoring isn't useful.

Two kinds of upload

Which one you need depends on how your language reaches production.

Your language	Command	What you upload
JavaScript, Dart	`sourcemaps upload`	`.map` files
Go, Rust, Java, Kotlin, Swift	`sources upload`	Source files

Minified means sourcemaps, compiled means sources

If your build minifies, the frames are mangled and a source map unmangles them. If your build compiles to a binary, the frames already carry the real file and line, but the binary ships without the code, so the dashboard has nothing to show you until you upload it.

octri-monitoring sourcemaps upload ./dist \
  --url https://monitoring.example.com \
  --token "$MONITORING_TOKEN" \
  --environment "$MONITORING_ENVIRONMENT" \
  --release "$GIT_SHA"

The release id has to match exactly

This is the single most common reason symbolication silently fails.

A mismatch is silent

The release your SDK reports at runtime through logging.release and the release you pass to the CLI must be the same string. If they differ by so much as a v prefix, the upload succeeds, the traces stay unreadable, and nothing warns you.

Use the git SHA on both sides:

export GIT_SHA="$(git rev-parse HEAD)"

The CLI defaults --release to git rev-parse HEAD, so inside a git checkout it usually matches without you doing anything.

Check before you trust it

--dry-run lists exactly what would be sent and the release id it resolved, without uploading:

octri-monitoring sourcemaps upload ./dist --dry-run

[dry-run] would upload 3 map(s) for release 9f2c1ab:
  dist/index.js.map
  dist/vendor.js.map
  dist/runtime.js.map

If the release there doesn't match what your SDK reports, fix it before you deploy.

Never ship maps to users

Uploading maps to Octri is not the same as serving them

Uploading to Octri makes traces readable in the dashboard. Serving those same .map files from your public web server hands your original source to anyone who opens devtools.

Upload them, then delete them from the deployed bundle.

When it isn't working

CLI reference

Every flag and environment variable.

CI setup

Upload automatically on every build.

Why the release has to match

The reasoning behind the rule on this page, on the blog.