Timeline Charts

Overview

cikit can visualize historical run data as SVG timeline charts. Timeline data is loaded through cikit data, rendered through TimelineChart, and registered as a run-specific timeline artifact.

A typical workflow is:

cikit data
    |
    +-- env.timeline(...)
            |
            +-- chart_timeline(...)
                    |
                    +-- TimelineChart
                            |
                            +-- TimelinePreset
                            |
                            +-- create(env, ...)
                                    |
                                    +-- TIMELINE artifact
                                            |
                                            +-- generated reports
                                            +-- Sphinx documentation

Timeline Data

A timeline contains ordered references and one or more value series. Every series must contain exactly one value for each reference.

Example:

{
    "refs": ["build-10", "build-11", "build-12"],
    "series": {
        "Coverage": [82.1, 83.4, 84.0],
        "Warnings": [12, 9, 7],
    },
}

Historical timeline data is queried through the configured cikit data service. The local cache stores the current values of individual runs, while timeline queries use the remote history.

Reference Keys

The X-axis reference is selected through RefKey.

Available reference keys are:

  • ID

  • INDEX_DESC

  • TIMESTAMP

  • COMMIT_HASH

  • SHORT_COMMIT_HASH

  • PIPELINE_ID

INDEX_DESC is useful for compact CI reports because the newest entry is represented by 0, the previous entry by -1, and so on.

Creating and Registering a Timeline

chart_timeline() retrieves historical data through the active CiRunEnvironment and creates a configurable TimelineChart object.

At this point no SVG file or cikit artifact exists yet.

timeline = chart_timeline(
    env,
    keys=["warnings", "errors"],
    title="Build diagnostics",
    limit=20,
)

The chart can now be configured before rendering:

timeline.set_preset(TimelinePreset.LINE_REPORT)

Calling create() performs the actual rendering and artifact registration:

artifact = timeline.create(env, "build_diagnostics")

This creates chart_build_diagnostics.svg and registers the file as an ArtifactType.TIMELINE artifact of the current logical run.

Direct TimelineChart Usage

A chart can also be created directly from already available timeline data:

from cikit.timeline import TimelineChart, TimelinePreset

chart = TimelineChart(
    data,
    title="Code quality",
    preset=TimelinePreset.LINE_REPORT,
)

chart.create(env, "quality")

The constructor validates the timeline structure immediately. Invalid reference or series data therefore fails before rendering.

Presets

TimelinePreset selects a complete visual configuration, including the chart class, style, dimensions, guides, legend behavior, and chart-specific options.

The currently available preset families are:

  • Line charts

  • Compact line charts

  • Report-oriented line charts

  • Filled report line charts

  • Grouped bar charts

  • Compact grouped bar charts

  • Report-oriented grouped bar charts

  • Stacked bar charts

Use stacked bars only when the series form meaningful additive parts of a total.

For a visual comparison of every available preset, see Timeline Preset Gallery.

Customizing Charts

A preset provides the starting configuration. Individual settings may be overridden afterwards.

Chart-wide Pygal options:

chart.set_chart_options(
    height=360,
    show_x_guides=True,
)

Change the chart style:

chart.set_style(custom_style)

Configure one series:

chart.set_series_options(
    "Warnings",
    secondary=True,
)

The Pygal chart class itself can also be replaced with set_chart_class(). These lower-level overrides are useful for project-specific visualization while the preset remains the normal starting point.

Report Integration

Timeline charts are integrated into reports exclusively through the cikit artifact mechanism.

TimelineChart.create() registers the rendered SVG as an ArtifactType.TIMELINE artifact. Reports do not access TimelineChart objects directly.

A report may choose to include timeline artifacts of the current run:

env.get_run_artifacts(ArtifactType.TIMELINE)

Whether timeline charts appear in a report therefore depends on the report implementation. Reports supporting TIMELINE artifacts include them automatically when such artifacts have been registered before report generation.

The current generic test and build reports support timeline artifacts.

This also means that creating a timeline and creating a report remain independent operations:

timeline = chart_timeline(...)
timeline.create(env, "build")

reports.write_build_report(env)

The report discovers the timeline through the artifact registry. No timeline object needs to be passed to the report.

Sphinx Integration

During Sphinx preparation, registered timeline artifacts are copied into the documentation’s static artifact area.

The cikit-chart directive embeds SVG charts as interactive HTML objects:

.. cikit-chart:: ../_static/artifacts/chart_build.svg
   :alt: Build timeline
   :width: 100%

Non-HTML builders receive a regular image fallback.