Overview
MFT repository (flint, mlxconfig, mlxlink, mtcr, mlxreg, …) contains a shared logging infrastructure called NVIDIA Tools Logger. It is disabled by default and produces no output until it is explicitly turned on.
nvtoolslogger is the command-line tool used to control it. With this tool, you can:
-
Set how verbose the logging is (globally, or per MFT module)
-
Choose where the log goes (screen, file, syslog)
-
Limit how many log files accumulate on disk
-
Inspect the currently active configuration
The tool does not log anything itself — it writes a small JSON configuration file that every MFT tool reads at start-up. Changes take effect on the next run of an MFT tool. Already
running processes are not affected.
File and Directory Locations
|
|
Linux / FreeBSD / ESXi |
Windows |
|---|---|---|
|
Configuration file |
|
|
|
Log directory |
|
|
|
Tool |
|
|
Permissions: The configuration file are found in a system directory, sonvtoolslogger must be run as root (Linux) or from an elevated / Administrator shell (Windows) when writing the default path. Read-only operations such as --show, do not require elevation.
Get Started
Turn logging on, send it to a file, and check the result:
# 1. Enable everything at INFO level
nvtoolslogger -l info
nvtoolslogger --set-level info
# 2. Send the output to /var/log/mft/
nvtoolslogger -o file
nvtoolslogger --enable-output file
# 3. Verify what is active
nvtoolslogger -s
nvtoolslogger --show
# 4. Run any MFT tool - it now logs
flint -d /dev/mst/mt4123_pciconf0 q
# 5. Look at the log
ls -ltr /var/log/mft/
To turn logging back off completely:
nvtoolslogger --reset
Concepts
Severity Levels
Logging is threshold-based: a level lets through that level and everything more severe.
|
Level |
Meaning |
|---|---|
|
|
Everything, including internal flow / register access detail. Most verbose. |
|
|
High-level progress messages. |
|
|
Recoverable problems. |
|
|
Operation failures. |
|
|
Unrecoverable failures only. |
|
|
No logging at all (this is the default). |
Example: --set-level warning emits warning, error and fatal, but not info or debug.
Layers (Modules)
Log messages are tagged with the MFT component "layer" that produced them. Each layer can carry its own severity threshold, which is useful when you need deep detail from one component without drowning in output from the rest.
Available layers:
mtcr, mlxreg, mft_core, mlxfwops, npgs, mst_tool, efuse, common, hca_caps , nvfwinject, mlxdpa, mlxtokengenerator, imgen, mlxfwmanager, mlxi2c, mflash, mflash_access , mflash_spi, imgen_mic, cable_access, cable_cdb
The keyword all may be used with --set-module / --clear-module to address every layer at once.
Precedence
per-module override > global level
A layer with no explicit override inherits the global level. --show displays which of the two is in effect for every layer ((override) vs (global)).
Output Sinks
A sink is a destination. Any combination may be active at the same time.
|
Sink |
Destination |
|---|---|
|
|
Standard output (colored) |
|
|
Standard error (colored) |
|
|
Rotating file under the log directory |
|
|
syslog on Linux/FreeBSD, Windows Event Log on Windows |
If logging is enabled but no sink is configured, MFT falls back to stderr so that messages are never silently lost.
On Windows, the syslog sink writes to the Event Log and requires administrator rights the first time, to register the event source.
Command Reference
nvtoolslogger
[-l|--set-level LEVEL] [-m|--set-module MODULE:LEVEL] [-M|--clear-module MODULE]
[-o|--enable-output SINK] [-O|--disable-output SINK] [-n|--set-max-log-files COUNT]
[-s|--show] [-r|--reset] [-h|--help]
|
Option |
Argument |
Description |
|---|---|---|
|
|
|
Set the global severity threshold: |
|
|
|
Set a per-module severity override, e.g. |
|
|
|
Remove a per-module override, reverting that layer to the global level. |
|
|
|
Enable an output sink: |
|
|
|
Disable an output sink. May be repeated. |
|
|
|
Maximum number of Maximum value is 1000. |
|
|
— |
Print the active configuration and the resolved level of every layer. |
|
|
— |
Restore the default configuration (global level |
|
|
— |
Print usage and exit. |
Both --option value and --option=value forms are accepted, as are the short forms
(-l info).
Common Tasks
Watch the log live on the terminal while running a tool:
nvtoolslogger --set-level debug --enable-output stdout
mlxlink -d /dev/mst/mt4123_pciconf0
Investigate a device-access problem (infrastructure layer):
nvtoolslogger --set-module mtcr:debug --set-module reg_access:debug --enable-output file
Turn a single layer back to the global level:
nvtoolslogger --clear-module mtcr
Quiet down without losing the configuration (keeps overrides and sinks, stops most output):
nvtoolslogger --set-level error
Stop writing to disk, keep the rest:
nvtoolslogger --disable-output file
Inspecting the Configuration
$ nvtoolslogger --show
NVIDIA Tools Logger Configuration
========================
Global severity level: info
Max log directory files: 100
Active sinks:
- file
- stdout
Per-module severity overrides:
mtcr: debug
Resolved layer settings:
mtcr: debug (override)
reg_access: info (global)
flint: info (global)
mlxconfig: info (global)
mlxlink: info (global)
mlxreg: info (global)
mft_core: info (global)
mlxfwops: info (global)
npgs: info (global)
mst_tool: info (global)
efuse: info (global)
common: info (global)
hca_caps: info (global)
The Resolved layer settings section is the authoritative answer to "what will actually be logged": it shows the effective level per layer and whether it came from an override or from the global level.
Reading the Log Output
Log File Naming
Each MFT process writes its own file in the log directory:
/var/log/mft/<tool-name>_<pid>.log
for example /var/log/mft/flint_20416.log.
Line Format
[2026-07-30 13:41:07.482] [debug] [mtcr] [mtcr_ul.c:412 mread4] read 0xf0014 = 0x00000001
| | | | |
timestamp severity layer source location message
Session Banner
Whenever logging is enabled, each MFT process writes a three-line banner at the top of its output, so every log is self-describing:
[2026-07-30 13:41:07.480] [logger] PID: 20416
[2026-07-30 13:41:07.480] [logger] Command line: flint -d /dev/mst/mt4123_pciconf0 q
[2026-07-30 13:41:07.481] [logger] MFT version: ...
Always include this banner when attaching a log to a bug report.
Log Rotation and Clean-up
A single process log rotates at 10 MB, keeping up to 5 rotated files.
At start-up, the file sink prunes the log directory so at most --set-max-log-files (default 100) *.log files remain; the oldest are deleted first.
Nothing is deleted automatically while logging is disabled or when the file sink is off.
Configuration File Format
nvtoolslogger is the supported way to edit the configuration, but the file is plain JSON and readable for inspection or for deployment via configuration management:
{
"global_level" : "info",
"max_log_dir_files" : 100,
"modules" :
{
"mtcr" : "debug"
},
"sinks" :
[
"file",
"stdout"
],
"version" : 1
}
|
Key |
Meaning |
|---|---|
|
|
Configuration schema version (currently 1). |
|
|
Global severity threshold. |
|
|
Log-directory file cap. |
|
|
Per-layer overrides. |
|
|
Enabled output destinations. |
The file is written atomically (temporary file + rename), so a tool reading it concurrently never sees a partially written configuration. Unknown module names are skipped with a warning; unknown or malformed values fall back to defaults.
Appendix for Developers
Adding log calls inside MFT sources goes through the shared logger API rather thanprintf/cout:
-
C++:
nvtoolslogger/NvToolsLogger.h—NvToolsLogger::debug(Layer::FLINT, "..."), plus thelogf()printf-style variant -
C:
nvtoolslogger/nvtoolslogger_c.h—mft_log()/mft_log_fmt() -
Python:
nvtoolslogger_api.py—Logger.debug(Layer.MTCR, "...")
New layers are added to layers.h (both the C enum and the C++ table); they then appear automatically in nvtoolslogger --help, --show, and the validation messages.
Last updated: