Skip to main content
plog run wraps any Python command with automatic framework instrumentation. No code changes required.

​
Usage

plog run -- python my_agent.py
plog run --agent-id my-agent -- python -m my_package
plog run --db /tmp/audit.db -- python script.py
plog run --server http://localhost:7600 -- python agent.py

​
Flags

FlagDefaultDescription
--agent-idautoAgent identifier for audit events
--db~/.provenlog/events.dbSQLite path (embedded mode)
--server—Server URL (mutually exclusive with --db)

​
How it works

  1. Creates a temporary sitecustomize.py that imports provenlog.auto
  2. Modifies PYTHONPATH to include the temporary file
  3. Executes your command as a child process
  4. Python runs sitecustomize on startup, patching all detected frameworks
  5. stdin/stdout/stderr are forwarded transparently
  6. Signals (SIGINT, SIGTERM) are forwarded to the child
  7. The child’s exit code is preserved

​
Examples

# Basic usage
plog run -- python my_agent.py

# With custom agent ID
plog run --agent-id payment-agent -- python -m payment_processor

# With custom database
plog run --db /var/log/audit.db -- python my_agent.py

# Sending events to a server
plog run --server http://localhost:7600 -- python my_agent.py
See Auto-Instrumentation for details on which frameworks are detected and how patching works.