# Diagnostics: `coverage debug`

The debug command shows internal information to help diagnose problems. If you are reporting a bug about coverage.py, including the output of this command can often help:

    $ coverage debug sys > please_attach_to_bug_report.txt

A few types of information are available:

- `config`: show coverage’s configuration

- `sys`: show system configuration

- `data`: show a summary of the collected coverage data

- `premain`: show the call stack invoking coverage

- `pybehave`: show internal flags describing Python behavior

- `sqlite`: show internal compilation options for SQLite

    $ coverage debug --help
    Usage: coverage debug <topic>

    Display information about the internals of coverage.py, for diagnosing
    problems. Topics are:

    'config' to show configuration settings.

    'data [filenames]' to summarize data files.

    'premain' to show what is calling coverage.

    'pybehave' to show internal flags describing Python behavior.

    'sqlite' to show SQLite compilation options.

    'sys' to show installation information.

    Options:
      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
      -h, --help       Get help on this command.
      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
                       [env: COVERAGE_RCFILE]

## `--debug` option

The `--debug` option is available on all commands. It instructs coverage.py to log internal details of its operation to help with diagnosing problems. It takes a comma-separated list of options, each indicating a facet of activity to log:

- `callers`: annotate each debug message with a stack trace of the callers to that point.

- `config`: before starting, dump all the configuration values.

- `core`: log decision about choosing the measurement core to use.

- `dataio`: log when reading or writing any data file.

- `dataop`: log a summary of data being added to CoverageData objects.

- `dataop2`: when used with `debug=dataop`, log the actual data being added to CoverageData objects.

- `lock`: log operations acquiring locks in the data layer.

- `multiproc`: log the start and stop of multiprocessing processes.

- `patch`: log when patches are applied and when they are executed. See [run] patch.

- `pathmap`: log the remapping of paths that happens during `coverage combine`. See [paths].

- `pid`: annotate all warnings and debug output with the process and thread ids.

- `plugin`: print information about plugin operations.

- `process`: show process creation information, and changes in the current directory. This also writes a time stamp and command arguments into the data file.

- `pybehave`: show the values of internal flags describing the behavior of the current version of Python.

- `pytest`: indicate the name of the current pytest test when it changes.

- `self`: annotate each debug message with the object printing the message.

- `sql`: log the SQL statements used for recording data.

- `sqldata`: when used with `debug=sql`, also log the full data being used in SQL statements.

- `sys`: before starting, dump all the system and environment information, as with coverage debug sys.

- `trace`: print every decision about whether to trace a file or not. For files not being traced, the reason is also given.

Debug options can also be set with the `COVERAGE_DEBUG` environment variable, a comma-separated list of these options, or in the [run] debug section of the .coveragerc file.

The debug output goes to stderr, unless the [run] debug_file setting or the `COVERAGE_DEBUG_FILE` environment variable names a different file, which will be appended to. This can be useful because many test runners capture output, which could hide important details. `COVERAGE_DEBUG_FILE` accepts the special names `stdout` and `stderr` to write to those destinations.