https://github.com/tfadeyi/auth0-simple-exporter
Simple Prometheus exporter for Auth0 log events
https://github.com/tfadeyi/auth0-simple-exporter
auth0 metrics monitoring observability prometheus prometheus-exporter
Last synced: 9 months ago
JSON representation
Simple Prometheus exporter for Auth0 log events
- Host: GitHub
- URL: https://github.com/tfadeyi/auth0-simple-exporter
- Owner: tfadeyi
- License: apache-2.0
- Created: 2023-03-12T00:30:58.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T08:42:59.000Z (about 2 years ago)
- Last Synced: 2024-05-23T09:44:46.240Z (about 2 years ago)
- Topics: auth0, metrics, monitoring, observability, prometheus, prometheus-exporter
- Language: Go
- Homepage:
- Size: 1.29 MB
- Stars: 15
- Watchers: 1
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Auth0 Exporter
[](https://github.com/tfadeyi/auth0-simple-exporter/actions/workflows/ci.yml)
[](https://github.com/tfadeyi/auth0-simple-exporter/blob/main/LICENSE)
[](https://github.com/tfadeyi/auth0-simple-exporter)
[](https://github.com/tfadeyi/auth0-simple-exporter/releases)
[](https://github.com/tfadeyi/auth0-simple-exporter)
[](https://goreportcard.com/report/github.com/tfadeyi/auth0-simple-exporter)
**Installation**
·
**Usage**
·
**Metrics**
·
**Report Bug**
---
A simple Prometheus exporter for [Auth0](https://auth0.com/) log [events](https://auth0.com/docs/api/management/v2#!/Logs/get_logs),
which allows you to collect metrics from Auth0 and expose them in a format that can be consumed by Prometheus.
## Motivation
It can be difficult to monitor **Auth0** tenant events on a Prometheus stack,
especially compared to other monitoring systems such as Datadog.
This Prometheus exporter aims to simplify this, making it easier to expose tenant events.
## Prerequisites
* [Auth0](https://auth0.com/) account.
* Auth0 tenant [management API](https://auth0.com/docs/api#management-api) client credentials.
* Required Grants: `read:users` or `read:user_idp_tokens`,`read:clients` or `read:client_keys`,`read:logs`
* *(Optional)* Auth0 tenant management API [static token](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens).
## Super TL;DR
If you just want to try the exporter locally without installation, you can do so by using Nix.
```shell
nix run github:tfadeyi/auth0-simple-exporter export -- --tls.disabled
```
## TL;DR
The quickest way to install the exporter is through Helm, make sure you have your Auth0 credentials at hand.
```shell
export TOKEN="< auth0 management API static static token >"
export DOMAIN="< auth0 tenant domain >"
```
```shell
# Installing by passing in secret directly
helm repo add auth0-exporter https://tfadeyi.github.io/auth0-simple-exporter
helm upgrade prod auth0-exporter/auth0-exporter --install --create-namespace -n auth0-exporter \
--set auth0.domain="$DOMAIN" --set auth0.token="$TOKEN" --set exporter.tls.disabled=true
```
This will install the exporter running with TLS disabled.
## Installation
* ### Download Pre-built Binaries
Binaries can be downloaded from [Releases](https://github.com/tfadeyi/auth0-simple-exporter/releases) page.
* Download and run exporter's binary with TLS disabled.
```shell
export TOKEN="< auth0 management API static static token >"
export DOMAIN="< auth0 tenant domain >"
curl -LJO https://github.com/tfadeyi/auth0-simple-exporter/releases/download/v0.0.2/auth0-simple-exporter-linux-amd64.tar.gz && \
tar -xzvf auth0-simple-exporter-linux-amd64.tar.gz && \
cd auth0-simple-exporter-linux-amd64
./auth0-simple-exporter export --tls.disabled
```
* ### Docker
The recommended way to get the Docker Image is to pull the prebuilt image from the project's Github Container Registry.
```shell
$ docker pull ghcr.io/tfadeyi/auth0-simple-exporter:latest
```
To use a specific version, you can pull a versioned tag.
```shell
$ docker pull ghcr.io/tfadeyi/auth0-simple-exporter:[TAG]
```
* ### Docker compose
To integrate the exporter with Docker Compose, follow these steps:
- Create a ```.env``` file (ideally named to match the tenant, e.g., .env.tenant1) and define the following variables:
```
TOKEN=< auth0 management API static static token >
DOMAIN=< auth0 tenant domain >"
CLIENT_SECRET=
CLIENT_ID=
```
- Update your ```docker-compose.yaml``` file to include the exporter as a service. Below is an example configuration for a single exporter setup:
```
services:
metric-exporter:
image: ghcr.io/tfadeyi/auth0-simple-exporter:latest
container_name: metric-exporter
env_file:
- .env.tenant1
command: export --tls.disabled
ports:
- "9301:9301"
```
- For a multi-tenant setup, you can configure multiple exporter services pointing to different ```.env``` files:
```
services:
metric-exporter:
image: ghcr.io/tfadeyi/auth0-simple-exporter:latest
container_name: metric-exporter
env_file:
- .env
command: export --tls.disabled
ports:
- "9301:9301"
metric-exporter2:
image: ghcr.io/tfadeyi/auth0-simple-exporter:latest
container_name: metric-exporter2
env_file:
- .env.tenant1
command: export --tls.disabled
ports:
- "9302:9301"
```
- Configure Prometheus to scrape metrics from the exporters. Below is an example ```prometheus.yaml``` configuration (this assumes you are running Prometheus in the same docker network as the exporter):
```
- job_name: auth0_exporter1
metrics_path: /metrics
static_configs:
- targets: ['metric-exporter:9301']
relabel_configs:
- source_labels: [ __address__ ]
target_label: __param_target
- source_labels: [ __param_target ]
target_label: instance
- target_label: __address__
replacement: metric-exporter:9301
- job_name: auth0_exporter2
metrics_path: /metrics
static_configs:
- targets: ['metric-exporter2:9302']
relabel_configs:
- source_labels: [ __address__ ]
target_label: __param_target
- source_labels: [ __param_target ]
target_label: instance
- target_label: __address__
replacement: metric-exporter2:9302
```
* ### Helm
This shows a simple installation of the exporter helm chart, running with TLS disabled.
```shell
export TOKEN="< auth0 management API static static token >"
export DOMAIN="< auth0 tenant domain >"
```
```shell
# Installing by passing in secret directly
helm repo add auth0-exporter https://tfadeyi.github.io/auth0-simple-exporter
helm upgrade --install --create-namespace -n auth0-exporter auth0-exporter/auth0-exporter \
--set auth0.domain="$DOMAIN" --set auth0.token="$TOKEN" \
--set exporter.tls.disabled=true
```
More info on the helm deployment can be found [here](deploy/charts/auth0-exporter/README.md).
* ### Build from source
From the repository root directory run:
```shell
make build
# or for multiple systems
make build-all-platforms
```
* ### Nix
The exporter can be used via Nix.
```shell
nix run github:tfadeyi/auth0-simple-exporter export -- --tls.disabled
```
* ### Octopus Deploy
You can use `Octopus Deploy` to the deploy the exporter to your cluster.
Simply add the following as the Feed URL.
```text
https://tfadeyi.github.io/auth0-simple-exporter
```
## Usage
```
Usage:
exporter export [flags]
Flags:
--auth0.client-id string Auth0 management api client-id.
--auth0.client-secret string Auth0 management api client-secret.
--auth0.domain string Auth0 tenant's domain. (i.e: .eu.auth0.com).
--auth0.from string Point in time from were to start fetching auth0 logs. (format: RFC3339) (default Now)
--auth0.token string Auth0 management api static token. (the token can be used instead of client credentials).
-h, --help help for export
--log.level string Exporter log level (debug, info, warn, error). (default "warn")
--namespace string Exporter's namespace.
--pprof.enabled Enabled pprof profiling on the exporter on port :6060. (help: https://jvns.ca/blog/2017/09/24/profiling-go-with-pprof/).
--pprof.listen-address int Port where the pprof webserver will listen on. (default 6060)
--probe.listen-address int Port where the probe webserver will listen on. (default 8081)
--probe.path string URL Path under which to expose the probe metrics. (default "probe")
--subsystem string Exporter's subsystem.
--tls.auto Allow the exporter to use autocert to renew its certificates with letsencrypt.
(Can only be used if the exporter is publicly accessible by the internet)
--tls.cert-file string Path to the PEM encoded certificate for the auth0-exporter metrics to serve.
--tls.disabled Run exporter without TLS. TLS is enabled by default.
--tls.hosts strings The different allowed hosts for the exporter. Only works when --tls.auto has been enabled.
--tls.key-file string Path to the PEM encoded key for the auth0-exporter metrics server.
--web.listen-address int Port where the exporter webserver will listen on. (default 8080)
--web.path string URL Path under which to expose the collected auth0 metrics. (default "metrics")
```
### Environment variables:
* ***TOKEN***, Auth0 management API static token.
* ***DOMAIN***, Auth0 tenant domain.
* ***CLIENT_SECRET***, Auth0 management API client-secret, (not required if setting the token).
* ***CLIENT_ID***, Auth0 management API client-id, (not required if setting the token).
## Example queries
Monitor the percentage of failed logins in the Auth0 tenant:
```
(tenant_failed_login_operations_total / tenant_login_operations_total) * 100
```
Monitor the number current logged-in users for a client application in Auth0 tenant:
```
(tenant_login_operations_total{client="ChatGPT"} - tenant_failed_login_operations_total{client="ChatGPT"}) - (tenant_logout_operations_total{client="ChatGPT"} - tenant_failed_logout_operations_total{client="ChatGPT"})
```
## Metrics
### Signup
| Metric | Meaning | Labels |
|------------------------------------------|-----------------------------------------------------|--------|
| `tenant_sign_up_operations_total` | The total number of signup operations. | client |
| `tenant_failed_sign_up_operations_total` | The number of failed signup operations. (codes: fs) | client |
### Login
| Metric | Meaning | Labels |
|----------------------------------------|---------------------------------------------------------|--------|
| `tenant_login_operations_total` | The total number of login operations. | client |
| `tenant_failed_login_operations_total` | The number of failed login operations. (codes: f,fp,fu) | client |
### Logout
| Metric | Meaning | Labels |
|-----------------------------------------|------------------------------------------------------|--------|
| `tenant_logout_operations_total` | The total number of logout operations. | client |
| `tenant_failed_logout_operations_total` | The number of failed logout operations. (codes: flo) | client |
**The other exposed metrics can be found [here](./docs/metrics.md).**
## Known Issues
* ### API Rate Limits
When the Prometheus scraping job interval is too frequent the exporter might encounter api-rate limit from Auth0.
To mitigate this try increasing the scraping interval for the job.
* ### Not all logs/events are available
Currently, not all logs/events from Auth0 are exposed, if a metric is not exposed, feel free to open a feature request.
## Prometheus
Example Prometheus configuration for the exporter. Replace `AUTH0-EXPORTER-HOSTNAME` with your instance's hostname.
```yaml
scrape_configs:
- job_name: auth0_exporter
metrics_path: /metrics
static_configs:
- targets: ['<>:9301']
relabel_configs:
- source_labels: [ __address__ ]
target_label: __param_target
- source_labels: [ __param_target ]
target_label: instance
- target_label: __address__
replacement: <>:9301
```
## Development
#### Makefile
Similar to other Golang projects, this projects makes use of make for building and testing the source code.
#### Nix
Before start development, add your tenant's Auth0 credentials to the `env-dev.sh`, this help when developing using Nix.
Once the credentials are added, you can start the development environment by:
```shell
$ source env-dev.sh
$ develop
```
This will boot up a Nix devshell with the need tools and information.
## Contributing
**Everyone** is welcome to contribute to the project.
Please see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for information on how to get started.
Feedback is always appreciated, whether it's a bug or feature request, feel free to open an issue using one of the templates.
## License
Apache 2.0, see [LICENSE.md](./LICENSE).