Reporting issues

Verbose log

If you are going to attach a log file, it would be helpful if the log file actually includes relevant information. By default only warnings and errors are logged by picom, so it's really hard to deduce what picom is doing behind the scene.

To increase the verbosity of picom's log, pass the --log-level=debug option. This is usually enough. However, if your issue is rendering related (e.g. visual artifacts), you should probably use --log-level=trace. Be care, since the trace log level generates a lot of logs, up to several MBs per minute.

Get a stack trace

The easiest way to get a stack trace is through a core dump. When enabled, a core file will be created when picom crashes, in the same directory picom ran from. You can open the core file with gdb: gdb -c /path/to/core, then get a stack trace with the backtrace gdb command. If you are running a systemd system, that's even easier. You just need to run coredumpctl gdb right after the crash, then run backtrace.

If coredump wasn't enabled at the point of the crash. You can enable coredump and run picom again until it crash. Or, you can run picom under gdb, then use the backtrace gdb command.

If you want to get a stack trace while picom is running, instead of after it crashes, you will have to temporarily pause the execution of picom in gdb. However, since picom takes over your screen, your screen won't be updated when picom is suspended by gdb. This can be a little bit confusing, but you can still type commands blindly and gdb will respond.

If you are reporting an issue for the experimental backends, you can run picom with the --debug-mode option to stop picom from taking over your screen. This option changes the behaviour of picom somewhat, so your issue might become unreproducible.

Note, to get a stack trace with useful information, you have to build picom with debug information. You can do that by adding --buildtype=debug to meson configure.

Capture a trace

It's sometimes helpful to know exactly what picom is trying to render. To capture that information, you can use tools like apitrace.

Here is a brief instruction about using apitrace.

To capture a trace with apitrace, you start picom by prepending apitrace trace to your picom command. For example, if you start picom by run picom, you should instead run apitrace trace picom. It might also be helpful to enable trace logging for picom, like this picom --log-level=trace, to include more information in the trace.

If you are capturing a trace for a bug report, please demonstrate the bug when you are capturing the trace.

After you finish, quit picom, and you will find a file named picom.trace in the current directory. That's what you need to upload.

!!IMPORTANT!!: Capturing a trace essentially records your screen. So try not to include any sensitive information, or anything that is irrelevant to your issue. Also try to keep it short to minimized the size of the trace file.