Stuck on a bug your tests don’t catch? To debug rails with byebug, rule out cheaper clues first, then work through the guide’s byebug chapters in order. This page maps that route.
This page is one part of the wider topic of ruby on rails debugging, so start there if you want the full map.
| Item | Value |
|---|---|
| View helpers for inspecting variables | Three (debug, to_yaml, inspect) |
| Output of the debug helper | A pre tag rendering the object as YAML |
| Default Rails log level | debug, in all environments |
| Log level numbers | 0 up to 5 (:debug through :unknown) |
| Default log file location | Rails.root/log/ |
The figures come from the Rails Guides debugging page for Rails 5.2. They can change between Rails versions, so check the guide for your version before you rely on them.
What the Rails Guides cover for byebug
The Rails Guides debugging page says it teaches you how to track down problems and issues in your application that your tests aren’t identifying. That is the situation where a debugger earns its place, because a failing test has already told you what it can.
Under the heading “Debugging with the byebug gem”, the guide lists these chapters:
- Setup
- The Shell
- The Context
- Threads
- Inspecting Variables
- Step by Step
- Breakpoints
- Catching Exceptions
- Resuming Execution
- Editing
- Quitting
- Settings
Read them in that order: setup first, then the shell and context, then inspecting, stepping and breakpoints. This page does not reproduce byebug’s commands or those of the debug gem, so open the byebug chapter of the guide for your Rails version to get them.
Start with the view helpers
Before you open a debugger, ask whether you only need to see a value. The guide says Rails gives you three ways to inspect a variable in a view: debug, to_yaml and inspect.
The debug helper returns a pre tag that renders the object in YAML, which gives you human-readable data from any object. Calling to_yaml yourself and passing the result to simple_format produces similar output, and the guide notes that this is how debug does its magic.
For arrays and hashes, inspect is the useful one, because it prints the object’s value as a string. An array of the numbers one to five renders as a plain bracketed list.
Leave a trail with the logger
Rails writes log information with the ActiveSupport::Logger class, and the guide says other loggers, such as Log4r, may be substituted. It also says Rails keeps a separate log file for each runtime environment, created under Rails.root/log/ and named after the environment.
You write to the log with logger.debug, logger.info, logger.warn, logger.error or logger.fatal from a controller, model or mailer. The guide’s example controller logs the new article’s attributes and whether it is valid before it saves, which lets you read the state of a request after the fact.
A message is printed only if its level is equal to or higher than the configured level. The six levels, in order, are:
- :debug
- :info
- :warn
- :error
- :fatal
- :unknown
They correspond to the numbers 0 up to 5, and the default is debug in all environments. For a closer look at picking between them, read about rails logger levels.
Checking the setting and changing it are separate steps. Calling Rails.logger.level tells you where you stand. To move it, the guide gives you two routes: a config.log_level line placed in an environment initializer, or a direct assignment to Rails.logger.level that works at any time, with :warn and 0 as its examples.
The guide’s reason for changing the level is practical. You can log more under development or staging without flooding your production log with unnecessary information. Because the default is debug in every environment, production starts out as chatty as development until you raise the level.
The guide’s example controller shows a habit worth copying. Inside the create action it logs the new article’s attributes, then whether the article is valid, and then a further message once the article was saved and the user is about to be redirected. Those messages surround the save call, so the log shows which step a request reached before something went wrong.
The guide’s own examples suggest a few habits for writing useful log lines:
- Log an object with inspect, as the example does with the article’s attributes, so you read real values instead of a bare object reference.
- Log the result of valid? before the save, so a failed save can be explained from the log alone.
- Match the level to the message: the guide uses logger.debug for state dumps, logger.info for “Processing the request…” and logger.fatal for an unrecoverable error.
- Rely on the configured level to keep chatty debug lines out of production, rather than deleting them each time.
You are not tied to the default writer either. The guide shows config.logger set to Logger.new(STDOUT) in config/application.rb or any other environment file, and it says a Log4r logger may be substituted. Whichever logger you pick, the same level rules decide which messages get written.
When does a debugger beat a log line?
A log line is a note you wrote in advance, so it only answers the question you thought to ask. A debugger session is the better fit when you don’t yet know which value matters. The guide’s byebug chapters on inspecting variables, stepping and breakpoints exist for that case.
A sensible order of attack looks like this:
- Reproduce the problem and note exactly what you expected.
- Print the suspect value in the view with debug or inspect.
- Add logger.debug lines in the controller or model, and confirm the log level lets them through.
- Move to byebug when you need to inspect several values or follow the code step by step.
- Remove the temporary logging and debugger calls once the cause is fixed.
The byebug list also includes a chapter called Catching Exceptions. If you want your app to respond to errors instead of just inspecting them, see rails exception handling.
Where web-console fits
The Rails 5.2 guide has a second debugging section titled “Debugging with the web-console gem”. Its chapters are Console, Inspecting Variables and Settings.
Treat web-console as a companion rather than a replacement. Check the guide for your Rails version to see whether it is covered there.
Frequently asked questions
Does byebug replace the logger?
Show answer
No. The guide documents both on the same page, and they do different jobs: the logger leaves a record you read later, while the byebug chapters cover inspecting and stepping through code.
What is the default Rails log level?
Show answer
The guide says the default Rails log level is debug in all environments, as of the Rails 5.2 version of the guide.
How do I change the log level?
Show answer
Use config.log_level = :warn in any environment initializer, or set Rails.logger.level = 0 at any time. The levels run from 0 up to 5.
Does this page cover the debug gem?
Show answer
No. The guide pages behind this article describe byebug, so the debug gem’s commands are left out. Check the guide for your Rails version for those.
