timelineviz 0.4.3

Timeline visualisation for CSV data and Prometheus test files

timelineviz

Timeline visualisation for CSV data and Prometheus test files.

Features

• Plot event timelines from CSV / DataFrame timestamp data
• Long-format logs — one timestamp column across many rows, with optional filters on level / event type (incident-style timelines)
• Handle time gaps with broken timeline display
• Auto-detect timestamp columns based on naming patterns
• Visualise Prometheus promtool unit-test files — series values, eval checkpoints, and alert checks on a relative time axis
• Customisable colour schemes
• CLI and Python API
• Optional next step: use saved PNGs (plus your CSV or milestone list) as input to multimodal / image-generation LLMs to produce executive-style infographics — see below

Installation

pip install timelineviz

# or with uv
uv add timelineviz

Python 3.11 or newer is required.

For development:

git clone https://github.com/garrywilliams/timeline_viz.git
cd timeline_viz
make install
make precommit-install

Run make or make help for tests, linting, builds, and other tasks. CI, release, and maintainer setup details live in DEVELOPING.md.

Quick Start

CSV / DataFrame Timelines

# Auto-detect timestamp columns
timelineviz data.csv --detect-timestamps --output-dir timelines

# Specify columns explicitly
timelineviz data.csv --timestamp-columns created_at updated_at completed_at

# Read CSV data from stdin
cat data.csv | timelineviz --timestamp-columns created_at updated_at completed_at

# Add more visually staggered label bubbles
timelineviz data.csv --timestamp-columns created_at updated_at completed_at --varying-height

from timelineviz import plot_timeline, plot_multiple_timelines

import pandas as pd
df = pd.read_csv("data.csv")

# Single entity
plot_timeline(df.iloc[0],
              timestamp_columns=['created_at', 'updated_at', 'completed_at'],
              entity_id="12345")

# Multiple entities
plot_multiple_timelines("data.csv",
                        timestamp_columns=['created_at', 'updated_at'],
                        id_column='entity_id',
                        output_dir="timeline_images")

Event log (long format)

Use this when each row is one event and times live in a single column (typical logs). Optionally keep or drop rows using another column (for example level or event_type) so you can focus on an incident and ignore noise.

timelineviz examples/incident_log.csv --event-log --log-time-column ts \
  --log-label-column message --log-filter-column level \
  --log-include ERROR WARN --output-dir timelines --no-show

# Pipe log rows straight in via stdin
tail -n 100 logs/development.csv | timelineviz --event-log --log-time-column ts \
  --log-label-column message --log-filter-column level \
  --log-include ERROR WARN --output-dir timelines --no-show

Omit the input path or pass - to read from stdin. This works for wide CSV mode, --event-log, and --promtest.

For plain-text logs, timelineviz can also parse common timestamp-first log lines directly in --event-log mode:

kubectl logs -n app-namespace deploy/my-service --tail=80 --timestamps \
  | timelineviz --event-log --raw-log-format auto \
    --log-include INFO WARN ERROR --output-dir timelines --no-show

This also works for many other timestamped logs, for example:

tail -n 100 app.log \
  | timelineviz --event-log --raw-log-format timestamped \
    --log-include INFO WARN ERROR --output-dir timelines --no-show

In raw log mode, timelineviz defaults to extracted columns ts, level, and message, so --log-include / --log-exclude work without any extra preprocessing. kubectl remains available as an explicit format alias.

Checked-in raw log fixtures:

• examples/raw_kubectl_logs.log
• examples/raw_timestamped_app.log

Example outputs from those fixtures:

from timelineviz import plot_event_log_timeline

plot_event_log_timeline(
    "incident.csv",
    timestamp_column="ts",
    label_column="message",
    filter_column="level",
    include_values=["ERROR", "WARN"],
    varying_height=True,
    output_file="incident_timeline.png",
    show_plot=False,
)

A small sample file is in examples/incident_log.csv.

The diagram below is from that sample, using the CLI flags above (ERROR and WARN rows only, message as the label):

For a denser example with more incident points, varying-height label bubbles, and multiple time breaks, see examples/review_event_log_breaks.csv rendered with --varying-height --threshold-days 2:

Prometheus Test Timelines

Visualise promtool unit-test YAML files — see series values change over time, where evaluations happen, and when alerts fire.

timelineviz examples/promtest_label_minimal.yml --promtest
timelineviz examples/promtest_label_minimal.yml --promtest --output-dir images --no-show

Replace the path with your own promtool unit-test YAML when needed. Checked-in examples live under examples/.

from timelineviz import parse_promtest_file, plot_promtest

groups = parse_promtest_file("examples/promtest_label_minimal.yml")
plot_promtest(groups, output_file="promtest_timeline.png")

Charts are self-documenting — each subplot shows the metric name and raw notation, value labels appear at transition points, eval/alert vertical lines are labelled, and a legend strip at the bottom explains all marker types.

Full guide: PROMTEST.md — notation reference, worked examples, and all parameters.

How It Works

CSV Timelines

Wide format (default): each entity is a row; timestamps live in separate columns (for example created_at, updated_at). Those columns become labelled points on one timeline per entity.

Long format (plot_event_log_timeline / --event-log): many rows share one timestamp column; each row is one point. Filters apply before plotting.

In both cases, when time gaps exceed a threshold, the timeline is broken into segments with slash markers indicating the breaks.

Promtest Timelines

Prometheus test files define metric series as values over discrete time steps (e.g. one value per minute). The library:

1. Parses the YAML and expands the compact notation (1+2x5 → 1, 3, 5, 7, 9, 11)
2. Plots each input_series as a step chart on its own subplot
3. Draws vertical markers at eval_time checkpoints
4. Shows alert check points with firing/pending status
5. Labels the x-axis with relative time offsets (0s, 1m, 2m, …)

Optional break_gap_minutes / CLI --promtest-break-gap: when gaps between anchors (0, series end, each eval/alert time) exceed that many minutes, the chart splits into multiple horizontal panels with slash markers—same idea as CSV threshold_days breaks. See PROMTEST.md and examples/promtest_time_breaks.yml.

From chart output to executive infographics

timelineviz is built for faithful, technical timelines (PNG from the CLI or output_file= in Python). For stakeholder decks, board summaries, or comms, you can treat that output as source material for a second step: a multimodal or image-focused LLM (any tool that accepts an image plus a long text brief—e.g. Nano Banana or similar) together with:

• The exported PNG (or a screenshot of the figure)
• Your structured facts: ordered milestones, dates, short business descriptions, KPIs, risks, and the story you want told
• A detailed creative prompt (audience, tone, layout, colour rules, and what not to invent)

The model can redesign the information as an infographic while you verify dates, labels, and numbers against your data. The sample below is an illustrative executive layout (sample healthcare journey) produced from that kind of workflow—not something timelineviz renders by itself.

Example only: narrative layout, icons, and insight rail were generated for communication design; always validate facts against your source CSV and plots.

API Reference

CSV Mode

Parameter	Description
timestamp_columns	Columns containing timestamp data to visualise
id_column	Column that uniquely identifies each entity
threshold_days	Time gap (in days) that triggers a timeline break
varying_height	Stagger labels above/below the line at varying heights for a more visually layered layout
entity_name	Type name for titles (e.g. "Patient", "Order")
label_mappings	Custom display names for timestamp columns
color_scheme	Dictionary of colour overrides

Promtest Mode

Parameter	Description
figsize	Figure dimensions (width, height) in inches
title	Custom figure title
color_scheme	Override colours (see PROMTEST.md)
output_file	Save to PNG
dpi	Resolution (default 150)

License

MIT