Skip to content

Commit

Permalink
chore: Update Dependencies (#9)
Browse files Browse the repository at this point in the history 
* Create .env

* chore: update readme
  • Loading branch information
@Wolftousen
Wolftousen authored Aug 28, 2024
1 parent 560871f commit 77cd7d7
Show file tree
Hide file tree
Showing 3 changed files with 166 additions and 118 deletions.
263 changes: 145 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,36 +12,43 @@ Our goal is to provide an Open Source plugin that works with the Open Telemetry

# Components

- DORA At A Glance - This is either a representation of each individual DORA Metric and how well you are doing or a trend graph depending on how you configure it

Metric View:
![Metrics](/screenshots/ranked/atAGlance.png?raw=true 'Metrics')

Overlall Trend View:
![Trend](/screenshots/trend/atAGlance.png?raw=true 'Trend')

Overall Trend View with Individual Metric Trends:
![Trend](/screenshots/trend/atAGlanceIndividual.png?raw=true 'Trend')

- DORA Charts - This is a set of charts that for the DORA metrics. It has the option of showing an individual components metrics, or an entire teams metrics

Component View with Metrics:
![Metrics](/screenshots/ranked/tab.png?raw=true 'Metrics')

Component View with Overall Trend:
![Trend](/screenshots/trend/tab.png?raw=true 'Trend')

Component View with Overall Trend and Individual Metric Trends:
![Trend](/screenshots/trend/tabIndividual.png?raw=true 'Trend')

Team View with Metrics:
![Metrics](/screenshots/ranked/teamView.png?raw=true 'Metrics')

Team View with Overall Trend:
![Trend](/screenshots/trend/teamView.png?raw=true 'Trend')

Team View with Overall Trend and Individual Metric Trends:
![Trend](/screenshots/trend/teamViewIndividual.png?raw=true 'Trend')
## `At A Glance`
This offers you a quick view of the state of a component or team.

Depending on how you have set up your configuration for this plugin, it will show:
- The individual DORA Metrics for the last 30 days
- `Deployment Frequency`- The average how often you are deploying, failed or successful
- Weekends, unless included, and holidays, if set, are subtracted from timespans that go over them
- `Change Lead Time` - The average of time merged to `main` to deployment success
- Weekends, unless included, and holidays, if set, are subtracted from timespans that go over them
- `Change Failure Rate` - The average number of changes that result in a failed deployment
- `Recovery Time` - The average of a failed deployment to the next successful deployment
- Regardless of configuration, includes weekends and does not subtract the holidays if set.
- The DORA Metrics overall trend over the last 30 days
- The Trend is calculated on a per week basis
- If a component has gone stale or is too new, you will see a note about there not being enough data to render a trend.
- There is an option to also show each DORA Metric as a line on the graph, a legend will appear in this case

Here are some examples:
| Metric View with Details Always Showing | Metric View with Details on Hover |
|-------------|-----|
| ![Metrics](/screenshots/ranked/atAGlance.png?raw=true 'Metrics') | ![Metrics](/screenshots/ranked/atAGlance_hover.png?raw=true 'Metrics') |

| Overall Trend View | Overall Trend View with Individual Metric Trends |
|-------------|-----|
| ![Trend](/screenshots/trend/atAGlance.png?raw=true 'Trend') | ![Trend](/screenshots/trend/atAGlanceIndividual.png?raw=true 'Trend') ||

## `Charts`
This is a set of charts that for the DORA metrics.

It has two different modes `Team View` and `Component View`:
- `Component View` - You will see this when you access a specific Component in the Catalog.
- `Team View` - You will see this when you access the `DORA Metrics` sidebar navigation.

Here are some examples:
| Component Metric View | Component Overall Trend View | Team Overall Trend View |
|-------------|------------|------------|
| ![Metrics](/screenshots/ranked/tab.png?raw=true 'Metrics') | ![Trend](/screenshots/trend/tab.png?raw=true 'Trend') | ![Trend](/screenshots/trend/teamView.png?raw=true 'Trend') |

# Dependencies

Expand All @@ -50,140 +57,160 @@ This plugin relies on the following dependencies:
- [Liatrio DORA React Components](https://github.com/liatrio/react-dora-charts)
- [Liatrio Otel Collector](https://github.com/liatrio/liatrio-otel-collector)
- An instance of Loki DB
- **You can swap out for any Time Series DB, but you will need to fork and modify the `Liatrio DORA API` to do so**
- **You can swap out for any Time Series DB, but you will need to fork and modify the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api) to do so**
- A GitHub Organization hosting your repositories
- **We will expand this to more platforms in the future**

# Installation of Dependencies

## Docker
## Docker Compose

In the `dependencies` folder, you will find a docker-compose file. Using this will spin up the following in docker containers:

TODO
- An instance of Loki DB with persistant storage
- An instance of Promtail, which is required by Loki DB
- An instance of an OTEL Collector configured to accept events from GitHub
- An instance of the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api), which this plugin can call to get the data it needs

You will need to update the `.env` file with your `GitHub Org`, `User` and `PAT` (with full repo access) for the API to be able to return a list of teams

## Kubernetes

If you have a Kubernetes Cluster, we have a quick start guide that installs `Loki DB` and `Liatrio OTEL Collector` (among a few other tools) that can be found [here](https://github.com/liatrio/tag-o11y-quick-start-manifests)
If you have a Kubernetes Cluster, we have a quick start guide that installs `Loki DB` and [Liatrio Otel Collector](https://github.com/liatrio/liatrio-otel-collector) (among a few other tools) that can be found [here](https://github.com/liatrio/tag-o11y-quick-start-manifests)

This quick start manifest does not set up the [Liatrio DORA API](https://github.com/liatrio/liatrio-dora-api) or any other API which you would need to sit between this plugin and the Loki DB.

## Congifuring GitHub

Once you have the dependencies configured and running, you will need to update your GitHub Organization to send events to the OTEL Collector.

You can do this by setting up a new `Webhook` and configuring the `Webhook` to send the following events:
- Deployments
- Issues
- Pull Requests
- Deployment Statuses

# Installation into BackStage

To Install this plugin you'll need to do the following:

1. Install the `backstage-dora-plugin` package into the `/packages/app` folder

```
npm install https://github.com/liatrio/backstage-dora-plugin/releases/download/v1.0.0/backstage-dora-plugin-v1.0.0.tgz
```
npm install https://github.com/liatrio/backstage-dora-plugin/releases/download/v1.0.0/backstage-dora-plugin-v1.0.0.tgz
yarn add backstage-dora-plugin@https://github.com/liatrio/backstage-dora-plugin/releases/download/v1.0.0/backstage-dora-plugin-v1.0.0.tgz
```
yarn add backstage-dora-plugin@https://github.com/liatrio/backstage-dora-plugin/releases/download/v1.0.0/backstage-dora-plugin-v1.0.0.tgz
```

2. Update the `/packages/app/src/App.tsx` file:

- Add this to your imports:
- Add this to your imports:

```
import { EntityDORACharts } from 'backstage-dora-plugin';
```
```
import { EntityDORACharts } from 'backstage-dora-plugin';
```

- Add this into the `FlatRoutes` element as a child:
- Add this into the `FlatRoutes` element as a child:

```
<Route path="/dora" element={<EntityDORACharts showTeamSelection />} />
```
```
<Route path="/dora" element={<EntityDORACharts showTeamSelection />} />
```

3. Update the `/packages/app/src/components/catalog/EntityPage.tsx` file:

- Add this to your imports:
- Add this to your imports:

```
import {
EntityDORACharts,
EntityDORAAtAGlance,
} from 'backstage-dora-plugin';
```
```
import {
EntityDORACharts,
EntityDORAAtAGlance,
} from 'backstage-dora-plugin';
```

- Define this constant:
- Define this constant:

```
const doraContent = (
<Grid container spacing={3} alignItems="stretch">
{entityWarningContent}
<EntityDORACharts showTeamSelection={false} />
</Grid>
);
```
```
const doraContent = (
<Grid container spacing={3} alignItems="stretch">
{entityWarningContent}
<EntityDORACharts showTeamSelection={false} />
</Grid>
);
```

- Add this into the `serviceEntityPage`, `websiteEntityPage`, `defaultEntityPage` `EntityLayoutWrapper` elements:
- Add this into the `serviceEntityPage`, `websiteEntityPage`, `defaultEntityPage` `EntityLayoutWrapper` elements:

```
<EntityLayout.Route path="/dora" title="DORA">
{doraContent}
</EntityLayout.Route>
```
```
<EntityLayout.Route path="/dora" title="DORA">
{doraContent}
</EntityLayout.Route>
```

- Add this into the `overviewContent` `Grid`:
- Add this into the `overviewContent` `Grid`:

```
<Grid item md={6}>
<EntityDORAAtAGlance />
</Grid>
```
```
<Grid item md={6}>
<EntityDORAAtAGlance />
</Grid>
```

4. Update the `app-config.yaml`:

- Add this to the `proxy.endpoints`:
- Add this to the `proxy.endpoints` and use the correct URL for your API:

```
/dora/api:
target: [URL_TO_DORA_API]
```

```
/dora/api:
target: [URL_TO_DORA_API]
```
- Add this root property `dora` to the file and then add the following under it:

- Add this root property `dora` to the file and then add the following under it:
- Required:

- Required:
- `dataEndpoint`: This the endpoint on the proxy that provides the deployment data. If you are using the `liatrio-dora-api` this will be `data`
- `teamListEndpiont`: This the endpoint on the proxy that provides the team and repo owndership data. If you are using the `liatrio-dora-api` this will be `teams`
- `daysToFetch`: This is the number of days worth of data that will be fetched for the charts to have available for display

- `dataEndpoint`: This the endpoint on the proxy that provides the deployment data. If you are using the `liatrio-dora-api` this will be `data`
- `teamListEndpiont`: This the endpoint on the proxy that provides the team and repo owndership data. If you are using the `liatrio-dora-api` this will be `teams`
- `daysToFetch`: This is the number of days worth of data that will be fetched for the charts to have available for display
- Optional:

- Optional:
- `showWeekends`: This boolean will toggle the `Deployment Frequency Chart` to hide weekends or show them. The default is to hide them.
- `includeWeekends`: This boolean will toggle whether weekends are included in scoring your `Deployment Frequency` and `Change Lead Time`. The default is to exclude them.
- `showDetails`: This boolean will toggle whether or not the `DORA At a Glance` shows the exact scores on hover or as static text. The default is to show them on hover.
- `showTrendGraph`: Enabling this field will change the `DORA At a Glance` to be a Trend Graph rather than have Metric indicators
- `showIndividualTrends`: Enabling this field will add individual Metric Trends to the Trend Graph in the `DORA At a Glance` component
- `rankThresholds`: This is an object to override the default rank thresholds for DORA Score Board and is fully optional all the way down to the individual ranks.

- `showWeekends`: This boolean will toggle the `Deployment Frequency Chart` to hide weekends or show them. The default is to hide them.
- `includeWeekends`: This boolean will toggle whether weekends are included in scoring your `Deployment Frequency` and `Change Lead Time`. The default is to exclude them.
- `showDetails`: This boolean will toggle whether or not the `DORA At a Glance` shows the exact scores on hover or as static text. The default is to show them on hover.
- `showTrendGraph`: Enabling this field will change the `DORA At a Glance` to be a Trend Graph rather than have Metric indicators
- `showIndividualTrends`: Enabling this field will add individual Metric Trends to the Trend Graph in the `DORA At a Glance` component
- `rankThresholds`: This is an object to override the default rank thresholds for DORA Score Board and is fully optional all the way down to the individual ranks.
There are 4 scores, all are optional:

There are 4 scores, all are optional:
- `deployment_frequency` measured in hours
- `change_lead_time` measured in hours
- `change_failure_rate` measured as a percentage
- `recover_time` measured in hours

- `deployment_frequency` measured in hours
- `change_lead_time` measured in hours
- `change_failure_rate` measured as a percentage
- `recover_time` measured in hours
Each score has the following rank options:

Each score has the following rank options:
- `elite`
- `high`
- `medium`

- `elite`
- `high`
- `medium`
**Note: Anything outside `medium` is considered `low`**

**Note: Anything outside `medium` is considered `low`**

The default rank thresholds are:
The default rank thresholds are:

- deployment_frequency
- elite: 24 (1 day or less)
- high: 168 (1 week or less)
- medium: 720 (1 month or less)
- change_lead_time
- elite: 24 (1 day or less)
- high: 168 (1 week or less)
- medium: 720 (1 month or less)
- change_failure_rate
- elite: 5
- high: 10
- medium: 45
- recover_time
- elite: 1 (1 hr or less)
- high: 24 (1 day or less)
- medium: 168 (1 week or less)
- deployment_frequency
- elite: 24 (1 day or less)
- high: 168 (1 week or less)
- medium: 720 (1 month or less)
- change_lead_time
- elite: 24 (1 day or less)
- high: 168 (1 week or less)
- medium: 720 (1 month or less)
- change_failure_rate
- elite: 5
- high: 10
- medium: 45
- recover_time
- elite: 1 (1 hr or less)
- high: 24 (1 day or less)
- medium: 168 (1 week or less)
21 changes: 21 additions & 0 deletions dependencies/.env
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
LOKI_URL="http://loki:3100/loki/api/v1/query_range"

# LOG_LEVEL=warn

PORT=3030

GITHUB_ORG=
GITHUB_USER=
GITHUB_TOKEN=

LOKI_DAYS_BATCH_SIZE=5

OTEL_COLLECTOR_HOST=otelcol
OTEL_COLLECTOR_PORT_GRPC=4317
OTEL_COLLECTOR_PORT_HTTP=4318
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

OTEL_RESOURCE_ATTRIBUTES=service.name=backstage,service.version=1.0,deployment.environment=local
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative
Binary file added screenshots/ranked/atAGlance_hover.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 77cd7d7

Please sign in to comment.