Grafana Calendar Annotator

Generate annotations in Grafana from events pulled from an ICS calendar.

Hacktoberfest

This project welcomes Hacktoberfest contributions! Any contributions to increase the OpenSSF Best Practices percentage or that close an issue will be given priority.

Getting Started

CLI

$ grafana-calendar-annotator --help

 Usage: grafana-calendar-annotator [OPTIONS]

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *  --grafana-url                 -g      TEXT         Url of the Grafana instance to populate annotations into [required]                                                                                    │
│ *  --grafana-api-key             -k      TEXT         API key to authenticate to the Grafana instance [required]                                                                                             │
│ *  --calendar-url                -c      TEXT         URL of the ICS Calendar to use to populate events from [required]                                                                                      │
│ *  --flatten/--no-flatten        -f/-nf               Flattening events will create a single time annotation instead of a span [default: no-flatten] [required]                                              │
│ *  --flatten-direction           -fd     [start|end]  Create the annotation at the start or the end of the event if the event is flattened [default: (start)] [required]                                     │
│ *  --tags                        -t      TEXT         List of tags to add to created annotations [default: (generated,)] [required]                                                                          │
│ *  --regenerate/--no-regenerate  -r/-nr               Regenerating will delete all annotations that have the same set of tags before creating new annotations [default: regenerate] [required]               │
│    --delete-only                 -d                   Only delete annotations with tags, do not create new annotations                                                                                       │
│    --help                                             Show this message and exit.                                                                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The following flags can be set with environment variables:

Flag	Variable Name
--grafana-url	GRAFANA_URL
--grafana-api-key	GRAFANA_TOKEN
--flatten	FLATTEN
--flatten-direction	FLATTEN_DIRECTION

grafana-calendar-annotator --grafana-url https://my-grafana.com --grafana-api-key abcd1234 --flatten --flatten-direction end --calendar-url https://my-calendar.com/personal.ics

# is the same as this

GRAFANA_URL=https://my-grafana.com GRAFANA_TOKEN=abcd1234 FLATTEN=true FLATTEN_DIRECTION=end grafana-calendar-annotator --calendar-url https://my-calendar.com/personal.ics

Installing

Pip

For the library and the cli

pip install grafana_calendar_annotator

Pipx

Pipx is useful for installing and running applications in isolated environments. I've always found it useful to ensure python applications are can be executed from anywhere in your system.