Configuration file

A report is declared entirely within a YAML file consisting of a few main sections: datasources, views, and outputs. In each section, you can declare as many plugin instances as you wish (to e.g., declare multiple database Datasources or multiple Plot visualizations in your report). As dictated by the YAML spec, duplicate keys (IDs) are not allowed; ensure that each plugin instance has its own ID unique to its section.

Note

It is possible to specify multiple configuration files when generating a report. In this case, the configurations are merged together, with the last file taking priority:

kpireport -c base-config.yaml -c extra-config.yaml

A full example

For more examples see Examples.

---
title: My report

datasources:
  db:
    plugin: mysql
    args:
      host: 127.0.0.1
  jenkins:
    plugin: jenkins
    args:
      host: 127.0.0.1:8000

views:
  line_plot:
    title: A line plot
    plugin: plot
    args:
      # Note that this refers to the "db" datasource registered above.
      datasource: db
      query: |
        select time, value from my_db.my_table
        where time > {from} and time < {to}
  results_table:
    title: A table of values
    plugin: table
    args:
      # Note that this refers to the "db" datasource registered above.
      datasource: db
      query: |
        select count(value), value from my_db.my_table
        where time > {from} and time < {to}
        group by value

outputs:
  mail:
    plugin: smtp
    args:
      smtp_host: 127.0.0.1
      smtp_port: 1025

Schema

Configuration file

https://kpi-reporter.readthedocs.io/page/configuration.schema.json
type	object
properties
title	Title of the report.
	type	string
interval_days	The report interval in days. This value is only used if start_date is not explicitly defined.
	type	integer
	default	7
start_date	Beginning of reporting period.
	type	string
	default	End date minus the number of dates in interval_days.
	format	date
end_date	End of reporting period.
	type	string
	default	Current date.
	format	date
theme	theme
datasources	Set of named datasource instances; the keys define the IDs.
	type	object
	additionalProperties	datasource
views	Set of named view instances; the keys define the IDs.
	type	object
	additionalProperties	view
outputs	Set of named output driver instances; the keys define the IDs.
	type	object
	additionalProperties	output
additionalProperties	False

theme

type	object
properties
num_columns	Number of columns in view grid layout.
	type	integer
	default	6
column_width	Width of single column in view grid layout, in pixels.
	type	integer
	default	86
theme_dir	Path to directory with additional theme assets.
	type	string
additionalProperties	False

datasource

type	object
properties
plugin	Name of datasource plugin to use.
	type	string
args	type	object
	additionalProperties	True
additionalProperties	False

view

type	object
properties
plugin	Name of view plugin to use.
	type	string
args	type	object
	additionalProperties	True
title	Optional headline title for the view.
	type	string
description	Optional description for the view.
	type	string
cols	Number of grid columns to take up.
	type	integer
	default	Total number of columns defined in theme (full bleed).
additionalProperties	False

output

type	object
properties
plugin	Name of output driver plugin to use.
	type	string
args	type	object
	additionalProperties	True
additionalProperties	False

View instances

The View instances defined in the views section define what is rendered in the final report. Each view is placed into a layout in the order in which they are defined, i.e., the first declared View will show at the top, and the last will show at the bottom.

The report layout follows a simple grid system with 6 columns. By default, Views will each take the full width. However, you can change this with the cols configuration option. For example, consider this configuration:

views:
  view_a:
  view_b:
    cols: 2
  view_c:
    cols: 4
  view_d:
  view_e:
    cols: 3
  view_f:
    cols: 3

The views would be rendered in the report like this:

View A
View B	View C
View D
View E		View F