Basic usage

clan has three basic uses

• Writing query results to an text or HTML report suitable for reading.
• Writing query results to a JSON file suitable for further processing.
• Generating an HTML “diff”, or change report, comparing two JSON outputs.

Generating a text report

To configure clan, create a YAML data file describing the analytics you want to run:

# Global configuration, only property-id is required
title: Commencement report
property-id: "53470309"
start-date: "2014-06-01"
prefix: "/commencement/"

# Metrics to report
queries:
    - name: Totals
      description: Top-level counts
      metrics:
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"

    - name: Totals by device category
      description: Device categories are desktop, tablet and mobile
      metrics:
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"
      dimensions:
          - "ga:deviceCategory"
      sort:
          - "-ga:pageviews"

Assuming this configuration is named “configuration.yml”, to produce an HTML report for this configuration you would run the following command.

clan report configuration.yml report.html

For complete documenation of this configuration, see Configuration.

Generating a JSON report

Instead of HTML you can output data in a JSON microformat suitable for diffing, archiving, visualization or further processing with other tools:

clan report configuration.yml report.json

Global configuration options, such as start-date can also be specified as command line arguments, allowing you to reuse a YAML configuration file for several projects. When specified, command-line arguments will always take precedence over options defined in the YAML configuration.

clan report --start-date 2014-05-1 --prefix /tshirt/ configuration.yml report.json

You can also convert an HTML report from an existing JSON report:

clan report analytics.json report.html

Generating a text diff

If you report on multiple projects using the same analytics, you can use clan to compare their performance:

clan diff a.json b.json diff.html

The values in the diff report columns will be:

• Absolute difference
• Percent change
• Change in percentage points

Generating a JSON diff

As with individual reports, diffs can also be saved as JSON for further processing:

clan diff a.json b.json diff.json