AutoMerge is generally available

Last updated:

Upload Source Maps

Make Node.js profiles of bundled, minified, or transpiled code show the original function names, files, and lines by uploading source maps to Dash0.

Bundlers, transpilers, and minifiers change the JavaScript that Node.js runs. Profiles of this code show the names and positions of the generated code, such as function i in dist/server.js at line 1. When you upload source maps, Dash0 shows these frames with the original function name, source file, line, and column, such as computeFibonacci in src/fibonacci.ts at line 5.

This page is about profiles of Node.js services. For browser profiles and stack traces of browser errors, Dash0 downloads source maps from your web servers instead. See Resolve Stack Traces with Source Maps.

How Dash0 finds the source map of a frame

Dash0 uses a debug ID to find the source map of a JavaScript frame. A debug ID is a UUID that identifies one build of one JavaScript file.

  1. At build time, an upload tool calculates a debug ID for each JavaScript file from the content of its source map. It writes the debug ID into both files and uploads the source map to Dash0.
  2. At runtime, the Parca Agent reads the debug ID from each JavaScript file that Node.js loads. The agent sends the debug ID as the build ID of the frames in that file.
  3. When you view a profile, Dash0 finds the source map by the build ID of each frame and resolves the frame.

The same build output always gets the same debug ID, so the tools do not upload a source map again when Dash0 already has it.

A source map that you upload later also applies to profiles that Dash0 received before the upload. Dash0 keeps source maps for the organization, so profiles in all its datasets use them.

Before you begin

  • Collect profiles with the Parca Agent v0.47.0 or later. The operator-managed Parca Agent meets this requirement. For frames from other profilers, Dash0 uses a source map only when the profiler sends the debug ID as the build ID of the frame.
  • Configure your build tool to write each source map to a separate .js.map file. The upload tools find a source map through the //# sourceMappingURL= comment of the JavaScript file, or as <file>.js.map next to it. They ignore inline source maps.
  • Get an auth token with the Ingesting permission (ingest:*), or with the ingest:debuginfo action. The per-signal action ingest:profiles does not permit uploads. Keep the token in your CI secrets.
  • Identify the OTLP gRPC endpoint of your organization, such as ingress.eu-west-1.aws.dash0.com:4317.

Upload with the CLI

Use the @polarsignals/sourcemap-cli package with build tools that write .js and .js.map files, such as tsc, Rollup, webpack, or swc. Run it in your CI pipeline after the build step and before you package or deploy the build output:

sh
npx @polarsignals/sourcemap-cli dist \
  --server-url ingress.YOUR_REGION.dash0.com:4317 \
  --token "$DASH0_AUTH_TOKEN" \
  --project-id YOUR_DATASET
  • Replace dist with your build output directory.
  • Replace the server URL with the OTLP gRPC endpoint of your organization.
  • Set --project-id to the identifier of the dataset that receives the profiles. The CLI requires this option, but Dash0 ignores its value.

The CLI changes the files in the directory. It adds a //# debugId=<UUID> comment at the end of each JavaScript file and a debugId field to each source map. Deploy the JavaScript files that the CLI changed. You do not need to deploy the .js.map files.

To select JavaScript files, use --include and --exclude with glob patterns. To write the debug IDs without an upload, use --dry-run. To see all options, run the CLI with --help.

Upload with the esbuild plugin

If you build with esbuild, use the @polarsignals/sourcemap-esbuild-plugin package. It writes the debug IDs and uploads the source maps at the end of each build:

js
import esbuild from "esbuild";
import { debugIdPlugin } from "@polarsignals/sourcemap-esbuild-plugin";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  platform: "node",
  sourcemap: true,
  outfile: "dist/index.js",
  plugins: [
    debugIdPlugin({
      debuginfoServerUrl: "ingress.YOUR_REGION.dash0.com:4317",
      token: process.env.DASH0_AUTH_TOKEN,
      projectID: "YOUR_DATASET",
    }),
  ],
});

Always set debuginfoServerUrl to the OTLP gRPC endpoint of your organization. Without it, the plugin sends your source maps to Polar Signals, not to Dash0. The plugin does not read the server URL from an environment variable.

Set projectID to the identifier of the dataset that receives the profiles. Dash0 ignores its value.

The plugin needs outfile or outdir, and a sourcemap value that writes .js.map files, such as true. Deploy the JavaScript files from the same build.

What the upload contains

The upload tools send each JavaScript file and its complete source map. A source map can contain your original source code. See Source map uploads for how to keep it out of the upload.

Check the result

Open Profiling under Telemetry and use Filter profiles... to select your Node.js service. JavaScript frames show the original source files, such as .ts files, and the original function names.

If a frame still shows a generated .js file, compare the Build ID of the frame with the //# debugId= comment at the end of the deployed JavaScript file:

What you seeWhat to do
The frame has no build ID.Check the Parca Agent version. Check that the deployed JavaScript file has the //# debugId= comment.
The build ID is different from the debug ID in your build output.Deploy the JavaScript files that the upload tool changed.
The build ID is the same, but the frame is not resolved.Upload the source map of this build. Use a token and an endpoint from the organization and region that receive the profiles.

Further Reading