Skip to main content

Collect Diagnostics

Collect the following diagnostic information after reproducing the issue you are observing, and collect the artifacts as soon as the behavior occurs so that runtime data is still available.

Capture Engine Diagnostics

If AI Gateway was started with --diagnostics-directory <directory>, trigger an on-demand snapshot by sending the running process a SIGUSR2 signal:

kill -USR2 <pid>

Zilla writes a timestamped zip archive (zilla-diagnostics-<timestamp>.zip) containing the engine runtime directory into the configured diagnostics directory. The same snapshot is captured automatically if the engine exits due to an unrecoverable error.

If --diagnostics-directory was not configured, archive the engine runtime directory manually instead.

Capture the Engine Runtime Directory Manually

AI Gateway stores its engine runtime state under the engine directory. By default: /var/run/zilla

Info

This location may be different if the zilla.engine.directory parameter is set in zilla.properties. Verify the correct directory before proceeding.

Create a tar archive of the engine directory shortly after reproducing the issue:

tar cvf /tmp/zilla-archive.tar /var/run/zilla

If your engine directory is different, replace /var/run/zilla with the configured path.

Confirm the AI Gateway Version

Capture the exact AI Gateway version you are running:

zilla version -v

Share with Support

Send the following items to support@aklivity.io:

  • zilla-diagnostics-<timestamp>.zip (or zilla-archive.tar if captured manually)
  • Output of zilla version -v
  • AI Gateway configuration file zilla.yaml
  • A brief description of the issue and how to reproduce it.

These artifacts provide the most relevant diagnostic information for stream-level and engine-level analysis and allow support to investigate efficiently.