qcodes.logger

The qcodes.logger module provides functionality to enable logging of errors and debug information from QCoDeS using the default python logging module. It also logs command history logging when using IPython/Jupyter.

The module also provides functionality to filter log messages by instrument and functions to extract log messages to pandas.DataFrame s

Classes:

LogCapture(logger, level)

Context manager to grab all log messages, optionally from a specific logger.

Functions:

`capture_dataframe`([level, logger])	Context manager to capture the logs in a `pd.DataFrame`
`console_level`(level)	Context manager to temporarily change the level of the qcodes console handler.
`filter_instrument`(instrument[, handler, level])	Context manager that adds a filter that only enables the log messages of the supplied instruments to pass.
`flush_telemetry_traces`()	Flush the traces of the telemetry logger.
`get_console_handler`()	Get handle that prints messages from the root logger to the console.
`get_file_handler`()	Get a handle that streams messages from the root logger to the qcodes log file.
`get_instrument_logger`(instrument_instance[, ...])	Returns an `InstrumentLoggerAdapter` that can be used to log messages including `instrument_instance` as an additional context.
`get_level_code`(level)	Get a logging level code from either a logging level string or a logging level code.
`get_level_name`(level)	Get a logging level name from either a logging level code or logging level name.
`get_log_file_name`()	Get the full path to the log file currently used.
`handler_level`(level, handler)	Context manager to temporarily change the level of handlers.
`log_to_dataframe`(log[, columns, separator])	Return the provided or default log string as a `pd.DataFrame`.
`logfile_to_dataframe`([logfile, columns, ...])	Return the provided or default logfile as a `pd.DataFrame`.
`start_all_logging`()	Starts python log module logging and ipython command history logging.
`start_command_history_logger`([log_dir])	Start logging of the history of the interactive command shell.
`start_logger`()	Start logging of messages passed through the python logging module.
`time_difference`(firsttimes, secondtimes[, ...])	Calculate the time differences between two series containing time stamp strings as their values.

class qcodes.logger.LogCapture(logger: ~logging.Logger = <RootLogger root (WARNING)>, level: int | str | None = None)[source]

Bases: object

Context manager to grab all log messages, optionally from a specific logger.

Example

>>> with LogCapture() as logs:
>>>     code_that_makes_logs(...)
>>> log_str = logs.value

qcodes.logger.capture_dataframe(level: LevelType = 10, logger: logging.Logger | None = None) → Iterator[tuple[logging.StreamHandler, Callable[[], pd.DataFrame]]][source]

Context manager to capture the logs in a pd.DataFrame

Example

>>> with logger.capture_dataframe() as (handler, cb):
>>>     qdac.ch01(1)  # some commands
>>>     data_frame = cb()

Parameters:

level – Level at which to capture.
logger – Logger used to capture the data. Will default to root logger if None is supplied.

Returns:

Tuple of handler that is used to capture the log messages and callback that returns the cumulative pd.DataFrame at any given point (within the context)

qcodes.logger.console_level(level: int | str) → Iterator[None][source]

Context manager to temporarily change the level of the qcodes console handler.

Example

>>> with logger.console_level(level=logging.DEBUG):
>>>     root_logger.debug('this is now visible')

Parameters:: level – Level to set the console handler to.

qcodes.logger.filter_instrument(instrument: InstrumentBase | Sequence[InstrumentBase], handler: logging.Handler | Sequence[logging.Handler] | None = None, level: LevelType | None = None) → Iterator[None][source]

Context manager that adds a filter that only enables the log messages of the supplied instruments to pass.

Example

>>> h1, h2 = logger.get_console_handler(), logger.get_file_handler()
>>> with logger.filter_instruments((qdac, dmm2), handler=[h1, h2]):
>>>     qdac.ch01(1)  # logged
>>>     v1 = dmm2.v() # logged
>>>     v2 = keithley.v()  # not logged

Parameters:

instrument – The instrument or sequence of instruments to enable messages from.
level – Level to set the handlers to.
handler – Single or sequence of handlers to change.

qcodes.logger.flush_telemetry_traces() → None[source]: Flush the traces of the telemetry logger. If telemetry is not enabled, this function does nothing.

qcodes.logger.get_console_handler() → Handler | None[source]: Get handle that prints messages from the root logger to the console. Returns None if start_logger() has not been called.

qcodes.logger.get_file_handler() → Handler | None[source]: Get a handle that streams messages from the root logger to the qcodes log file. To setup call start_logger(). Returns None if start_logger() has not been called.

