How to Upload Symbol Files with Symbol-Upload

Overview 👀

Symbol-upload is a cross-platform application that automatically uploads symbol files as part of your build process and is the successor of SendPdbs. Each build of your product that sends crash reports must have an exact set of matching symbol files uploaded to BugSplat.

The symbol-upload tool can be installed by npm and used as a CLI tool or a javascript library. We also provide a GitHub Action that can be added to your build workflow.

npm i -g @bugsplat/symbol-upload

Alternatively, you can use one of the following terminal commands to download prebuilt binaries of symbol-upload, or download with your web browser via the GitHub releases page.

If you download symbol-upload-macos via a web browser, Gatekeeper will block the application from running. To add the application to the system's allow list, run the following command in terminal

xattr -r -d com.apple.quarantine ./symbol-upload-macos

Windows

Invoke-WebRequest -Uri "https://app.bugsplat.com/download/symbol-upload-windows.exe" -OutFile "symbol-upload-windows.exe"

macOS

curl -sL -O "https://app.bugsplat.com/download/symbol-upload-macos" && chmod +x symbol-upload-macos

Linux

curl -sL -O  "https://app.bugsplat.com/download/symbol-upload-linux" && chmod +x symbol-upload-linux

A group of symbols identified by their application name and version is called a symbol store. Symbol-upload automatically creates a new symbol store each time you upload symbols to a unique application and version combination. BugSplat's backend automatically removes symbols that haven't been accessed recently. Using our web application, you can manually delete a symbol store. Send symbols to BugSplat for every build on your build/integration server. There is no limit on the number of symbols you can post to BugSplat. However, by default, each symbol file must be smaller than 4 GB.

Using symbol-upload 🧑‍💻

Running symbol-upload in a command window without any arguments shows the following usage information:

bobby@BugSplat % ~ % symbol-upload -h

@bugsplat/symbol-upload v10.2.0

  symbol-upload contains a command-line utility and a set of libraries to help  
  you upload symbol files to BugSplat.                                          

Usage

  -h, --help                             Print this usage guide.                                                       
  -b, --database string                  Your BugSplat database name. The value of database must match the value used  
                                         to post crash reports. This value can also be provided via the                
                                         BUGSPLAT_DATABASE environment variable.                                       
  -a, --application string               The name of your application. If not provided symbol-upload will attempt to   
                                         use the value of the name field in package.json if it exists in the current   
                                         working directory.                                                            
  -v, --version string                   Your application's version. If not provided symbol-upload will attempt to use 
                                         the value of the version field in package.json if it exists in the current    
                                         working directory.                                                            
  -u, --user string (optional)           The email address used to log into your BugSplat account. If provided         
                                         --password must also be provided. This value can also be provided via the     
                                         SYMBOL_UPLOAD_USER environment variable.                                      
  -p, --password string (optional)       The password for your BugSplat account. If provided --user must also be       
                                         provided. This value can also be provided via the SYMBOL_UPLOAD_PASSWORD      
                                         environment variable.                                                         
  -i, --clientId string (optional)       An OAuth2 Client Credentials Client ID for the specified database. If         
                                         provided --clientSecret must also be provided. This value can also be         
                                         provided via the SYMBOL_UPLOAD_CLIENT_ID environment variable.                
  -s, --clientSecret string (optional)   An OAuth2 Client Credentials Client Secret for the specified database. If     
                                         provided --clientId must also be provided. This value can also be provided    
                                         via the SYMBOL_UPLOAD_CLIENT_SECRET environment variable.                     
  -r, --remove                           Removes symbols for a specified database, application, and version. If this   
                                         option is provided no other actions are taken.                                
  -f, --files string (optional)          Glob pattern that specifies a set of files to upload. For example,            
                                         **/*.{pdb,exe,dll} will recursively search for .pdb, .exe, and .dll files.    
                                         Defaults to "*.js.map"                                                        
  -d, --directory string (optional)      Path of the base directory used to search for symbol files. This value will   
                                         be combined with the --files glob. Defaults to '.'                            
  -m, --dumpSyms boolean (optional)      Use dump_syms to generate and upload sym files for specified binaries.        
  -l, --localPath string (optional)      Path to a directory to copy symbols to. If provided, the files will be copied   
                                         to the provided path instead of being uploaded to BugSplat. Useful for        
                                         creating a self-hosted symbol server.                                         

  The -u and -p arguments are not required if you set the environment variables 
  SYMBOL_UPLOAD_USER and SYMBOL_UPLOAD_PASSWORD, or provide a clientId and      
  clientSecret.                                                                 
                                                                                
  The -i and -s arguments are not required if you set the environment variables 
  SYMBOL_UPLOAD_CLIENT_ID and SYMBOL_UPLOAD_CLIENT_SECRET, or provide a user    
  and password.                                                                 

Example

  symbol-upload -b your-bugsplat-database -a your-application-name -v your-     
  version [ -f "*.js.map" -d "/path/to/containing/dir" [ -u your-bugsplat-email 
  -p your-bugsplat-password ] OR [ -i your-client-id -s your-client-secret] ]   

Links

  🐛 https://bugsplat.com                          
                                                   
  💻 https://github.com/BugSplat-Git/symbol-upload 
                                                   
  💌 [email protected] 

Example

The following is an example of how to invoke symbol-upload and search a directory recursively for .dll, .pdb, and .exe files. Replace the values of your-bugsplat-database, your-email, and your-password with your BugSplat database, email, and password. You can specify a glob for the -f argument to match for files based on a pattern.

symbol-upload -b your-bugsplat-database -a my-awesome-app -v 1.0 -u your-email -p your-password -d "/path/to/build -f "**/*.+(exe|dll|pdb)"

