This is an automated email from the ASF dual-hosted git repository.
zky pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 0248b94add docs: Add "Debugging DORA Issue Metrics" section to
"Dashboard Troubleshooting" guide (#631)
0248b94add is described below
commit 0248b94addaf2c74f4414bcffd06795bd5b049fc
Author: KucherenkoSerhiy <[email protected]>
AuthorDate: Wed Aug 30 11:49:00 2023 +0200
docs: Add "Debugging DORA Issue Metrics" section to "Dashboard
Troubleshooting" guide (#631)
* Co-authored with: Louis.z <[email protected]>
docs: Add "Debugging DORA Issue Metrics" section to "Dashboard
Troubleshooting" guide.
Supplied with .png diagrams for each of the DORA metrics
* docs: add a small troubleshooting section regarding webhook usage
* refact: move dashboard troubleshooting images to
/docs/Configuration/images folder
* docs: include to v0.18
* docs: remove subfolders from image path
---
docs/Configuration/images/cfr.png | Bin 0 -> 47658 bytes
docs/Configuration/images/deployments.png | Bin 0 -> 18243 bytes
docs/Configuration/images/lead_time.png | Bin 0 -> 33594 bytes
docs/Configuration/images/mttr.png | Bin 0 -> 35749 bytes
docs/Troubleshooting/Dashboard.md | 42 +++++++++++++++++++++
.../version-v0.18/Configuration/images/cfr.png | Bin 0 -> 47658 bytes
.../Configuration/images/deployments.png | Bin 0 -> 18243 bytes
.../Configuration/images/lead_time.png | Bin 0 -> 33594 bytes
.../version-v0.18/Configuration/images/mttr.png | Bin 0 -> 35749 bytes
.../version-v0.18/Troubleshooting/Dashboard.md | 42 +++++++++++++++++++++
10 files changed, 84 insertions(+)
diff --git a/docs/Configuration/images/cfr.png
b/docs/Configuration/images/cfr.png
new file mode 100644
index 0000000000..73af317d74
Binary files /dev/null and b/docs/Configuration/images/cfr.png differ
diff --git a/docs/Configuration/images/deployments.png
b/docs/Configuration/images/deployments.png
new file mode 100644
index 0000000000..1e05b23420
Binary files /dev/null and b/docs/Configuration/images/deployments.png differ
diff --git a/docs/Configuration/images/lead_time.png
b/docs/Configuration/images/lead_time.png
new file mode 100644
index 0000000000..a9a3206fe1
Binary files /dev/null and b/docs/Configuration/images/lead_time.png differ
diff --git a/docs/Configuration/images/mttr.png
b/docs/Configuration/images/mttr.png
new file mode 100644
index 0000000000..8c77736a4b
Binary files /dev/null and b/docs/Configuration/images/mttr.png differ
diff --git a/docs/Troubleshooting/Dashboard.md
b/docs/Troubleshooting/Dashboard.md
index 1250cb01e4..9bf31d04ee 100644
--- a/docs/Troubleshooting/Dashboard.md
+++ b/docs/Troubleshooting/Dashboard.md
@@ -5,6 +5,48 @@ description: >
Dashboard Troubleshooting
---
+## Debugging DORA Issue Metrics
+
+This section may help if `Median Time to Restore Service (MTTR)` or `Change
Failure Rate (CFR)` do not appear on the dashboards or you want to learn more
about how these issue-based metrics are built.
+
+### DORA Validation Dashboard
+Starting from DevLake v0.18 this dashboard can be found near the `DORA`
dashboard. Also, it can be accessed by a direct link in the `Dashboard
Instruction` panel in the `DORA` dashboard.
+
+This dashboard is a step-by-step guide to check which step went wrong **for
all 4 of the DORA metrics**. The sections are:
+- Check "Deployment Frequency"
+- Check "Median Lead Time for Changes"
+- Check "Change Failure Rate" & "Median Time to Restore Service
+
+### SQL scripts behind Grafana charts
+Each chart has a hidden button in the top-right corner to access the context
menu. In that menu, click `Edit` to open a more detailed view with the script
that tells how exactly the data is queried.
+
+### How issues and deployments are associated to projects
+
+Following Entity-Relationship diagrams below represent how the data is mapped
and used for each of the 4 DORA metrics.
+They are based on the SQL queries for each of the charts.
+
+Legend:
+- Blue box: user data source, be it **deployments**, **pull requests** from
the source code, or **issues**
+- White box: a table or entity used by DevLake
+- Connections: lines that tell how the tables are mapped, also specify which
fields are used.
+
+The `project_mapping` is responsible for mapping **deployments**, **pull
requests** from the source code, or **issues**.
+To do so, it must be filtered using either `table = 'cicd_scopes'`, `table =
'repos'`, or `table = 'boards'` when connecting to another table.
+
+
+
+
+
+
+
+
+
+### If you use webhooks
+
+DevLake knows to which project an issue or a deployment belongs only by
segregation between the webhooks.
+I.e. **each project should have its own webhook**. A webhook used by multiple
projects means that all the
+issues or deployments published by that webhook **will be replicated among
those projects**, as they belong to both of them.
+
WIP
diff --git a/versioned_docs/version-v0.18/Configuration/images/cfr.png
b/versioned_docs/version-v0.18/Configuration/images/cfr.png
new file mode 100644
index 0000000000..73af317d74
Binary files /dev/null and
b/versioned_docs/version-v0.18/Configuration/images/cfr.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/deployments.png
b/versioned_docs/version-v0.18/Configuration/images/deployments.png
new file mode 100644
index 0000000000..1e05b23420
Binary files /dev/null and
b/versioned_docs/version-v0.18/Configuration/images/deployments.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/lead_time.png
b/versioned_docs/version-v0.18/Configuration/images/lead_time.png
new file mode 100644
index 0000000000..a9a3206fe1
Binary files /dev/null and
b/versioned_docs/version-v0.18/Configuration/images/lead_time.png differ
diff --git a/versioned_docs/version-v0.18/Configuration/images/mttr.png
b/versioned_docs/version-v0.18/Configuration/images/mttr.png
new file mode 100644
index 0000000000..8c77736a4b
Binary files /dev/null and
b/versioned_docs/version-v0.18/Configuration/images/mttr.png differ
diff --git a/versioned_docs/version-v0.18/Troubleshooting/Dashboard.md
b/versioned_docs/version-v0.18/Troubleshooting/Dashboard.md
index 1250cb01e4..868a7dbde5 100644
--- a/versioned_docs/version-v0.18/Troubleshooting/Dashboard.md
+++ b/versioned_docs/version-v0.18/Troubleshooting/Dashboard.md
@@ -5,6 +5,48 @@ description: >
Dashboard Troubleshooting
---
+## Debugging DORA Issue Metrics
+
+This section may help if `Median Time to Restore Service (MTTR)` or `Change
Failure Rate (CFR)` do not appear on the dashboards or you want to learn more
about how these issue-based metrics are built.
+
+### DORA Validation Dashboard
+Starting from DevLake v0.18 this dashboard can be found near the `DORA`
dashboard. Also, it can be accessed by a direct link in the `Dashboard
Instruction` panel in the `DORA` dashboard.
+
+This dashboard is a step-by-step guide to check which step went wrong **for
all 4 of the DORA metrics**. The sections are:
+- Check "Deployment Frequency"
+- Check "Median Lead Time for Changes"
+- Check "Change Failure Rate" & "Median Time to Restore Service
+
+### SQL scripts behind Grafana charts
+Each chart has a hidden button in the top-right corner to access the context
menu. In that menu, click `Edit` to open a more detailed view with the script
that tells how exactly the data is queried.
+
+### How issues and deployments are associated to projects
+
+Following Entity-Relationship diagrams below represent how the data is mapped
and used for each of the 4 DORA metrics.
+They are based on the SQL queries for each of the charts.
+
+Legend:
+- Blue box: user data source, be it **deployments**, **pull requests** from
the source code, or **issues**
+- White box: a table or entity used by DevLake
+- Connections: lines that tell how the tables are mapped, also specify which
fields are used.
+
+The `project_mapping` is responsible for mapping **deployments**, **pull
requests** from the source code, or **issues**.
+To do so, it must be filtered using either `table = 'cicd_scopes'`, `table =
'repos'`, or `table = 'boards'` when connecting to another table.
+
+
+
+
+
+
+
+
+
+### If you use webhooks
+
+DevLake knows to which project an issue or a deployment belongs only by
segregation between the webhooks.
+I.e. **each project should have its own webhook**. A webhook used by multiple
projects means that all the
+issues or deployments published by that webhook **will be replicated among
those projects**, as they belong to both of them.
+
WIP
