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-uploadAlternatively, 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-macosWindows
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-macosLinux
curl -sL -O "https://app.bugsplat.com/download/symbol-upload-linux" && chmod +x symbol-upload-linuxA 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-hereTo 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
Last updated
Was this helpful?