Debugging and Logging

Bluesky uses Python logging framework. See below for a list of the names of the loggers it publishes to.

Useful Snippets

If the RunEngine is “hanging,” running slowly, or repeatedly encountering an error, it is useful to know exactly where in the plan the problem is occurring. To follow the RunEngine’s progress through the plan, crank up the verbosity of the logging.


To direct the output to a file instead of to the screen:

from bluesky import set_handler

Logger Names

Here is the complete list of loggers used by bluesky.

  • 'bluesky' — the logger to which all bluesky log messages propagate
  • 'bluesky.RE' — Messages from a RunEngine. INFO-level notes state changes. DEBUG-level notes when each message from a plan is about to be processed, when a document has been emitted to subscribed callbacks, and when a status object has completed.
  • 'bluesky.RE.<id>' — Messages from a specific RunEngine instance, disambiguating the (rare) case where there are multiple RunEngine instances in the same process. This is the logger that the accessor RE.log refers to.
  • 'bluesky.RE.<id>.msg' — DEBUG-level notes when each message from a plan is about to be processed.

Logging Handlers

By default, bluesky prints log messages to the standard out by adding a logging.StreamHandler to the 'bluesky' logger at import time. You can, of course, configure the handlers manually in the standard fashion supported by Python. But a convenience function bluesky.set_handler(), makes it easy to address common cases.

See the Examples section below.

bluesky.set_handler(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, datefmt='%H:%M:%S', color=True)[source]

Set a new handler on the logging.getLogger('bluesky') logger.

This function is run at import time with default paramters. If it is run again by the user, the handler from the previous invocation is removed (if still present) and replaced.

file : object with write method or filename string

Default is sys.stdout.

datefmt : string

Date format. Default is '%H:%M:%S'.

color : boolean

Use ANSI color codes. True by default.

handler : logging.Handler

The handler, which has already been added to the ‘bluesky’ logger.


Log to a file.

>>> set_handler(file='/tmp/what_is_happening.txt')

Include the date along with the time. (The log messages will always include microseconds, which are configured separately, not as part of ‘datefmt’.)

>>> set_handler(datefmt="%Y-%m-%d %H:%M:%S")

Turn off ANSI color codes.

>>> set_handler(color=False)