deltacodepl / ads-monitor

Comprehensive system for monitoring changes and fluctuations in Google Ads

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. Data that powers the dashboard and alerts are extracted from Google Ads API and stored in a Prometheus. --collectors app,disapprovals --collectors app,disapprovals

Deployment

Prerequisites

• Google Ads API access and google-ads.yaml file - follow documentation on API authentication.
• (Optional) prometheus.yml file configured. Learn more at how to configure Prometheus.
• (Optional) Docker Compose installed.

Deploy to VM

Installation

The easiest way to try the solution is to run it via Docker Compose.

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=<YOUR_MCC_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:/root/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 you can specify by adding with --collectors <collector_name> CLI argument.

docker run --network=host \
  -v /path/to/google-ads.yaml:/root/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:/root/google-ads.yaml \
  -v /path/to/gaarf_exporter.yaml:/app/gaarf_exporter.yaml \
  gaarf_exporter --config /app/gaarf-exporter.yaml

There are two CLI flags that can help fine-tuning which queries from config file should be run:

• --queries.include - comma-separated query names (i.e. performance,search_terms) that will be taken from gaarf_exporter.yaml for fetching.
• --queries.exclude - comma-separated query names (i.e. performance,search_terms) that will be will be excluded from fetching despite being in the gaarf_exporter.yaml config.

docker run --network=host \
  -v /path/to/google-ads.yaml:/root/google-ads.yaml \
  -v /path/to/gaarf_exporter.yaml:/app/gaarf_exporter.yaml \
  gaarf_exporter \
  --config /app/gaarf-exporter.yaml \
  --queries.include=performance,disapprovals

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
2. Import 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 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 for additional configuration opportunities.

Disclaimer

This is not an officially supported Google product.