Logging

Kopia maintains diagnostic logging for troubleshooting purposes. This documents describes parameters that can be set to configure logging:

Log File Location

The location of log directory varies by operating system:

On Linux - ~/.cache/kopia
On macOS - ~/Library/Logs/kopia
On Windows - %LocalAppData%\kopia

Log file location can be overridden by setting flag --log-dir or KOPIA_LOG_DIR environment variable.

The log directory contains two subdirectories:

cli-logs - contains one log file per each invocation of kopia binary and contains general-purpose logging and debugging information and may contain sensitive information like username, hostname, filenames, etc. Please sanitize contents of such log files before filing bug reports.
content-logs - contains one log file per each invocation of kopia binary and contains low-level formatting logs but will not contain any sensitive data such as file names, hostnames, etc.

Log Retention

Log retention can be configured using flags and environment variables.

Flag	Environment Variable	Default	Description
`--log-dir-max-files`	`KOPIA_LOG_DIR_MAX_FILES`	1000	Maximum number of log files to retain
`--log-dir-max-age`	`KOPIA_LOG_DIR_MAX_AGE`	720h	Maximum age of log files to retain
`--content-log-dir-max-files`	`KOPIA_CONTENT_LOG_DIR_MAX_FILES`	5000	Maximum number of content log files to retain
`--content-log-dir-max-age`	`KOPIA_CONTENT_LOG_DIR_MAX_AGE`	720h	Maximum age of content log files to retain

Controlling Log Level

The amount of logs can be controlled using log levels:

debug - most detailed logs including potentially verbose debugging information
info - normal output
warning - errors and warnings only
error - errors only

You can control how much data is written to console and log files by using flags:

--log-level - sets log level for console output (defaults to info)
--file-log-level - sets log level for file output (defaults to debug)

Color Output

By default, console output will be colored to indicate different log levels, this can be disabled (useful when redirecting output to a file) with --disable-color. To force color colorized output when redirecting to a file use --force-color.

Progress Output

Kopia displays progress information during operations such as snapshots and synchronization. This output can be controlled separately from log levels using --progress (default) or --no-progress flags. This is particularly useful when running Kopia in scripts or scheduled tasks where clean output is preferred.