Analytics plugin

Kill Bill plugin to provide business analytics and reporting capabilities. You can find the documentation here.

Kill Bill compatibility

Plugin version	Kill Bill version
1.x.y	0.14.z
3.x.y	0.16.z
4.x.y	0.18.z
5.x.y	0.19.z
6.x.y	0.20.z
7.0.y	0.22.z
7.1.y	0.22.z
7.2.y	0.22.z
8.0.y	0.24.z

Release notes

Starting with 7.2.0, the configuration is using a YAML format, instead of key-value pairs.
We've upgraded numerous dependencies in 7.1.x (required for Java 11 support).
Version 8.1.0 of the plugin includes a DDL change. So, upgrading to this version requires running this migration.

Requirements

The plugin needs a database. The latest version of the schema can be found here.

Installation

Locally:

kpm install_java_plugin analytics --from-source-file target/analytics-plugin-*-SNAPSHOT.jar --destination /var/tmp/bundles

Configuration

Per tenant

The analytics plugin allows some optional tenant level configuration. This can be done by executing the following API endpoint:

curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d '!!org.killbill.billing.plugin.analytics.api.core.AnalyticsConfiguration
  refreshDelaySeconds: 10
  lockAttemptRetries: 100
  rescheduleIntervalOnLockSeconds: 10
  enablePartialRefreshes: true
  blacklist:
    - 468e5259-6635-4988-9ae7-3d79b11fc6ed
    - f7da09af-8593-4a88-b6d4-1c4ebf807103
  highCardinalityAccounts:
    - a8e594e5-1b78-4c2d-876b-f09ec36c611c
    - 31ea22c7-19ae-4316-a432-5e6319e49f97
  ignoredGroups:
    - FIELDS
  pluginPropertyKeys:
    killbill-stripe:
      1: processorResponse
      2: avsResultCode
      3: cvvResultCode
  databases:
    warehouse:
      type: trino
      url: jdbc:trino://example.net:8080/hive/sales?user=admin' \
    http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-analytics

Global

You can also configure the following properties related to the analytics plugin in the Kill Bill Configuration File:

org.killbill.notificationq.analytics.tableName=analytics_notifications
org.killbill.notificationq.analytics.historyTableName=analytics_notifications_history
org.killbill.analytics.lockSleepMilliSeconds=100

In addition, the following per-tenant properties can also be configured globally:

org.killbill.billing.plugin.analytics.blacklist=468e5259-6635-4988-9ae7-3d79b11fc6ed,f7da09af-8593-4a88-b6d4-1c4ebf807103
org.killbill.billing.plugin.analytics.ignoredGroups=FIELDS
org.killbill.billing.plugin.analytics.highCardinalityAccounts=a8e594e5-1b78-4c2d-876b-f09ec36c611c,31ea22c7-19ae-4316-a432-5e6319e49f97
org.killbill.billing.plugin.analytics.refreshDelaySeconds=10
org.killbill.billing.plugin.analytics.lockAttemptRetries=100
org.killbill.billing.plugin.analytics.rescheduleIntervalOnLockSeconds=10
org.killbill.billing.plugin.analytics.enablePartialRefreshes=true
org.killbill.billing.plugin.analytics.enableTemplateVariables=false

Note that the per-tenant configuration always takes precedence. So, the global properties only serve as defaults when a per-tenant configuration is not specified.

See Plugin Configuration for further information.

Setup

The analytics plugin includes a set of canned reports which can be installed by running the seed_reports.sh script. See Installing Canned Reports for further information. By default, the views will use the converted amount columns when applicable, which require the analytics_currency_conversion table to be populated with currency conversion rates as explained here. If you are only using one currency, use the non-converted columns instead (next_mrr instead of converted_next_mrr for example).

In addition, you can also create custom reports based on database tables/views. To create a report based on a local view named report_accounts_summary execute the following endpoint:

curl -v \
     -X POST \
     -u admin:password \
     -H "X-Killbill-ApiKey:bob" \
     -H "X-Killbill-ApiSecret:lazar" \
     -H 'Content-Type: application/json' \
     -d '{"reportName": "report_accounts_summary",
          "reportType": "COUNTERS",
          "reportPrettyName": "Accounts summary",
          "sourceTableName": "report_accounts_summary",
          "refreshProcedureName": "refresh_report_accounts_summary",
          "refreshFrequency": "HOURLY"}' \
     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"

See Creating Custom Reports for further information.

When configuring refreshes via stored procedures, make sure to bump the connection timeout accordingly (org.killbill.billing.osgi.dao.connectionTimeout), as it will be used to set the read and query timeouts.

In addition to creating reports, you can also perform several other report operations.

About

Kill Bill is the leading Open-Source Subscription Billing & Payments Platform. For more information about the project, go to https://killbill.io/.

killbill/killbill-analytics-plugin