Skip to main content

Uploading Debuginfos

In order to resolve memory addresses to human readable function names for compiled languages such as Go, Rust, C, C++, or Haskell, you must provide these mappings (referred to as debuginfos) to Polar Signals Cloud.

Ideally debuginfos are available in the production binaries, as then the agent installed on a node and recording the profiling data can extract them and everything works automatically.

For various reasons this may be impractical, for example because debuginfos can dramatically increase the binary size.

Solution​

The solution to this problem is to upload debuginfos out of band, using the parca-debuginfo CLI. This is typically done in a CI/CD pipeline.

Install the CLI​

Download it:

curl -sL https://github.com/parca-dev/parca-debuginfo/releases/download/v0.11.0/parca-debuginfo_0.11.0_`uname -s`_`uname -m`.tar.gz > parca-debuginfo_0.11.0_`uname -s`_`uname -m`.tar.gz

Verify the checksum:

curl -sL https://github.com/parca-dev/parca-debuginfo/releases/download/v0.11.0/checksums.txt | shasum --ignore-missing -a 256 --check

And unpack it:

tar -xzf parca-debuginfo_0.11.0_`uname -s`_`uname -m`.tar.gz parca-debuginfo

If you want to move the CLI to a path in your `$PATH` you can move the binary (adjust to your preferred location):

mv parca-debuginfo /usr/local/bin/parca-debuginfo

Obtain a token​

Next you'll need to obtain an authentication token to upload the debuginfos to your Polar Signals Cloud project. See the Generating Tokens page to learn how.

Upload​

Finally you can use the authentication token to issue the upload command:

parca-debuginfo upload --store-address=grpc.polarsignals.com:443 --bearer-token=<the-token-you-obtained> /path/to/your/binary

Troubleshooting​

Below are some common troubleshooting scenarios and solutions.

Debuginfo Already Exists​

For various reasons debuginfo with the same build ID might already exist. For example the agent eagerly uploaded debuginfos from the production binary but they were not high quality, because the high quality debuginfos are split off of the production binary in build pipelines.

If you still want to replace the existing debuginfos with the debuginfos use the --force flag. So the full command might look something like this:

parca-debuginfo upload --store-address=grpc.polarsignals.com:443 --bearer-token=<the-token-you-obtained> /path/to/your/binary --force