Getting Started
To get started pull the latest image from our package repository
and after setting the minimal configuration
deploy it on your infrastructure of choice. The application will expose all
metrics on the /actuator/prometheus endpoint.
Authentication
To be able to make requests to the Github Api on your behalf Github Metrics uses
Github Apps. The AuthApp Github Metrics
has the correct privileges to only access the nessesary data. To use it simply install it
on your organization and generate a private key which is then used to set the
APP_GITHUB_APPLICATION_PEM env variable.
| environment variables | description |
|---|---|
| APP_GITHUB_APPLICATION_ID | The ID of the Github App installed for authorizing the Api calls made by Github Metics (In the case of `AuthApp Github Metrics` is: **882159**) |
| APP_GITHUB_APPLICATION_INSTALL_ID |
The id of the installation of the above mentioned Github App.
Can be retrived from the url when visiting https://github.com/organizations/<your-org>/settings/installations
and then clicking on Configure for AuthApp Github Metrics
|
| APP_GITHUB_APPLICATION_PEM |
A private key generated through the installation of the Github
App. This environement variable is just the whole pem
string provided by Github. For more information on how to create
this Github App check out the github authentication
page.
|
Github Metrics will only request the repositories that you give the app the access to. Any other repositories that are not added in the Apps list will be completly ignored.
Configuration
After setting the minimal configuration the application should start running without problems. If you are interested in tuning the service to work better for specialized needs there are a number of environment variables that can be set to change the behaviour of the service. Before getting into the list please consider that some understanding of the inner workings of the service is required. You can find details on the architecture page.
The two main things that can be configured are the exporting schedule as well as the cache eviction. For the exporting shedule you can find a list of the things to configure here.
As for the Cache eviction the configuration is more important and not as simple.
The cache eviction schedule can be configured, determining how often new data
is fetched but then you can also determine at what status level the rate limiter
will decide to completly stop fetching new data. For this set the <your-metric>..STOP_EVICTION_STATUS
to one of the following:
"CRITICAL", "WARNING", "CONCERNING", "GOOD", "OK", ""
Grafana
Grafana is a great tool for visualizing time series data so is a perfect solution to display the data generated by this service. If you are planning on also using Grafana to visualize your data we provide a few example json exports as well as some great example dashboards that you can copy from as you wish a public dashboard to explore different ways of visualizing the data our serivce provides.
Deployment Example
For deploying Github Metrics we decided to use Grafana Cloud which had a few influences on the final deployment of the service. Normally prometheus is based on a pull model where prometheus pulls your data but when using Grafana Cloud you have to be the one to push to it, meaning a push model. Since we didn't want to change the service itself we decided to add Grafana Alloy as a sidecar to serve as both the one pulling from our service and pushing to Grafana Cloud.
This in between actor did add some latency concerns since the scrape interval can, in the worst case add a whole scrape interval time to the latency. (In our case 10s)
