Home

+ We are updating this page due to Cyclops 3.0 release.

Architecture diagram

Prerequisites

• Java 8 and Maven 3
• PostgreSQL 9.6: set up the database tables as per instructions in Install/schema.sh
• RabbitMQ 3.6: set up queues, exchanges and bindings as per instructions in Install/bindings.sh

Deployment

• Execute mvn package assembly:single in UDR, CDR, Coin and Billing folders
• Fill information and credentials in each microservice's configuration file
• Start compiled JARs with their respective configuration file java -jar service.jar service.conf

Usage data

Upload usage data representing consumption of your services/users to the UDR micro service

• via RabbitMQ's queue cyclops.udr.consume
• via HTTP POST at IP:PORT/usage

Both accept data in JSON and require metric, account, usage and unit fields to be present. Time field is either provided in milliseconds or generated automatically, where remaining data you might have goes into data, as in the example below.

{
  "metric": "Memory",
  "account": "Martin",
  "time": 1493450936000,
  "usage": 1024,
  "unit": "MB",
  "data": {
    "project": "ABC",
    "host": "gentoo"
  }
}

Pricing rules

Rule engine sitting between UDR and CDR micro service expects pricing rules via HTTP POST at IP:PORT/rule as plain text. The full documentation is available here.

An example pricing rule rating Storage metric (3 CHF per unit of storage):

import ch.icclab.cyclops.facts.Usage;
import ch.icclab.cyclops.facts.Charge;

rule "Static rating for Storage"
salience 50
when
  $usage: Usage(metric == "Storage") 
then
  Charge charge = new Charge($usage);
  charge.setCharge(3 * $usage.getUsage());
  charge.setCurrency("CHF");

  retract($usage);
  insert(charge);
end

And system rule that always needs to be present:

import ch.icclab.cyclops.facts.Charge;
import java.util.List;

global ch.icclab.cyclops.publish.Messenger messenger;

rule "Broadcast charge data"
salience 20
when
  $charge: List( size > 0 ) from collect ( Charge() )
then
  messenger.broadcast($charge);
  $charge.forEach(c->retract(c));
end

Billing rules

Second rule engine is put between CDR and Billing micro services and expects billing rules via HTTP POST at IP:PORT/rule as plain text. The full documentation is available here.

Two system rules are necessary, first responsible for collecting CDRs based on received Bill request (with priority 50):

import ch.icclab.cyclops.facts.BillRequest;
import ch.icclab.cyclops.facts.Charge;
import ch.icclab.cyclops.facts.Bill;
import java.util.List;

rule "Collect CDRs for the Bill Request"
salience 50
when
  $request: BillRequest($accounts: accounts)
  $CDRs: List(size > 0) from collect (Charge(account memberOf $accounts))
then
  // bills for each currency of account\'s CDRs
  List<Bill> bills = $request.process($CDRs);

  // add bills to the working memory
  bills.forEach(bill->insert(bill));

  // remove processed CDRs and the bill request
  $CDRs.forEach(c->retract(c));
  retract($request);
end

And second rule responsible for broadcasting generated bills (with priority 30):

import ch.icclab.cyclops.facts.Bill;
import java.util.List;

global ch.icclab.cyclops.publish.Messenger messenger;

rule "Broadcast generated bills"
salience 30
when
  $bills: List(size > 0) from collect (Bill())
then
  // broadcast and remove processed bills
  messenger.broadcast($bills);
  $bills.forEach(bill->retract(bill));
end

Feel free and add your own discounting and tax rules, intercepting the bill generation and broadcasting, working in the priority range of (30, 50).

Generating UDRs

Once rules have been added and your collector has sent some usage data in, the next step is to generate UDR records, which can be done by sending HTTP POST at IP:PORT/command as follows:

{
  "command": "GenerateUDRs",
  "time_from": 1501027200000,
  "time_to": 1501113599999
}

This consolidates usage data and generates UDRs in the period time_from and time_to (in milliseconds).

Generating CDRs

Generating Bills