betahuhn / ackee-report

📈 CLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.

ackee-report

CLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.

👋 Introduction

ackee-report lets you create monthly website performance reports using your Ackee analytics data and either send them via email, generate a RSS feed or output it to a JSON file. It uses Ackee's Graphql API and can be configured to generate multiple reports for different websites, data ranges and recipients.

🚀 Get started

Install ackee-report globally via npm:

npm install ackee-report -g

ackee-report@latest requires Ackee >=v3.1.1. Use [email protected] for older versions of Ackee

After that ackee-report is ready to be used 🎉

⚙️ Configuration

On the first run ackee-report will ask you to input a few values:

• ackee server / ACKEE_SERVER - the endpoint of your Ackee instance
• ackee token / ACKEE_TOKEN - a permanent Ackee token (can be used instead of username and password, more info)
• ackee username ACKEE_USERNAME - your Ackee username (more info)
• ackee password ACKEE_PASSWORD - your Ackee password (more info)
• email host / EMAIL_HOST - the domain of the email server (more info)
• email port / EMAIL_PORT - the port of the email server (more info)
• email username / EMAIL_USERNAME - the username to use with the email server (more info)
• email password / EMAIL_PASSWORD - the password to use with the email server (more info)
• email from / EMAIL_FROM - the from address to use (more info)

The configuration will be stored in your home directory under ~/.config/configstore/ackee-report.json and can be changed at any point.

Environment Variables

If you don't want to interact with ackee-report via the CLI interface, you can also specify each configuration option as an environment variable e.g. ACKEE_TOKEN=<token>

Ackee API authentication

ackee-report needs access to your Ackee instance via the API in order to get all the data it needs to generate the report. You can choose any of the two authentication methods below:

Username and password:

Enter your username and password you use to login to the Ackee UI on the first run of ackee-report or change it in the config file later.

ackee-report will then use them to create a temporary access token each time it runs and use it to query the Ackee API.

Permanent access token (recommended):

The recommended way of authenticating ackee-report is with a permanent access token (only available with Ackee v2.2.0 or later).

