Configuration¶

Configuring with YAML¶

clan is configured using either YAML, command-line arguments or both.

The basic structure of the YAML configuration file is:

# Global configuration
title: Sample configuration
property-id: "53470309"

# A list of queries to execute
queries:

    # Individual query configuration
    - name: Totals
      description: Property-wide top-level totals.
      metrics:
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"

Global configuration¶

The following is a list of properties that may be specified in as global configuration. Note that these may also be specified using command line arguments. Some properties can also be specified on a per-query basis. If there is a disagreement, the values will be preferred in the following order:

Command-line values
Query configuration in YAML
Global configuration in YAML

title¶

A user-friendly title for the report.

property-id¶

The ID of the Google Analytics property to query.

start-date¶

The start date of all queries, in YYYY-MM-DD format.

end-date¶

The end date of all queries, in YYYY-MM-DD format. Supersedes ndays if both are specified.

ndays¶

A number of days from the start date to report on. Superseded by end-date if both are specified.

domain¶

If specified, results will be limited to URLs from this domain.

prefix¶

If specified, results will be limited to URLs with this prefix.

Per-query configuration¶

Individual queries support the following properties.

name¶

A brief name for the query..

description¶

A longer description of the query.

metrics¶

A list of Google Analytics metrics to be reported.

For details about all metrics you can report on, see the Google Analytics Core Reporting API docs.

dimensions¶

A list of Google Analytics metrics on which to segment the data. Not that these are pairwise not hierarchical. If your query configuration looked like:

- name: Pageviews by device and browser
  metrics:
      - "ga:pageviews"
  dimensions:
      - "ga:deviceCategory"
      - "ga:browser"
  sort:
      - "-ga:pageviews"

Then your resulting report would enumerate the most popular combinations of device and browser, not the most popular devices further subdivided by most popular browser.

sort¶

A list of Google Analytics metrics to sort by. Prefix a value with a - to sort in descending order.

filter¶

A Google Analytics query filter expression to apply to the data. This will be “ANDed” togther with any filters automatically generated from other configuration options such as domain or prefix.

segment¶

A Google Analytics segment definition to use to filter the data.