qcodes.logger.get_instrument_logger(instrument_instance: InstrumentBase, logger_name: str | None = None) → InstrumentLoggerAdapter[source]

Returns an InstrumentLoggerAdapter that can be used to log messages including instrument_instance as an additional context.

The logging.LoggerAdapter object can be used as any logger.

Parameters:

instrument_instance – The instrument instance to be added to the context of the log record.
logger_name – Name of the logger to which the records will be passed. If None, defaults to the root logger.

Returns:

logging.LoggerAdapter instance, that can be used for instrument specific logging.

qcodes.logger.get_level_code(level: str | int) → int[source]: Get a logging level code from either a logging level string or a logging level code. Will return the output of logging.getLevelName() if called with a str. If called with an int it will return the int supplied.

qcodes.logger.get_level_name(level: str | int) → str[source]: Get a logging level name from either a logging level code or logging level name. Will return the output of logging.getLevelName() if called with an int. If called with a str it will return the str supplied.

qcodes.logger.get_log_file_name() → str[source]: Get the full path to the log file currently used.

qcodes.logger.handler_level(level: int | str, handler: Handler | Sequence[logging.Handler]) → Iterator[None][source]

Context manager to temporarily change the level of handlers.

Example

>>> with logger.handler_level(level=logging.DEBUG, handler=[h1, h1]):
>>>     root_logger.debug('this is now visible')

Parameters:

level – Level to set the handlers to.
handler – Handle or sequence of handlers which to change.

qcodes.logger.log_to_dataframe(log: Sequence[str], columns: Sequence[str] | None = None, separator: str | None = None) → pd.DataFrame[source]

Return the provided or default log string as a pd.DataFrame.

Unless qcodes.logger.logger.LOGGING_SEPARATOR or qcodes.logger.logger.FORMAT_STRING_DICT have been changed using the default for the columns and separator arguments is encouraged.

Lines starting with a digit are ignored. In the log setup of qcodes.logger.logger.start_logger() Traceback messages are also logged. These start with a digit.

Parameters:

log – Log content.
columns – Column headers for the returned dataframe, defaults to columns used by handlers set up by qcodes.logger.logger.start_logger().
separator – Separator of the log file to separate the columns, defaults to separator used by handlers set up by qcodes.logger.logger.start_logger().

Returns:

A pd.DataFrame containing the log content.

qcodes.logger.logfile_to_dataframe(logfile: str | None = None, columns: Sequence[str] | None = None, separator: str | None = None) → pd.DataFrame[source]

Return the provided or default logfile as a pd.DataFrame.

Unless qcodes.logger.logger.LOGGING_SEPARATOR or qcodes.logger.logger.FORMAT_STRING_DICT have been changed using the default for the columns and separator arguments is encouraged.

Lines starting with a digit are ignored. In the log setup of qcodes.logger.logger.start_logger() Traceback messages are also logged. These start with a digit.

Parameters:

logfile – Name of the logfile, defaults to current default log file.
columns – Column headers for the returned dataframe, defaults to columns used by handlers set up by qcodes.logger.logger.start_logger().
separator – Separator of the logfile to separate the columns, defaults to separator used by handlers set up by qcodes.logger.logger.start_logger().

Returns:

A pd.DataFrame containing the logfile content.

qcodes.logger.start_all_logging() → None[source]: Starts python log module logging and ipython command history logging.

qcodes.logger.start_command_history_logger(log_dir: str | None = None) → None[source]

Start logging of the history of the interactive command shell. Works only with IPython and Jupyter. Call function again to set new path to log file.

Parameters:: log_dir – directory where log shall be stored to. If left out, defaults to ~/.qcodes/logs/command_history.log

qcodes.logger.start_logger() → None[source]: Start logging of messages passed through the python logging module. This sets up logging to a time based logging. This means that all logging messages on or above filelogginglevel will be written to pythonlog.log All logging messages on or above consolelogginglevel will be written to stderr. filelogginglevel and consolelogginglevel are defined in the qcodesrc.json file.

qcodes.logger.time_difference(firsttimes: pd.Series, secondtimes: pd.Series, use_first_series_labels: bool = True) → pd.Series[source]

Calculate the time differences between two series containing time stamp strings as their values.

Parameters:

firsttimes – The oldest times
secondtimes – The youngest times
use_first_series_labels – If true, the returned Series has the same labels as firsttimes. Else it has the labels of secondtimes

Returns:

A pd.Series with float values of the time difference (s)