Skip to content
This repository has been archived by the owner on Sep 18, 2024. It is now read-only.

Commit

Permalink
[Task]: Document the new steps for the analytics local database import (
Browse files Browse the repository at this point in the history
#113)

## Summary
Fixes #100 

### Time to review: __1 mins__

## Changes proposed
* Added documentation about local database import

## Context for reviewers

> The current analytics documentation is focused on the slack
integration. This task is to add the work from
#84 to the
documentation and include the local Metabase steps.

## Additional information
> Screenshots, GIF demos, code examples or output to help show the
changes working as expected.
  • Loading branch information
aplybeah authored Jul 1, 2024
1 parent cbccbed commit fd0b498
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 0 deletions.
Binary file added analytics/static/screenshot-metabase-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 36 additions & 0 deletions documentation/analytics/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ It should also open two new browser tabs, each with a separate report:
- `make sprint-burndown` - Runs the sprint burndown report
- `make percent-complete` - Runs the percent complete by deliverable report
- `make sprint-reports` - Runs both percent complete and sprint burndown (without exporting data first)
- `make gh-db-data-import` - Imports issue and sprint data to the analytics database

## Using the command line interface

Expand Down Expand Up @@ -96,6 +97,41 @@ Exporting project data works almost the same way, except it expects a `--project
poetry run analytics export gh_project_data --owner HHS --project 13 --output-file data/sprint-data.json
```

### Working with the Analytics database

The following sections assume that the steps in our [development guide](development.md) have been completed first. This is especially helpful when seeding the database for local testing and development. Additionally, you will need to have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed.

#### Importing Github data

You can use the following command to import data to the analytics database.

```bash
poetry run analytics import db_import --sprint-file data/sprint-data.json --issue-file data/issue-data.json
```

Some notes about this command:
- `--sprint-file` and `--issue-file` refer to the files generated by their respective commands (e.g. `gh_issue_data `). When running the import command via `make` these flags are prepopulated with the relative paths: `data/issue-data.json` and `data/sprint-data.json`.

The data from this command can be found in the `github_project_data` table.

#### Viewing the data in the Terminal

The database can be accessed locally by running the command `docker-compose up -d`. This will start the docker containers for Metabase and the analytics database in a detatched state.

In Docker desktop, navigate to the analytics database container and sign into the database `psql -U <database-user>`. From here, you can run SQL queries to view data.

When finished, run `docker-compose down` to stop and remove all containers, networks and volumes associated with the analytics application.

#### Viewing the data in Metabase

[Metabase](https://www.metabase.com/) is a buisness intelligence that lets you query, organize and view data with a friendly UX. In order to view data in Metabase, start the containers and then navigate to http://localhost:3100/.

The first time you access Metabase you will be guided through a small setup process to sync the database to the platform.

![Screenshot of the landing page in Metabase](../../analytics/static/screenshot-metabase-page.png)

![Screenshot of a row of test data](../../analytics/static/screenshot-metabase-row-data.png)

### Calculating metrics

#### Calculating sprint burndown
Expand Down

0 comments on commit fd0b498

Please sign in to comment.