---

name: plox description: Plot timestamped logs as graphs. Use when user wants to visualize log data, plot numeric values over time, count events, track time deltas between events, compare multiple log files, or get statistics from logs.

plox - Time Plots from Logs

Turn messy logs into clean graphs. Extract numeric values using regex and plot them over time.

Requirements

• plox must be available in PATH
• gnuplot required for PNG output

Commands

graph - Plot data from logs

Copyplox graph --input <LOG_FILE> --plot <GUARD> <FIELD> [OPTIONS]

Basic example:

Copyplox graph --input app.log --plot duration

With regex extraction:

Copyplox graph --input app.log --plot worker "took:([\d\.]+)(\w+)?"

Multiple panels:

Copyplox graph --input app.log \
  --plot module1 value1 \
  --panel \
  --plot module2 value2

stat - Show statistics and histogram

Copyplox stat --input <LOG_FILE> field-value <GUARD> <FIELD>

Shows count, min, max, mean, median, percentiles (q75, q90, q95, q99) and ASCII histogram.

cat - Display extracted values

Copyplox cat --input <LOG_FILE> field-value <GUARD> <FIELD>

Prints raw extracted timestamp-value pairs.

match-preview - Debug regex patterns

Copyplox match-preview --input <LOG_FILE> --verbose <GUARD> <FIELD>

Test regex patterns before plotting. Use -v or -vv for more detail.

Data Sources (Line Types)

Line Styling Options

Panel Options

Input Options

Output Options

Generated files:

• PNG graph at specified location
• .gnuplot script alongside PNG
• CSV cache in .plox/ directory next to log files

Multi-File Comparison

Binding lines to specific files

Copy# Apply line only to 3rd input file (0-indexed)
--input a.log,b.log,c.log --plot guard duration --file-id 2

# Apply line to a specific file
--plot guard duration --file-name errors.log

Per-file panel duplication

Copy# Duplicate panel layout for each input file
plox graph --input a.log,b.log --per-file-panels \
  --plot worker duration

Creates separate panels for each log file, useful for side-by-side comparison.

Panel alignment

Timestamp Formats

Field Regex Patterns

The field can be a simple name or regex with capture groups:

Unit conversion: Time units (s, ms, us, ns) are auto-converted to milliseconds when captured.

TOML Config Example

Copy[[panels]]
panel_title = "Metrics"
legend = true

[[panels.lines]]
guard = "worker"
field = "duration"
style = "points"
marker_size = 3.0
marker_color = "red"
title = "Worker duration"

[[panels]]

[[panels.lines]]
guard = "module"
field = 'count=(\d+)'
style = "steps"
line_color = "blue"

Environment Variables

Workflow

1. Start simple: plox graph --input app.log --plot <keyword>
2. Debug regex: plox match-preview -v --input app.log <guard> <field>
3. Check distribution: plox stat --input app.log field-value <guard> <field>
4. Iterate: Add panels, styling, more lines
5. Save config: -w config.toml when CLI gets complex
6. Reuse: plox graph -i new.log -c config.toml
7. Compare logs: --input a.log,b.log --per-file-panels

Real-World Example

Given log lines like:

Copy2025-04-22 09:31:00.885 INFO maintain txs=(29382, 0) duration=56.206398ms
2025-04-22 09:31:13.081 DEBUG prune: validated_counter=2, took:4.708552ms

Copy# Plot prune duration and validation count
plox graph --input eve.log \
  --plot prune "validated_counter" --style points --marker-size 3 \
  --panel \
  --plot prune "took:([\d\.]+)(\w+)?" --style points --marker-size 3

# Extract watched txs count from maintain lines
plox graph --input eve.log \
  --plot maintain "txs=\((\d+),\s+\d+\)"