From ff37da92b65a28def43547b30f2c109803258d6d Mon Sep 17 00:00:00 2001
From: Jimmy Berry <jberry@suse.com>
Date: Wed, 4 Oct 2017 01:15:17 -0500
Subject: [PATCH] docs/metrics.md: initial documentation of metrics workflow.

---
 docs/metrics.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/metrics.md

diff --git a/docs/metrics.md b/docs/metrics.md
new file mode 100644
index 00000000..e9a17797
--- /dev/null
+++ b/docs/metrics.md
@@ -0,0 +1,55 @@
+# Metrics
+
+Ingest relevant OBS and annotation data to generate insightful metrics.
+
+The overall structure is to loop over all requests to extract point of change
+and calculate metrics. Many of the points of change are treated as deltas,
+meaning add one to this bucket or minus one from another. After all requests are
+ingested the points are walked to evaluate the deltas and recreate the state at
+that point in time.
+
+OBS provides incomplete and inconsistent data which causes odd results like
+negative backlog counts. The ingest tool implements a number of workarounds to
+figure out the correct values when possible, but when not possible the provided
+values are used rather than excluding a fairly large chunk of data. The main
+issues are documented in:
+
+- openSUSE/open-build-service#3857
+- openSUSE/open-build-service#3858
+- openSUSE/open-build-service#3897
+- openSUSE/open-build-service#3898
+
+## Pre-requisites
+
+- InfluxDB instance
+- Grafana instance
+  - import `metrics/grafana` dashboards
+  - create data sources for desired projects
+    setting name and database to the project name (ex. `openSUSE:Factory`)
+
+## Usage
+
+See help information for InfluxDB connection flags.
+
+```
+./metrics -p openSUSE:Factory
+```
+
+Once completed the Grafana dashboard should make pretty graphs.
+
+## Development
+
+Grafana provides an export to JSON option which can be used when the dashboards
+are modified to export them and version control the changes in git. Ensure not
+to unintentionally change the default project, annotation state, or time period
+by saving the dashboard with different defaults.
+
+Use the `--debug` option and inspect individual request XML dumps by looking in
+`~/.cache/osc-plugin-factory-metrics` or:
+
+```
+osc api '/request/$reqid?withfullhistory=1'
+```
+
+When adding new delta based metrics it may be necessary to add key logic in
+`walk_points()` to handle proper grouping for evaluation of deltas.