You can use the -r flag to remove a symbol store instead of uploading. This is helpful when you create a new build but don't want to increment the build number.

Authentication

Credentials can be provided to symbol-upload via the -u and -p command-line arguments. OAuth2 Client ID and Client Secret credentials can also be provided for authentication via the -i and -s arguments and are created on the OAuth Integrations page.

Apple

MacOS and iOS builds typically generate .app or .xcarchive files. To upload bundled .dSYM files, point symbol-upload at the .app or .xcarchive file, and use a glob that instructs symbol-upload to search for .dSYM files recursively.

symbol-upload ... -d "/path/to/build.xcarchive -f "**/*.dSYM"

Dump Syms

BugSplat can generate Crashpad symbol files as part of the upload process. The Crashpad symbol files have a .sym format and are useful for cross-platform applications. BugSplat has integrated Mozilla's dump-syms into symbol-upload, which allows developers to skip building Breakpad. To generate a .sym file at upload time, specify the -m flag when invoking symbol-upload.

Self-Hosted Symbol Servers

The symbol-upload tool can be used to create a SymSrv directory structure for Windows symbols that is compatible with both BugSplat and Microsoft Visual Studio. Additionally, symbol-upload can also create a SymSrv directory structure for macOS and Crashpad symbols that is compatible with BugSplat.

To upload symbols to a local directory, provide the -l flag and a path where the symbols will be copied.

symbol-upload -f "**/*.{pdb,exe,dll}" -l "C:\path\to\output"

Next, use a sync tool to upload the directory to a cloud services provider. The following is an example that uses s3 sync via the AWS CLI.

aws s3 sync . s3://your-bucket-name-here

To connect BugSplat to your self-hosted symbol server, please refer to our Symbol Server documentation.

GitHub Actions

The symbol-upload repo also includes a GitHub Action that's compatible with the default Windows, macOS, and Linux images. Here's a snippet you can add to your workflow:

- name: Symbols 📦
      uses: BugSplat-Git/symbol-upload@main
      with:
        clientId: "${{ secrets.SYMBOL_UPLOAD_CLIENT_ID }}"
        clientSecret: "${{ secrets.SYMBOL_UPLOAD_CLIENT_SECRET }}"
        database: "${{ secrets.BUGSPLAT_DATABASE }}"
        application: "MyConsoleCrasher"
        version: "1.0.0"
        files: "*.{pdb,exe,dll}"
        directory: "BugSplat\\Win32\\release"

We have also created an example repo demonstrating how to use the @bugsplat/symbol-upload action to upload symbols to BugSplat.

Improving Upload Speeds

Customers located far away from our US-East hosting location, especially those with high-latency and high-bandwidth connections, sometimes report slow upload speeds. We have several reports of significantly faster uploads after following the advice in the Microsoft technical note: https://docs.microsoft.com/en-us/troubleshoot/windows-server/networking/tcpip-performance-known-issues