Logging

The Foxglove Agent provides configurable logging to help you monitor its operation and troubleshoot issues.

Log output configuration

The FOXGLOVE_LOG_OUTPUT environment variable controls where the Agent writes its logs. Three output modes are available:

Mode	Output destination	Best for
journald	System journal (systemd)	Production deployments with systemd
json	JSON-formatted logs to stderr	Log aggregation and automated parsing
text	Human-readable logs to stderr	Development and manual troubleshooting

The installation guide's environment templates configure journald for Debian and standalone deployments, and text for Docker. You only need to change this setting if you want different log output behavior.

Viewing logs

How you access Agent logs depends on your installation method and log output configuration.

Debian package

The Agent writes structured log entries to the system journal. View logs with journalctl:

# View recent logs
journalctl -u foxglove-agent

# Follow logs in real-time
journalctl -u foxglove-agent -f

To export the binary journal (for example, to provide to Foxglove support):

journalctl -u foxglove-agent --since "1 hour ago" -o export > foxglove-agent.journal

Statically linked Linux executable

If you run the Agent under systemd, view logs with journalctl, replacing <unit-name> with your service's unit name:

# View recent logs
journalctl -u <unit-name>

# Follow logs in real-time
journalctl -u <unit-name> -f

To export the binary journal (for example, to provide to Foxglove support):

journalctl -u <unit-name> --since "1 hour ago" -o export > foxglove-agent.journal

If you don't use systemd, logs are written to stderr based on your FOXGLOVE_LOG_OUTPUT setting.

Docker image

Logs are written to stderr. Use docker logs to view them:

# View recent logs
docker logs <container-name>

# Follow logs in real-time
docker logs -f <container-name>

Log levels

The Agent uses the following log levels, from least to most verbose:

• error: Critical errors that require attention
• warn: Warnings about potential issues or degraded operation
• info: General informational messages about Agent activity (default)
• debug: Detailed diagnostic information for troubleshooting

Enabling debug logging

Set the FOXGLOVE_LOG environment variable to enable debug logging:

FOXGLOVE_LOG=info,agent=debug

This configuration sets the log level to debug for the agent itself, but retains a default log level of info for the agent's library dependencies.

Debug logging may be useful for:

• Investigating file discovery and indexing issues
• Troubleshooting upload problems
• Providing detailed logs when reporting issues to Foxglove support

warning

Don't leave debug logging enabled continuously in production environments, as it can:

• Generate large log volumes
• Make it harder to identify important messages
• Impact performance in high-throughput scenarios

Enable debug logging temporarily when investigating specific issues, then return to the default log level.