Reporting usage events from SMS Gateway

Configuring SMS Gateway to publish usage events in an IBM Cloudant database

Before configuring SMS Gateway to publish to a database, set up an IBM® Cloudant® for IBM Cloud.

Set the following environment variables in your configuration to publish usage events in an IBM Cloudant database. You can use both IBM Cloudant and another reporting service simultaneously by adding the IBM Cloudant configuration variables to your configuration.

The following examples show the configuration for publishing usage events to IBM Cloudant.

• Single-tenant environment: Set the following environment variables in your configuration. You can configure authentication for IBM Cloudant either with an API key by adding the REPORTING_USAGE_CLOUDANT_APIKEY variable or by username and password by adding REPORTING_USAGE_CLOUDANT_USERNAME and REPORTING_USAGE_CLOUDANT_PASSWORD.

REPORTING_USAGE_CLOUDANT_URL=http://usageCloudantURL.ibm.com/
REPORTING_USAGE_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
REPORTING_USAGE_CLOUDANT_USERNAME=myAdmin
REPORTING_USAGE_CLOUDANT_PASSWORD=myTokenOrPassword
REPORTING_USAGE_CLOUDANT_DB_NAME=myDBname
REPORTING_USAGE_CLOUDANT_EVENT_INDEX=usage

• Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable usage events, configure a reporting object that contains the following properties. If you use non-default account configurations to IBM Cloudant, you might need to include additional environment variables. You can configure authentication for IBM Cloudant either with an API key by adding the apiKey variable or by username and password by adding username and password.

  "reporting": {
  "usageCloudant": {
    "url": "http://usageCloudantURL.ibm.com/",
    "dbName": "myDBName",
    "username": "myAdmin",
    "password": "myTokenOrPassword",
    "apiKey": "myApiKey",
    "usageEventInd": "usage"
  }
  }
  

Configuring SMS Gateway to publish usage events in a CouchDB

To set up CouchDB, clone the repository and follow the instructions on GitHub. If you use CouchDB, you can't use an API key to authenticate.

Set the following environment variables in your configuration to publish usage events in a CouchDB database. You can use both CouchDB and another reporting service simultaneously by adding the CouchDB configuration variables to your configuration.

The following examples show the configuration for publishing usage events to CouchDB.

• Single-tenant environment: Set the following environment variables in your configuration.

REPORTING_USAGE_CLOUDANT_URL="http://<svc-couchdb>:5984/"
REPORTING_USAGE_CLOUDANT_USERNAME=myCouchDBUsername
REPORTING_USAGE_CLOUDANT_PASSWORD=myCouchDBPassword
REPORTING_USAGE_CLOUDANT_DB_NAME=myCouchDB
REPORTING_USAGE_CLOUDANT_EVENT_INDEX=usage

• Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable usage events, configure a reporting object that contains the following properties.

  "reporting": {
  "usageCloudant": {
    "url": "http://<svc-couchdb>:5984/",
    "dbName": "myDBName",
    "username": "myAdmin",
    "password": "myTokenOrPassword",
    "usageEventInd": "usage"
  }
  }
  

Configuring SMS Gateway to publish usage reporting events

1. Set up a Splunk HTTP Event Collector (HEC) or a REST server that can store the events, for example in a noSQL database.
2. Configure your REST server URL and authorization credentials and enable usage events in SMS Gateway.

• Single-tenant environment: Set the following environment variables in your configuration.

  REPORTING_URL=http://myresteventserver.ibm.com/
  REPORTING_USERNAME=myRestAdmin
  REPORTING_PASSWORD=myRestTokenOrPassword
  REPORTING_USAGE_EVENT_INDEX=usage
  

• Multi-tenant JSON configuration: In the multi-tenant JSON configuration file, for each tenant where you want to enable usage reporting, configure a reporting object that contains the following properties. You can configure indexes for other types of reporting events within the same object.

  "reporting": {
   "url": "http://myresteventserver.ibm.com/",
   "username": "myRestAdmin",
   "password": "myRestTokenOrPassword",
   "usageEventInd": "usage"
  }
  

  The usage event index value, usage, is included as the index value in all usage events, so that the REST server that consumes them can differentiate the type of event. The index field is required for Splunk HEC, but it's also useful for anyone who is building their own REST server to handle these events.

Usage event format

All SMS Gateway reporting events are based on the Splunk HTTP Event Controller JSON format.

In the following example, the usage event JSON object shows that it received one message and sent one message in the 10000 ms time interval.

{
  "time": 1514131211,
  "host": "8.64.81.144",
  "source": "tenantID",
  "sourceType": "smsgw",
  "index": "usage",
  "event": {
    "periodLength": "10000",
    "inbound": "1",
    "outbound": "1",
    "total": "2",
  }
}