Wait, what's a symbol server?
"Symbol files" (aka PDB files) contain information about your software that a debugger can use to show you backtraces, local variables, etc. They are generated by the compiler when you build your software. Debugging is a nightmare without symbols. Really.
A "symbol server" hosts symbol files for Windows-based software. Debuggers use symbol servers to obtain symbol files for the software you're debugging automatically. John Robbins has written a great article explaining all of this and more on his blog. Symbol servers can serve symbol files over HTTP or a Windows file share.
That doesn't sound so hard. Why do I need this?
symstore.exe, which creates the directory structure that the symbol server serves, and
symsrv.dll, which implements the logic for retrieving symbols from a symbol server, operate case-insensitively (like much Windows software). This means that
symsrv.dll might ask for symbols using a URL that uses uppercase where
symstore.exe used lowercase, or vice versa.
Many web servers treat URLs case-insensitively. S3 does not. So one job of Pepto Symbol is to provide case-insensitive access to symbol files stored on S3.
In addition, if you try to access a file that doesn't exist on S3, you will get a 403 Forbidden error, rather than 404 Not Found. When
symsrv.dll gets a 403 error from a symbol server, it blacklists that server for the rest of the debugging session. So Pepto Symbol also converts 403 errors to 404 errors.
- You must use all-lowercase keys when uploading your symbols to S3.
- You need a server on which Pepto Symbol can run as an HTTP proxy.
Let's say you've uploaded your symbols (using lowercased keys, remember!) to
http://my-bucket.s3.amazonaws.com/awesome/symbols, and that you're going to deploy Pepto Symbol to
First, deploy Pepto Symbol to a server. Pepto Symbol comes preconfigured for deployment on Heroku:
heroku create --stack cedar heroku config:add S3_BUCKET=my-bucket git push heroku master
(It should be fairly simple to deploy it elsewhere if needed.)
Next, add the following URL to your symbol path:
You can add an optional
PATH_PREFIX environment variables for shorter URLs.
This prefix will be prepended to all requests paths to the S3 bucket.
heroku config:add PATH_PREFIX=/awesome/symbols
Now the symbol server URL can be
To run Pepto Symbol locally on port 5000:
echo S3_BUCKET=my-bucket > .env foreman start
Pepto Symbol's Git repository is available on GitHub, and can be browsed at https://github.com/aroben/pepto-symbol. You can clone the repository with this command:
git clone https://github.com/aroben/pepto-symbol
If you'd like to hack on Pepto Symbol, follow these instructions:
- Fork the project to your own account
- Clone down your fork
- Create a thoughtfully named topic branch to contain your change
- Hack away
- If you are adding new functionality, document it in README.md
- Do not change the version number, I will do that on my end
- If necessary, rebase your commits into logical chunks, without errors
- Push the branch up to GitHub
- Send a pull request for your branch
Copyright (c) 2012 Adam Roben. See the LICENSE file for details.