Skip to content

doc: Add usage documentation #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
darthfork merged 1 commit into from
Nov 4, 2024
Merged

doc: Add usage documentation #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,9 @@ test:
lint: ## Run linter
@golangci-lint run

fmt: ## Format golang source files
@go fmt ./...

coverage: ## Run unit tests with coverage
@go test -cover -v $(SRC) -coverprofile=coverage.out
@go tool cover -html=coverage.out
Expand All @@ -68,8 +71,5 @@ release: push-container cross-platform
--generate-notes\
$(BUILDDIR)/*

fmt: ## Format golang source files
@go fmt ./...

clean: ## Clean build directory
@rm -rf $(BUILDDIR)
134 changes: 26 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,114 +1,32 @@
# promgithub Service
# Github Prometheus Exporter (promgithub)

The `promgithub` service is a lightweight tool designed to receive and process GitHub webhook events, such as commits, pull requests, and workflow runs. It exports metrics to Prometheus, allowing you to monitor and gain insights into your GitHub activities in a straightforward manner. This service is ideal for integrating GitHub events into your observability stack, making it easier to track CI/CD workflows, job durations, and more.
The `promgithub` service is a lightweight service designed to receive and process GitHub webhook events (commits, pull requests, workflow jobs and workflow runs). The webhook events are converted to prometheus metrics, allowing monitoring and insights into GitHub activities.

## Metrics Exported by the Service

The `promgithub` service exports the following Prometheus metrics:

- **promgithub_workflow_status**:

- Type: Counter
- Description: Total number of workflow runs with status
- Labels: `repository`, `branch`, `workflow_name`, `workflow_status`, `conclusion`

- **promgithub_workflow_duration**:

- Type: Histogram
- Description: Duration of workflow runs
- Labels: `repository`, `branch`, `workflow_name`, `workflow_status`, `conclusion`

- **promgithub_workflow_queued**:

- Type: Gauge
- Description: Number of workflow runs queued
- Labels: `repository`, `branch`, `workflow_name`

- **promgithub_workflow_in_progress**:

- Type: Gauge
- Description: Number of workflow runs in progress
- Labels: `repository`, `branch`, `workflow_name`

- **promgithub_workflow_completed**:

- Type: Gauge
- Description: Number of workflow runs completed
- Labels: `repository`, `branch`, `workflow_name`

- **promgithub_job_status**:

- Type: Counter
- Description: Total number of jobs with status
- Labels: `runner`, `repository`, `branch`, `workflow_name`, `job_name`, `job_status`, `job_conclusion`

- **promgithub_job_duration**:

- Type: Histogram
- Description: Duration of jobs runs in seconds
- Labels: `runner`, `repository`, `branch`, `workflow_name`, `job_name`, `job_status`, `job_conclusion`

- **promgithub_job_queued**:

- Type: Gauge
- Description: Number of jobs queued
- Labels: `runner`, `repository`, `branch`, `workflow_name`, `job_name`

- **promgithub_job_in_progress**:

- Type: Gauge
- Description: Number of jobs in progress
- Labels: `runner`, `repository`, `branch`, `workflow_name`, `job_name`

- **promgithub_job_completed**:

- Type: Gauge
- Description: Number of jobs completed
- Labels: `runner`, `repository`, `branch`, `workflow_name`, `job_name`

- **promgithub_commit_pushed**:

- Type: Counter
- Description: Total number of commits pushed
- Labels: `repository`, `branch`, `commit_author`, `commit_author_email`

- **promgithub_pull_request**:

- Type: Counter
- Description: Total number of pull requests
- Labels: `repository`, `base_branch`, `head_branch`, `pull_request_author`, `pull_request_author_email`, `pull_request_status`

- promgithub_api_calls_total:

- Type: Counter
- Description: Number of API calls
- Labels: `status`, `method`, `path`

- **promgithub_request_duration_seconds**:

- Type: Histogram
- Description: Request duration in seconds
- Labels: `path`, `method`

## How to Use This Service

### Setting up the Webhook in GitHub (Repository/Organization)

1. Navigate to your GitHub repository or organization settings.
2. Under **Settings**, find **Webhooks** and click **Add webhook**.
3. Enter the payload URL pointing to your `promgithub` service, e.g., `http://<your-service-url>/webhook`.
4. Set the **Content type** to `application/json`.
5. Add the **Secret**: Use the value of `PROMGITHUB_WEBHOOK_SECRET`.
6. Select the events to trigger the webhook:
- You can select **Just the push event** or **Send me everything**, depending on your needs.
7. Click **Add webhook** to save.

### Requirements to Run the Service

- **Redis**: The service uses Redis for caching metrics. Ensure you have a Redis instance available and reachable by the service.

### Required Parameters

- **Environment Variables**:
- `PROMGITHUB_WEBHOOK_SECRET`: The secret used to validate incoming GitHub webhook requests.
- `PROMGITHUB_SERVICE_PORT` (optional): The port to listen on (default is `8080`).
| Name | Type | Labels | Description |
|------------------------------------|-----------|------------------------------------------------------------------------------------------|-----------------------------------------|
| `promgithub_workflow_status` | Counter | `repository`, `branch`, `workflow_name`, `workflow_status`, `conclusion` | Total number of workflow runs with status |
| `promgithub_workflow_duration` | Histogram | `repository`, `branch`, `workflow_name`, `workflow_status`, `conclusion` | Duration of workflow runs |
| `promgithub_workflow_queued` | Gauge | `repository`, `branch`, `workflow_name` | Number of workflow runs queued |
| `promgithub_workflow_in_progress` | Gauge | `repository`, `branch`, `workflow_name` | Number of workflow runs in progress |
| `promgithub_workflow_completed` | Gauge | `repository`, `branch`, `workflow_name` | Number of workflow runs completed |
| `promgithub_job_status` | Counter | `runner`, `repository`, `branch`, `workflow_name`, `job_name`, `job_status`, `job_conclusion` | Total number of jobs with status |
| `promgithub_job_duration` | Histogram | `runner`, `repository`, `branch`, `workflow_name`, `job_name`, `job_status`, `job_conclusion` | Duration of jobs runs in seconds |
| `promgithub_job_queued` | Gauge | `runner`, `repository`, `branch`, `workflow_name`, `job_name` | Number of jobs queued |
| `promgithub_job_in_progress` | Gauge | `runner`, `repository`, `branch`, `workflow_name`, `job_name` | Number of jobs in progress |
| `promgithub_job_completed` | Gauge | `runner`, `repository`, `branch`, `workflow_name`, `job_name` | Number of jobs completed |
| `promgithub_commit_pushed` | Counter | `repository`, `branch`, `commit_author`, `commit_author_email` | Total number of commits pushed |
| `promgithub_pull_request` | Counter | `repository`, `base_branch`, `head_branch`, `pull_request_author`, `pull_request_author_email`, `pull_request_status` | Total number of pull requests |
| `promgithub_api_calls_total` | Counter | `status`, `method`, `path` | Number of API calls |
| `promgithub_request_duration_seconds` | Histogram | `path`, `method` | Request duration in seconds |

## Using `promgithub` service

For usage information see [Usage documentation](./docs/usage.md)

## Contributing to `promgithub` service

For contributing guidelines see [Contributing documentation](./docs/contributing.md)
3 changes: 3 additions & 0 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Contributing to `promgithub`

**TODO**
78 changes: 78 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Using `promgithub` service

## Deploying the service

The service can be deployed in your choice of infrastructure

### Deploying in kubernetes

To deploy the service in a kubernetes cluster you can use the provided helm chart.

**TODO:** Add helm chart details

## Deploying service in a container

To deploy the service in a container using a container management environment like fargate/docker-compose, you can use the `promgithub` container from the [GHCR container repository](https://github.com/darthfork/promgithub/pkgs/container/promgithub)

## Deploying service binary

The service binaries are also available under [github releases](https://github.com/darthfork/promgithub/releases) which can be deployed as the user wishes.


### Service Parameters

The service expects the following parameters to be set:

- **Environment Variables**:
- `PROMGITHUB_WEBHOOK_SECRET`: The secret used to validate incoming GitHub webhook requests.
- `PROMGITHUB_SERVICE_PORT` (optional): Service API port (default is `8080`).

## Setting up the Webhook in GitHub (Repository/Organization)

1. Navigate to your GitHub repository or organization settings.
2. Under **Settings**, find **Webhooks** and click **Add webhook**.
3. Enter the payload URL pointing to your `promgithub` service, e.g., `http://<your-service-url>/webhook`.
4. Set the **Content type** to `application/json`.
5. Add the **Secret**: Use the value of `PROMGITHUB_WEBHOOK_SECRET`.
6. Select the following events to trigger the webhook:
- **push**
- **pull request**
- **workflow job**
- **workflow runs**
7. Click **Add webhook** to save.

## Prometheus scraping configuration

Configure prometheus to scrape `promgithub`'s `/metrics` endpoint to extract metrics

### Prometheus configuration

To allow prometheus to scrape `promgithub`'s `/metrics` endpoint, add the following configuration to your prometheus setup:

```yaml
scrape_configs:
- job_name: 'promgithub'
scrape_interval: 15s
metrics_path: '/metrics'
static_configs:
- targets: ['promgithub:8080']
labels:
service: 'promgithub'
```

### VictoriaMetrics configuration

If you use victoria-metrics as your metrics provider, add a `vmservicescrape` configuration to your `promgithub` chart deployment

```yaml
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMServiceScrape
metadata:
name: promgithub
namespace: promgithub
spec:
endpoints:
- path: /metrics
interval: 15s
port: http
```