Skip to content

Commit

Permalink
Move our documentation out to readthedocs.io (#161)
Browse files Browse the repository at this point in the history 
* Migrate to mkdocs for publishing on readthedocs

* Start nav

* Fixing images, links and nav

* Test local linking

* use page prefix on install links

* Hopefully final commit with link fixes, readme and contributing update.

* Fix img links on README
  • Loading branch information
@etsauer
etsauer authored Aug 18, 2020
1 parent 303aabc commit 19f976f
Show file tree
Hide file tree
Showing 22 changed files with 70 additions and 39 deletions.
0 docs/CONTRIBUTING.md → CONTRIBUTING.md
View file
File renamed without changes.
13 changes: 5 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
![Pelorus](media/Logo-Pelorus-A-Standard-RGB_smaller.png)
![Pelorus](docs/img/Logo-Pelorus-A-Standard-RGB_smaller.png)

![](https://github.com/redhat-cop/pelorus/workflows/Pylama/badge.svg)

Expand All @@ -16,17 +16,14 @@ Currently, Pelorus functionality can capture proven metrics that measure Softwar

Pelorus is a Grafana dashboard that can easily be deployed to an OpenShift cluster, and provides an organizational-level view of the [four critical measures of software delivery performance](https://blog.openshift.com/exploring-a-metrics-driven-approach-to-transformation/).

![Software Delivery Metrics Dashboard](media/sdp-dashboard.png)
![Software Delivery Metrics Dashboard](docs/img/sdp-dashboard.png)

A short video describing each of these metrics is available [here](https://www.youtube.com/watch?v=7-iB_KhUaQg).

## Installation
## Documentation

A guide for installation can be found in the install document found in the [install guide](./docs/Install.md)

## User Guide
The [Pelorus user guide](/docs/UserGuide.md) provides an index to all documentation.
Pelorus documentation is available at [pelorus.readthedocs.io](https://pelorus.readthedocs.io/).

## Contributing to Pelorus

If you are interested in contributing to the Pelorus project, please review our Contribution guide which can be found in the [contribution guide](./docs/CONTRIBUTING.md)
If you are interested in contributing to the Pelorus project, please review our Contribution guide which can be found in the [contribution guide](./CONTRIBUTING.md)
2 changes: 1 addition & 1 deletion docs/Architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The following diagram shows the various components and traffic flows in the Pelorus ecosystem.

![Pelorus Architecture Diagram](/media/architecture.png)
![Pelorus Architecture Diagram](img/architecture.png)

Pelorus is composed of the following open source components.

Expand Down
4 changes: 2 additions & 2 deletions docs/Configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Configuring The Pelorus Stack

The Pelorus stack (Prometheus, Grafana, Thanos, etc.) can be configured by changing the `values.yaml` file that is passed to helm. The recommended practice is to make a copy of the one [provided in this repo](/charts/)deploy/values.yaml), and store in in your own configuration repo for safe keeping, and updating. Once established, you can make configuration changes by updating your `values.yaml` and applying the changes like so:
The Pelorus stack (Prometheus, Grafana, Thanos, etc.) can be configured by changing the `values.yaml` file that is passed to helm. The recommended practice is to make a copy of the one [provided in this repo](https://github.com/redhat-cop/pelorus/blob/v1.2.1-rc/charts/pelorus/values.yaml), and store in in your own configuration repo for safe keeping, and updating. Once established, you can make configuration changes by updating your `values.yaml` and applying the changes like so:

```
helm upgrade pelorus charts/deploy --namespace pelorus --values myclusterconfigs/pelorus/values.yaml
Expand All @@ -15,7 +15,7 @@ The following configurations may be made through the `values.yaml` file:
| `openshift_prometheus_htpasswd_auth` | yes | The contents for the htpasswd file that Prometheus will use for basic authentication user. | User: `internal`, Password: `changeme` |
| `openshift_prometheus_basic_auth_pass` | yes | The password that grafana will use for its Prometheus datasource. Must match the above. | `changme` |
| `custom_ca` | no | Whether or not the cluster serves custom signed certificates for ingress (e.g. router certs). If `true` we will load the custom via the [certificate injection method](https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#certificate-injection-using-operators_configuring-a-custom-pki) | `false` |
| `extra_prometheus_hosts` | no | Configures additional prometheus instances for a multi-cluster setup. See [Deploying across multple clusters](/docs/Install.md#deploying-across-multiple-clusters) for details. | Nil |
| `extra_prometheus_hosts` | no | Configures additional prometheus instances for a multi-cluster setup. See [Deploying across multple clusters](/page/Install.md#deploying-across-multiple-clusters) for details. | Nil |
| `exporters` | no | Specified which exporters to install. See [Configuring Exporters](#configuring-exporters). | Installs deploytime exporter only. |

## Configuring Exporters
Expand Down
22 changes: 11 additions & 11 deletions docs/Dashboards.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ By providing data organized into collections that track organizational behaviors

_Software Delivery Performance_ is a measure of an organization's ability to effectively deliver software-based products they have built to their customers. It is comprised of 4 _measures_ that provide a balanced perspective, taking both speed to market and stability measures into account. Tracking _Software Delivery Performance_ over time provides IT organizations with data they can use to make smarter investments in their internal tools and processes to optimize their delivery processes based on the types of products they are delivering. This outcomes provides a bridge between development, operations and leadership, allowing them to better communicate about whether proposed work on infrastructure imrovements or process developments are in line with the overall vision and financial goals of the organization at large.

![Software Delivery Performance dashboard](/media/sdp-dashboard.png)
![Software Delivery Performance dashboard](img/sdp-dashboard.png)

The Pelorus _Software Delivery Performance_ dashboard tracks the four primary measures of software delivery:

Expand All @@ -31,7 +31,7 @@ The Pelorus _Software Delivery Performance_ dashboard tracks the four primary me
### Measures

![Exporter relaionship diagram](/media/exporter-relationship-diagram.png)
![Exporter relaionship diagram](img/exporter-relationship-diagram.png)

#### Lead Time for Change

Expand All @@ -47,10 +47,10 @@ For an organization-level measurement, aggregate by averaging the lead time for

The following exporters are required to calculate _Lead Time for Change_:

* The [commit time exporter](/exporters/committime) provides the `commit_time` metric, which is the timestamp that a commit was made to source control.
* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.
* The [commit time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/committime) provides the `commit_time` metric, which is the timestamp that a commit was made to source control.
* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.

The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `commit_time` and `deploy_time` data points into the following metrics:
The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/templates/prometheus-rules.yaml). This converts individual `commit_time` and `deploy_time` data points into the following metrics:

* `sdp:lead_time:by_app` - Calculated lead times by application (`deploy_time - commit_time`)
* `sdp:lead_time:global` - A Global average of `sdp:lead_time:by_app`
Expand All @@ -71,7 +71,7 @@ For an organization-level measurement, take the sum across product-level deploym

The following exporters are required to calculate _Deployment Frequency_:

* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.
* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.

The dashboard then just tracks a `count_over_time()` of the individual `deploy_time` metrics for the time range selected in the dashboard. It also provides a comparison to the previous time range.

Expand All @@ -89,9 +89,9 @@ For an organizational-level measurement, average MTTR data across products.

The following exporters are required to calculate _Mean Time to Restore_:

* The [failure exporter](/exporters/failure) provides the `failure_creation_timestamp` and `failure_resolution_timestamp` metrics, which attempt to capture the beginning and end of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future.
* The [failure exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/failure) provides the `failure_creation_timestamp` and `failure_resolution_timestamp` metrics, which attempt to capture the beginning and end of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future.

The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `failure_resolution_timestamp` data points into the following metrics:
The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `failure_resolution_timestamp` data points into the following metrics:

* `fr:time_to_restore` - A calculated time to restore for each failure event (`failure_resolution_timestamp - failure_creation_timestamp`)
* `fr:time_to_restore:global` - A global average of all `fr:time_to_restore` calculations.
Expand All @@ -113,10 +113,10 @@ For an organizational-level measurement, expand the scope of the failures captur

The following exporters are require to calculate _Change Failure Rate_:

* The [failure exporter](/exporters/failure) provides the `failure_creation_timestamp` metrics, which attempt to capture the beginning of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future.
* The [deploy time exporter](/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.
* The [failure exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/failure) provides the `failure_creation_timestamp` metrics, which attempt to capture the beginning of individual failure or degredation events in customer-facing systems. This data is typically collected from a ticketing system, though automated approaches of failure detection and tracking could be added in the future.
* The [deploy time exporter](https://github.com/redhat-cop/pelorus/blob/master/exporters/deploytime) provides the `deploy_time` metric, which is a timestamp that a production deployment was rolled out.

The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `deploy_time` data points into the following metric:
The exporters are only responsible for gathering data about individual events. Before the dashboard consumes them, we perform some aggregation calculations in a set of [PrometheusRules](https://github.com/redhat-cop/pelorus/blob/master/charts/deploy/templates/prometheus-rules.yaml). This converts individual `failure_creation_timestamp` and `deploy_time` data points into the following metric:

* `fr:change_failure_rate` - A ratio of the number of failed changes to the total number of changes to the system.

Expand Down
6 changes: 3 additions & 3 deletions docs/Demo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ The second argument the script takes is the url of the forked repo, so for examp
## Execution

An "idle" state could resemble:
![Idle-Data](../media/pelorus-dashboard-idle-data.png)
![Idle-Data](img/pelorus-dashboard-idle-data.png)

Run the demo script
```
pelorus/demo/demo.sh <path to container-pipelines> <url to forked repo>
```

The script will start and will begin to run the ansible-applier on the <path to container-pipelines> path. It will attempt to install ansible-galaxy, skipping if it is, and then run the ansible-applier playbook. This will setup a build (jenkins) as well as a dev, stage and prod environment. Once jenkins has been setup, an initial run of the basic-nginx app will build and deploy. Once that is complete, the dashboard should resemble the following:
![First-Deploy-Data](../media/pelorus-dashboard-first-deploy.png)
![First-Deploy-Data](img/pelorus-dashboard-first-deploy.png)

A prompt will appear on the screen waiting for user input, the user can "rerun" the script. What this will do is create a change in the index.html file, git commit and push it to the <url to forked repo> repository, then create another pipeline build. Then the second pipeline build of basic-nginx will start. Once complete, the dashboard will update again:
![Second-Deploy-Data](../media/pelorus-dashboard-second-deploy.png)
![Second-Deploy-Data](img/pelorus-dashboard-second-deploy.png)
20 changes: 10 additions & 10 deletions docs/Development.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,25 @@ There are three main tracks of Pelorus development to consider.

We use [Helm](https://helm.sh) to provide an automated deployment and configuration experience for Pelorus. We are always doing work to cover more and more complex use cases with our helm charts. In order to be able to effectively contribute to these charts, you'll need a cluster that satisfies all of the installation prerequisites for Pelorus.

See the [Install guide](/docs/Install.md) for more details on that.
See the [Install guide](/page/Install.md) for more details on that.

Currently we have two charts:

1. The [operators](/charts/operators/) chart installs the community operators on which Pelorus depends.
1. The [operators](https://github.com/redhat-cop/pelorus/blob/master/charts/operators/) chart installs the community operators on which Pelorus depends.
* [Prometheus Operator](https://operatorhub.io/operator/prometheus)
* [Grafana Operator](https://operatorhub.io/operator/grafana-operator)
2. The [pelorus](charts/pelorus/) chart manages the Pelorus stack, which includes:
2. The [pelorus](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/) chart manages the Pelorus stack, which includes:
* Prometheus
* Thanos
* Grafana
* A set of Grafana Dashboards and Datasources
* The Pelorus exporters, managed in an [exporter](/charts/exporter) subchart.
* The Pelorus exporters, managed in an [exporter](https://github.com/redhat-cop/pelorus/blob/master/charts/pelorus/charts/exporters) subchart.

We use Helm's [chart-testing](https://github.com/helm/chart-testing) to ensure quality and consistency in the chart. When making updates to one of the charts, ensure that the chart still passes lint testing using `helm lint`. The most common linting failure is forgetting to bump the `version` field in the `Chart.yaml`. When updating the version, use the output of `git describe` to keep the versioning in line with the repo.

## Dashboard Development

We are continually doing work to enhance and bugfix the Pelorus dashboards. Doing so requires a complete Pelorus stack, including all exporters required to populate a given dashboard. See the [Dashboards](/docs/Dashboards.md) user guide for that information.
We are continually doing work to enhance and bugfix the Pelorus dashboards. Doing so requires a complete Pelorus stack, including all exporters required to populate a given dashboard. See the [Dashboards](/page/Dashboards.md) user guide for that information.

To effectively do dashboard development, you'll likely need at least two browser windows open, one with Grafana, and another with Prometheus for testing queries. Since our dashboards are imported to Grafana via the Grafana Operator, they get imported in read-only mode. Because of this, you'll need to make a copy of it for development purposes.

Expand All @@ -45,7 +45,7 @@ The following outlines a workflow for working on a dashboard:
1. Sign in to Grafana via the Grafana route.
1. Once signed in, sign as an administrator
1. Click the signin button in the bottom right corner
![Signin button](/media/signin.png)
![Signin button](img/signin.png)
1. The admin credentials can be pulled from the following commands:
```
oc get secrets -n pelorus grafana-admin-credentials -o jsonpath='{.data.GF_SECURITY_ADMIN_USER}' | base64 -d
Expand Down Expand Up @@ -122,7 +122,7 @@ Running an exporter on your local machine should follow this process:
pip install -r exporters/requirements.txt
1. Set any environment variables required (or desired) for the given exporter (see [Configuring Exporters](docs/Configuration.md#configuring-exporters) to see supported variables).
1. Set any environment variables required (or desired) for the given exporter (see [Configuring Exporters](/page/Configuration.md#configuring-exporters) to see supported variables).
1. Start the exporter
Expand Down Expand Up @@ -209,7 +209,7 @@ The following are notes and general steps for testing Pull Requests for specific
git fetch themoosman
git checkout themoosman/feature-branch
```
2. [Install Pelorus](/docs/Install.md) from checked out fork/branch.
2. [Install Pelorus](/page/Install.md) from checked out fork/branch.
>:mag: **Note**<br/>
>:mag: In most cases you can deploy changes to an existing deployment to retain existing data.
3. Log into Grafana via the grafana route.
Expand All @@ -230,15 +230,15 @@ Most exporter changes can be tested locally.
git fetch themoosman
git checkout themoosman/feature-branch
```
1. Gather necessary [configuration information](/docs/Configuration.md#configuring-exporters).
1. Gather necessary [configuration information](/page/Configuration.md#configuring-exporters).
1. [Run exporter localy](#running-locally). You can do this either via the command line, or use the provided [VSCode debug confuration](#ide-setup-vscode) to run it in your IDE Debugger.
1. Once exporter is running, you can test it via a simple `curl localhost:8080`. You should be validating that:
1. You get a valid response with metrics.
1. Confirm the format of expected metrics.
### Helm Install changes
For testing changes to the helm chart, you should just follow the [standard install process](/docs/Install.md), then verify that:
For testing changes to the helm chart, you should just follow the [standard install process](/page/Install.md), then verify that:
* All expected pods are running and healthy
* Any expected behavior changes mentioned in the PR can be observed.
Expand Down
Loading

0 comments on commit 19f976f

Please sign in to comment.