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:

wget https://github.com/parca-dev/parca-debuginfo/releases/download/v0.13.0/parca-debuginfo_0.13.0_`uname -s`_`uname -m`

Verify the checksum:

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

Make it executable:

chmod +x parca-debuginfo_0.13.0_`uname -s`_`uname -m`

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

sudo mv parca-debuginfo_0.13.0_`uname -s`_`uname -m` /usr/local/bin/parca-debuginfo

Obtain a Service Account Token and Project ID​

Next you'll need:

  1. A service account token for authentication
  2. Your project ID to specify which project to upload to

See the Generating Tokens page to learn how to create a service account and generate a token.

Upload​

Finally you can use the service account token and project ID to issue the upload command:

parca-debuginfo upload \
  --store-address=grpc.polarsignals.com:443 \
  --bearer-token=<your-service-account-token> \
  --grpc-headers=projectID=<your-project-id> \
  /path/to/your/binary

Replace:

  • <your-service-account-token> with your actual service account token
  • <your-project-id> with your actual project ID

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=<your-service-account-token> \
  --grpc-headers=projectID=<your-project-id> \
  /path/to/your/binary \
  --force