You will have to create one via the Ackee UI under Settings/Permanent Tokens, then click on New permanent token and give it a name (doesn't matter what).

Copy the permanent token id and enter it on the first run of ackee-report or add it to the config file under ackee.token later.

The same token will then be used each time ackee-report runs to query the Ackee API.

Email setup

If you want to send your report via email, you have to specify your email providers SMTP server and credentials, as well as the from option:

• Host - smtp.example.com
• Port - 465
• Username - [email protected]
• Password - password
• From - [email protected] or Ackee <[email protected]>

Note: For port 465 ackee-report will use TLS when connecting to your email server, on all other ports it will use STARTTLS (#44)

Common providers:

Gmail

If you use gmail to send emails, use these values:

• Host - smtp.gmail.com
• Port - 465
• Username - your gmail username (your email address)
• Password - your gmail password or if you have 2FA enabled, an "Application Specific password"

SendGrid

If you use SendGrid to send emails, use these values:

• Host - smtp.sendgrid.net
• Port - 465
• Username - apikey (everyone's username is apiKey)
• Password - your API Key (generate one here)

MailGun

If you use SendGrid to send emails, use these values:

• Host - smtp.mailgun.org
• Port - 465
• Username - [email protected]
• Password - get your password here

📚 Usage

Usage: ackee-report <command> [options]

CLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.

Commands:
  email [options]             Generate report and send it via email
  json [options]              Query API for data and output it to JSON file
  html [options]              Generate report and output it to a HTML file
  rss|xml [options]           Generate report as a RSS feed
  domains|domain [titles...]  get domain id by title
  config                      output current config
  help [command]              display help for command

Options:
  General:
    -d, --domain <titles...>    specify domains by title
    -i, --id <ids...>           specify domains by id
    -r, --range <range>         specify data range (default: "month")
    -l, --limit <number>        limit number of list items (default: 3)
    -e, --events [type]         get event data (default: false)
    -v, --version               output the version number
    -h, --help                  display help for command

  Email:
    -t, --to <recipient...>     to whom the report should be sent

  RSS/JSON/HTML:
    -o, --output <file>         path to output file (default: "report.[xml/json/html]")

Example call:
  $ ackee-report email --domain example.com --to [email protected]

If you want to send the report periodically, you have to setup a cron job which runs the command at a set interval (example below).

🛠️ Examples

Generate a report for one domain and send it via email

ackee-report email -d example.com -t [email protected]

This will generate a report for the domain example.com and send it via email to [email protected].

Multiple domains and recipients

ackee-report email -d example.com example2.com -t [email protected] [email protected]

Include events in report

ackee-report email -d all -t [email protected] -e

Average event type

ackee-report email -d all -t [email protected] -e avg

Custom range

You can specify the data range of the report with the -r/--range option:

ackee-report email -d example.com -t [email protected] -r day

Available values: day/week/month/six_months.

Note: The total views/range value is calculated by counting the views of the last x days since the program ran. For the month range for example, it is not the number of views in the current month, but the number of views in the last 30 days.

Send the report periodically (cron)

To send a report periodically, for example every month at the 28th at 23:55 setup a cron job like this:

55 23 28 * * ackee-report email -d example.com -t [email protected] >> /tmp/ackee-report.log 2>&1

Note: We use the 28th as running on the last day of the month is very complicated with cron and Ackee resets its data on the first day of each month.

Note: You may have to specify the actual path to ackee-report. In that case, replace ackee-report in the command above with the output of which ackee-report.

If you are not familiar with cron, here's a tutorial on how to get started.

To send multiple reports to different people, add them all as seperate cron jobs.

Generate RSS feed

You can generate a RSS feed/xml file instead of sending the report via email:

ackee-report rss -d example.com -o output.xml

Output the report to a JSON file

You can also save the report in a JSON file:

ackee-report json -d example.com -o output.json

Output the email report to a HTML file

You can also save the report, which is normally sent via email, directly to an HTML file:

ackee-report html -d example.com -o index.html

🖼️ Screenshot

💻 Development

Issues and PRs are very welcome!

Run yarn lint or npm run lint to use eslint.

Please check out the contributing guide before you start.

To see differences with previous versions refer to the CHANGELOG.

❔ About

This library is an extension to the awesome privacy focused analytics tool Ackee.

Ackee was developed by @electerious, if you want to support him and the development of Ackee visit the Donate section on the Ackee repository.

License

Copyright 2020 Maximilian Schiller

This project is licensed under the MIT License - see the LICENSE file for details.

ackee-report's Issues

Broken data references

🐞 Describe the bug

Used to be working
After V2 it changed
Report shows mangled data for pages and referrers, and broken average calculations

🖼️ Screenshots

See attached

⚙️ Environment

• OS: Ubuntu
• Version 20.04
• Ackee version : 3.1.1

Pages and referrers should be links

Describe the bug
Pages and referrers are currently only text.

Expected behavior
If they are a URL, they should be clickable links.

Additional context
Originally posted by @electerious in #7 (comment)

Pressing enter should skip the option

Describe the bug

ackee-report asks to input a few values when you use it for the first time. I don't have an email host, username and password as I wanted to use the RSS generator. It would be great if there's a way to skip them.

Expected behavior

Pressing enter should skip the option.

Screenshots

I've entered a space in order to skip them.

AckeeApiError: `GRAPHQL_VALIDATION_FAILED`

🐞 Describe the bug

When running Ackee Report I get this error:

✖  AckeeApiError: {"errors":[{"message":"Field \"averageViews\" of type \"AverageViews!\" must have a selection of subfields. Did you mean \"averageViews { ... }\"?","locations":[{"line":7,"column":8}],"extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}},{"message":"Field \"averageDuration\" of type \"AverageDuration!\" must have a selection of subfields. Did you mean \"averageDuration { ... }\"?","locations":[{"line":8,"column":8}],"extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}]} (400 status code)

📚 To Reproduce

• Install ackee-report
• Configure token and server
• Try to do ackee-report html -d all

💡 Expected behavior

Report to be generated

🖼️ Screenshots

⚙️ Environment

• OS: Linux Mint 20.1
• Shell fish
• Ackee version 3.1.1
• Ackee Report version 1.3.3

RSS / XML export

Is your feature request related to a problem? Please describe.

I just thought that it would be cool to get a daily Ackee report in my RSS reader.

Describe the solution you'd like

ackee-report rss or ackee-report xml command that generates a RSS feed you can subscribe to. You just need to place the file into an accessible folder (probably protected) and subscribe to it.