Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/google-marketing-solutions/ads-monitor
Comprehensive system for monitoring changes and fluctuations in Google Ads
https://github.com/google-marketing-solutions/ads-monitor
alertmanager google-ads-api grafana prometheus
Last synced: about 2 months ago
JSON representation
Comprehensive system for monitoring changes and fluctuations in Google Ads
- Host: GitHub
- URL: https://github.com/google-marketing-solutions/ads-monitor
- Owner: google-marketing-solutions
- License: apache-2.0
- Created: 2023-08-01T08:23:30.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-25T14:12:57.000Z (about 2 months ago)
- Last Synced: 2024-11-25T15:24:24.599Z (about 2 months ago)
- Topics: alertmanager, google-ads-api, grafana, prometheus
- Language: Python
- Homepage:
- Size: 355 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Ads Monitor
## Problem statement
Well defined monitoring in Ads allows users quickly respond to any unexpected
fluctuation in the accounts. But monitoring Ads in smaller time increments (i.e.
every 15 minutes) to identify any problems in performance or approvals can be
time consuming and error-prone.
## Solution
Ads Monitor provides a way to expose a set of custom defined Ads metrics and
dimensions in a Prometheus format which make it possible to reuse widely
available monitoring and alerting tool (i.e. Grafana and Alertmanager) to setup
a solid monitoring environment for your crucial Ads metrics and dimensions.
## Deliverable (implementation)
Ads Monitor provides you with a Grafana dashboard and a set of default [alerts](prometheus/alerts.yml).
Data that powers the dashboard and alerts are extracted from Google Ads API and
stored in a Prometheus.
## Deployment
### Prerequisites
* Google Ads API access and [google-ads.yaml](https://github.com/google/ads-api-report-fetcher/blob/main/docs/how-to-authenticate-ads-api.md#setting-up-using-google-adsyaml) file - follow documentation on [API authentication](https://github.com/google/ads-api-report-fetcher/blob/main/docs/how-to-authenticate-ads-api.md).
* (Optional) `prometheus.yml` file configured. Learn more at [how to configure Prometheus](docs/how-to-configure-prometheus.md).
* (Optional) [Docker Compose](https://docs.docker.com/compose/install/) installed.
### Installation
The easiest way to try the solution is to run it via [Docker Compose](https://docs.docker.com/compose/install/).
1. expose environmental variables `GOOGLE_ADS_YAML` and `GAARF_EXPORTER_ACCOUNT_ID`:
```
export GOOGLE_ADS_YAML=/path/to/google-ads.yaml
export GAARF_EXPORTER_ACCOUNT_ID=
```
> If you don't specify the environmental variable Ads Monitor will be expecting `google-ads.yaml` file in your $HOME directory.
3. start the containers:
```
docker compose up
```
This command will build `gaarf_exporter` image and start scraping Google Ads every 15 minutes,
pull latest images of Prometheus, AlertManager and Grafana.
#### Manual installation
You can build and run `gaarf_exporter` container on your own.
1. Build `gaarf_exporter` container:
```
cd gaarf_exporter
docker build -t gaarf_exporter .
```
2. Run `gaarf_exporter` container:
```
docker run --network=host \
-v /path/to/google-ads.yaml:/google-ads.yaml \
gaarf_exporter
```
`gaarf_exporter` expected these files to be mapped into containers:
* `google-ads.yaml` - file that contains authentication details to connect to Google Ads API.
> Change `--network=host` to the network where your Prometheus instance is running.
`gaarf_exporter` will push expose metrics on `localhost:8000` so they can later be scraped by Prometheus.
##### Skipping or including particular queries
When running `gaarf_exporter` you can specify which data to get from Google Ads.
The exporter some with a lot of built-in [collectors](gaarf_exporter/README.md#collectors)
you can specify by adding with `--collectors ` CLI argument.
```
docker run --network=host \
-v /path/to/google-ads.yaml:/google-ads.yaml \
gaarf_exporter --collectors app,disapprovals
```
Alternatively you can pass an `--config` argument `gaarf_exporter`
> `--config` always has priority over `--collectors` flag.
```
docker run --network=host \
-v /path/to/google-ads.yaml:/google-ads.yaml \
-v /path/to/gaarf_exporter.yaml:/app/gaarf_exporter.yaml \
gaarf_exporter --config /app/gaarf_exporter.yaml
```
### Usage
#### Creating Grafana dashboard
Once the metrics are scraped by Prometheus you can open Grafana
(usually located at `http://localhost:3000`):
1. Create [Prometheus datasource](https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source)
2. [Import dashboard](https://grafana.com/docs/grafana/latest/dashboards/manage-dashboards/#import-a-dashboard) by copying content of `dashboard.json` located in `grafana` folder.
3. Associate Prometheus datasource with in an imported dashboard with the created Prometheus datasource on step 1.
#### Configuring Alertmanager
[Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) is responsible for sending alerts to various receivers (email, Slack, Telegram, etc).
To configure Alertmanager to send updates to Slack open `alertmanager/alertmanager.yml` and under `receivers` section add the following block:
```
- name: slack
api_url: https://hooks.slack.com/services/XXXXXXXX/XXXXX/XXXXXXXX
slack_configs:
- channel: "#your-slack-channel"
```
Please refer to Alertmanager [documentation](https://prometheus.io/docs/alerting/latest/configuration/)
for additional configuration opportunities.
## Disclaimer
This is not an officially supported Google product.