Metadata-Version: 2.1
Name: gaarf-exporter
Version: 0.7.0.dev1
Author: Google Inc. (gTech gPS CSE team)
Author-email: no-reply@google.com
License: Apache 2.0
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Description-Content-Type: text/markdown

# gaarf exporter

Prometheus exporter for Google Ads metrics with customizable metrics collectors.

## Installation and usage

### Locally

1. Install `gaarf-exporter` from pip:

```
pip install gaarf-exporter
```
2. Run `gaarf-exporter`:

```
gaarf-exporter
```

### Docker

```
docker run --network=host \
  -v /path/to/google-ads.yaml:/root/google-ads.yaml \
  -v `pwd`/gaarf_exporter.yaml:/app/gaarf_exporter.yaml \
  gaarf_exporter
```

```
docker run --network=host gaarf_exporter \
  --config gs://path/to/gaarf_config.yaml \
  --ads-config gs://path/to/google-ads.yaml

```

--network=host
By default it will start http_server on `localhost:8000` and will push some basic metrics to it.

### Customization

* `--ads-config` - path to `google-ads.yaml`
* `--config` - path to `gaarf_exporter.yaml`
* `--http_server.address` - address of your http server (`localhost` by default)
* `--http_server.port` - port of your http server (`8000` by default)
* `--pushgateway.address` - address of your pushgateway service (`None` by default)
* `--pushgateway.port` - port of your pushgateway (`None` by default)
* `--delay-minutes` - delay in minutes between scrapings (`15` by default)

#### Customizing with macros:

##### Customizing fetching dates

By default `gaarf-exporter` fetches performance data for TODAY; if you want to
customize it you can provide optional flags:
* `--macro.start_date=:YYYYMMDD-N`, where `N` is number of days starting from today
* `--macro.end_date=:YYYYMMDD-M`, where `N` is number of days starting from today

It will add an additional metric to be exposed to Prometheus `*_n_days` (i.e.
`googleads_clicks_n_days`.

### Collectors

You can specify collectors with `--collectors <collector_name>` CLI argument. Some collectors available by default, other you need to specify explicitly.

#### `default` registry.

* `performance` - extract `clicks`, `impressions`, `cost`, `conversions` on by `ad_network` and `ad_group_id`
* `disapprovals` - extract `approval_status`, `review_status`, `topic`, `topic_type` by `ad_group_id` and `ad_id` only for not approved ads
* `conversion_action` - extract `all_conversions` by `conversion_id` and `account_id`
* `mapping` - performance mapping between `ad_group_id`, `ad_group_name`, `campaign_id`, `campaign_name,` `campaign_status`, `account_id`, `account_name`

#### `disapprovals` registry.

* `disapprovals` - extract `approval_status`, `review_status`, `topic`, `topic_type` by `ad_group_id` and `ad_id` only for not approved ads
* `ad_group_ad_asset_disapprovals` - extract `approval_status`, `review_status`, `topic`, `topic_type` by `ad_group_id` and `asset_id` only for enabled assets.
* `sitelink_disapprovals` - extract `approval_status`, `review_status`, `topic`, `topic_type` by `asset_id`,   `sitelink_title` and both sitelink descriptions only for not approved sitelinks.

#### `app` registry.

* `app_campaign_mapping` - performs mapping between `campaign_id`, `app_id`, `app_store`, `and bidding_strategy` only for active campaigns.
* `asset_performance` - extract `clicks`, `impressions`, `cost`, `installs`, `inapps`, and `conversions_value` by `ad_group_id`, `ad_network` and `asset_id`
* `asset_perf_label` - extract `performance_label` by `ad_group_id` and `asset_id`

#### `pmax` registry.

* `pmax_mapping` - performs mapping between `asset_group_id`, `asset_group_name`, and meta information on campaign and account only for active campaigns and enabled asset groups.

#### `search` registry.

* `search_terms` - extract `clicks`, `impressions`, `cost`, `conversions` on by `search_term` and `ad_group_id`
* `search_terms_conversion_split` - extract `all_conversions` by `search_term` and `conversion_id` on `ad_group_id` level
* `keywords` - extract `clicks`, `impressions`, `cost`, `conversions`, and `historical auality_score`  by `keyword` and `match_type` on ad_group level.
* `keywords_conversion_split` - extract `all_conversions` by `keyword` and `match_type` on ad_group level.

#### `search` registry.

* `placements` - extract `clicks`, `impressions`, `cost`, `conversions` on by `placement_name` and `placement_type` for each account.
* `placements_conversion_split` - extract `all_conversions` by `placement_type` and `placement_type` for each account.

#### `demographics` registry.

* `age` - extract `clicks`, `impressions`, `cost`, `conversions` by `age_range` and `campaign_id`
* `age_conversion_split` - extract `all_conversions` by `age_range` and `conversion_id` on `campaign_id` level
* `gender` - extract `clicks`, `impressions`, `cost`, `conversions` by `gender` and `campaign_id`
* `gender_conversion_split` - extract `all_conversions` by `gender` and `conversion_id` on `campaign_id` level

#### `geo` registry.

* `user_location` - extract `clicks`, `impressions`, `cost`, `conversions` by `country_id` and `campaign_id` only for active campaigns.
* `user_location_conversion_split` - extract `all_conversions` by `country_id`  and `campaign_id`only for active campaigns.

#### `all` registry.

* `bid_budgets` - extract current values of bid (target_cpa, target_roas) and budget
* `account_status` - extract `customer_status` for each account.
* `campaign_service_status` - extract `primary_status` for each campaign.
