-
Notifications
You must be signed in to change notification settings - Fork 0
(Deprecated: Breakpad Module only) Getting started and setup
This page will go through all the steps to get started and set up using the Godot Backtrace module. The Breakpad module supports only the Linux platform, so this page is written assuming you are on Linux. As new platforms are added, this page will change accordingly.
NOTE: The Breakpad module is no longer supported! It is still provided on the Breakpad_Module_Backup branch in case anyone needs it. If possible, please use the Crashpad module in the main branch, as it supports all major desktop operating systems and is actively maintained. The instructions on this page only apply to the Breakpad module.
The module has a few dependencies that need to be set up before it can be used. First, you will need to download and compile the 3.x branch of the Godot Github repository. The Godot documentation has a guide for compiling for Linux on its documentation that covers all the steps needed. You will need to install all of the dependencies and libraries needed to compile Godot, including scons.
If you wish to make modifications to the module, you may also want to look at the engine development page on the documentation.
Next, you will need to download and compile Google Breakpad. This module currently uses Google Breakpad for generating crash reports that can be parsed by services like Backtrace. The getting started page on the Google Breakpad page covers how to download, compile, and install Breakpad on your machine. Note that to compile Breakpad, you will need to download Google's depot_tools, in addition to Breakpad itself.
Note: Currently the module assumes you have Google Breakpad compiled and installed on your machine using make install to make linking easier. If you do not wish to install Breakpad but still use the module, you will need to modify the SCsub file at modules/breakpad accordingly so it points to the generated libbreakpad_client.a file that is generated after compiling Breakpad.
After you have Breakpad compiled and installed, you will also need to make a copy of its source code to the thirdparty folder. Copy the breakpad/src/src folder and paste it into the thirdparty/breakpad folder in this module. This is required for Godot to compile the headers correctly.
Finally, the last dependency is to make sure you have curl installed on your system. To know whether you have curl installed, open a terminal and type curl and then press enter. If you get output like curl: try 'curl --help' or 'curl --manual' for more information then curl is successfully installed and usable. If curl is not installed, you will need to install it so crash reports can be sent to the online server. To install curl, search "OS-HERE install curl", where "OS-HERE" is the name of the Linux OS you are using. For most Linux operating systems, curl is installed automatically.
Once you have all those steps finished, you are ready to start using the module! The last steps are to copy the modules and thirdparty folders from the Godot Backtrace Module and paste them into the folder where you downloaded the Godot source code. This should add a breakpad folder to the modules folder, as well as adding a breakpad folder to the thirdparty folder in the Godot source code.
Now you can compile Godot normally using scons. The code should build like normal and you will receive an executable you can run.
Note: If you have not installed Breakpad using make install, you may get an error about missing types and functions! Please make sure to either install Breakpad or change the SCsub file to point to the libbreakpad_client.a file that is generated after compiling Breakpad.
Once you have successfully compiled the module, there are just a few more steps you need to complete. First, open the Godot project that you want to add automatic error generation to with the newly compiled Godot executable. Next, create a new node and make sure Breakpad is an option from the drop down list. If it is there, then that means the module has successfully compiled and is ready to be used. If it is not present, please check the "Getting Started" section to see if you missed any steps.
While you can add a Breakpad node directly to a scene and get error reporting that way, the best way to set up automatic error reporting is through the use of an autoload singleton. This way, there is just a single instance of the node and it is accessible in all scenes. First, make a new script by going to the script tab on the top of the screen and pressing "new" from the file drop down. Name the file something like automatic_crash_report.gd and then save it. Then change the code to the following:
extends Breakpad
func _ready():
# Setup the URL and the Token:
# (We'll show how to get these values in a moment!)
api_URL = "yoursubdomainhere.sp.backtrace.io"
api_token = "YourTokenHere"
# Set the attributes you want your crash report to have:
# For example, we'll add a version of 0.0.1
crash_attributes["version"] = "0.0.1"
# Finally, start tracking errors using Breakpad
start_breakpad()
As you can see, it is really easy and fast to get automatic crash reporting ready and set up for your Godot project.
We need to make the script run as an autoload singleton in Godot. First, open the project settings by clicking project in the top right corner of the Godot editor and then select project settings. From the window that pops up, select the AutoLoad tab and then in the Path: field, set the path to the automatic_crash_report.gd file, optionally change the node name, and then select Add. This will make the script run as an autoload singleton.
If you want to learn more about autoload singletons in Godot, refer to the Godot documentation on autoload singleton.
Before we can run this code, we need to figure out what values we'll need for api_URL and api_token, so the system knows where to send the crash report once it occurs.
Because this module is designed to work with Backtrace, we will be following the steps to set up the module so Breakpad sends it's data to a Backtrace instance.
First, go to the Backtrace website at https://backtrace.io/ and make a free account by pressing "GET STARTED" if you do not already have an account. Backtrace is free for single developers with a limit of 25K monthly errors, which is more than enough for small projects.
If you are making a new account, be sure to remember to note what you put in as your subdomain, as this will be important! If you already have an account, you will need to get your subdomain so you can correctly point the module to the right place.
Once you have made your account, go to your subdomain, which should be something like https://SUBDOMAIN_HERE.sp.backtrace.io/, where SUBDOMAIN_HERE is, instead, the subdomain you have chosen for your account. Once logged in, make a new project and name it the same as your Godot project. Then go to the project settings, which you can access by clicking your profile on the top right corner, and select "project settings" from the drop down. On the left side, go to "Integration guides" and select "Minidump".
This will bring you to the Minidump integration guide. What we are looking for is the automatically formatted URL for CURL, which should be right below the text "If you are using curl, the following command submits a file.dmp into your Backtrace instance". It should look something like the following:
curl -v --data-binary @file.dmp 'https://submit.backtrace.io/SUBDOMAIN_HERE/1234567890123456789012345678901234567890123456789012345678901234/minidump'
On your page, instead of SUBDOMAIN_HERE it will, instead, have the name of your subdomain in all lowercase, and instead of a long string of 1234567890, there will be a token that is unique to your project. This is the data we need to set in the autoload singleton we made in Godot.
First, copy https://submit.backtrace.io/SUBDOMAIN_HERE/ (where SUBDOMAIN_HERE is your subdomain) and paste it as the value of api_URL in the autoload singleton script file we made in Godot earlier. It's important that there be a / at the end of the URL, as otherwise it will not work correctly, so make sure to include it at the end.
Next, copy the long string after the URL that should look something like 1234567890123456789012345678901234567890123456789012345678901234 and paste that as the api_token in the autoload singleton script file we made in Godot earlier. Make sure to use the full token from the Minidump integration guide without any / characters.
Once done, your Godot autoload singleton file should look something like this:
extends Breakpad
func _ready():
# Setup the URL and the Token:
# (these values should reflect the values on the Minidump integration guide)
api_URL = "https://submit.backtrace.io/SUBDOMAIN_HERE/"
api_token = "1234567890123456789012345678901234567890123456789012345678901234"
crash_attributes["version"] = "0.0.1"
start_breakpad()
If it does, then we're almost ready to send our first test crash report to make sure everything is working! The last step we need to do is generate and submit the symbol files, so when a crash occurs Backtrace knows how to link the stacktrace to code in Godot.
To do this, we first need to generate a .sym file that we can upload to Backtrace. Go to where you compiled Godot and open the folder with the executable you compiled. Then open a terminal at that location and type the following command:
dump_syms godot.x11.tools.64 > godot.x11.tools.64.sym
What this will do is call the dump_syms command from Google Breakpad and will generate a symbols file that we can then use to map stacktrace data from Breakpad to lines of code.
Note: You may need to change godot.x11.tools.64 in the command based on how you compiled Godot. For example, if you compiled Godot with 32 bits instead of 64, then you will need to change it to godot.x11.tools.32 instead.
Once finished, go back to the Backtrace website and on the right side, select "Symbols", and from the drop down, select "Upload an archive". Then drag and drop the .sym file you just generated with dump_syms and hit "next". You can optionally add a tag (I suggest 0.0.1) and then hit next. Backtrace will then upload it to their servers and you are ready to go!
Please note that you will need to repeat this process of generating the .sym files and uploading it to Backtrace each time you compile Godot from source with the Breakpad module. This is required because anytime the Godot source code changes the stacktrace data changes as well.
To test to see if the automatic error reporting code works correctly, add the following code to your Godot autoload singleton:
extends Breakpad
func _ready():
api_URL = "https://submit.backtrace.io/SUBDOMAIN_HERE/"
api_token = "1234567890123456789012345678901234567890123456789012345678901234"
crash_attributes["version"] = "0.0.1"
start_breakpad()
# wait a few frames
yield(get_tree(), "idle_frame")
yield(get_tree(), "idle_frame")
yield(get_tree(), "idle_frame")
# manually cause a crash
force_crash()
What this code does is wait a few frames, just to make sure everything is fully initialized, and then forces a crash using the force_crash function, which is designed specifically to cause a simple crash by trying to divide an integer by zero. Run this code and you should find that Godot will launch, stay for a few moments, and then automatically close. If so, then that means everything worked correctly!
Go ahead and check your project on Backtrace. From the project settings, click the "Back" button with an arrow on the top left of the screen. This will bring you to the triage screen and you should see a single open error with a description of "Breakpad::crash". You can click the fingerprint on this error to see more details. If you look at the call stack, it will show the C++ code that was executed leading up to the crash. This means the module is working and set up successfully!
Now enjoy the benefits of having automatic crash detection in your Godot games! Remember to remove force_crash() in your singleton, so your project only will upload a crash when Godot actually crashes.