mirror of
https://github.com/cgrates/cgrates.git
synced 2026-02-11 18:16:24 +05:00
Documentation refactoring to provide better structure for later
This commit is contained in:
DanB
@@ -31,7 +31,7 @@ import (
|
||||
|
||||
var (
|
||||
version = flag.Bool("version", false, "Prints the application version.")
|
||||
server = flag.String("server", "127.0.0.1:2000", "server address host:port")
|
||||
server = flag.String("server", "127.0.0.1:2012", "server address host:port")
|
||||
rpc_encoding = flag.String("rpc_encoding", "gob", "RPC encoding used <gob|json>")
|
||||
)
|
||||
|
||||
|
||||
11
docs/administration.rst
Normal file
11
docs/administration.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
5. Administration
|
||||
=================
|
||||
|
||||
The general steps to get CGRateS operational are:
|
||||
|
||||
#. Create CSV files containing the initial data for CGRateS.
|
||||
#. Load the data in the databases using the Loader application.
|
||||
#. Start the a Balancer or a Rater. If Balancer is used, start one or more Raters serving that Balancer.
|
||||
#. Start the SessionManager talking to your VoIP Switch or directly make API calls to the Balancer/Rater.
|
||||
#. Make API calls to the Balancer/Rater or just let the SessionManager do the work.
|
||||
|
||||
2
docs/advanced.rst
Normal file
2
docs/advanced.rst
Normal file
@@ -0,0 +1,2 @@
|
||||
6. Advanced Topics
|
||||
==================
|
||||
105
docs/architecture.rst
Normal file
105
docs/architecture.rst
Normal file
@@ -0,0 +1,105 @@
|
||||
2. Architecture
|
||||
===============
|
||||
|
||||
The CGRateS suite consits of three software applications, described bellow.
|
||||
|
||||
2.1. cgr-rater
|
||||
--------------
|
||||
The most important and complex as functionality.
|
||||
|
||||
Customisable through the use of a configuration file, it will start on demand one or more services, outlined bellow.
|
||||
|
||||
::
|
||||
|
||||
rif@grace:~$ cgr-rater -help
|
||||
Usage of cgr-rater:
|
||||
-config="/etc/cgrates/cgrates.cfg": Configuration file location.
|
||||
-version=false: Prints the application version.
|
||||
|
||||
:Example: cgr-rater -config=cgr-customconfig.cfg
|
||||
|
||||
2.1.1. Rater service
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
Responsible with the following tasks:
|
||||
|
||||
- Operates on balances.
|
||||
- Computes prices for rating subjects.
|
||||
- Monitors and executes triggers.
|
||||
|
||||
Accessed by components using it's functionality via RPC or directly within same running cgr-rater process.
|
||||
|
||||
2.1.2. Balancer service
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
Optional component, used as proxy/balancer to a pool of Rater workers.
|
||||
|
||||
The Raters will register their availability to the Balancer thus implementing dynamic HA functionality.
|
||||
|
||||
2.1.3. Scheduler service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Used to execute periodic/scheduled tasks.
|
||||
|
||||
2.1.4. SessionManager service
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Responsible with call control on the Telecommunication Switch side. Operates in two different modes (per call or globally):
|
||||
|
||||
- Prepaid
|
||||
|
||||
- Monitors call start.
|
||||
- Checks balance availability for the call.
|
||||
- Enforces global timer for a call at call-start.
|
||||
- Executes routing commands for the call where that is necessary ( eg call un-park in case of FreeSWITCH).
|
||||
- Periodically executes balance debits on call at the beginning of debit interval.
|
||||
- Enforce call disconnection on insufficient balance.
|
||||
- Refunds the balance taken in advance at the call stop.
|
||||
|
||||
- Postpaid
|
||||
|
||||
- Executes balance debit on call-stop.
|
||||
|
||||
All call actions are logged into CGRateS's LogDB.
|
||||
|
||||
2.1.5 Mediator service
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
Responsible to mediate the CDRs generated by Telecommunication Switch.
|
||||
|
||||
Has the ability to combine CDR fields into rating subject and run multiple mediation processes on the same record.
|
||||
|
||||
On Linux machines, able to work with inotify kernel subsystem in order to process the records close to real-time after the Switch has released them.
|
||||
|
||||
|
||||
2.2. cgr-loader
|
||||
---------------
|
||||
Used for importing the rating information into the CGRateS database system.
|
||||
|
||||
::
|
||||
|
||||
rif@grace:~$ cgr-loader -help
|
||||
Usage of cgr-loader:
|
||||
-dbhost="localhost": The database host to connect to.
|
||||
-dbname="10": he name/number of the database to connect to.
|
||||
-dbpass="": The database user's password.
|
||||
-dbport="6379": The database port to bind to.
|
||||
-dbtype="redis": The type of the database (redis|mongo|postgres)
|
||||
-dbuser="": The database user to sign in as.
|
||||
-flush=false: Flush the database before importing
|
||||
-path=".": The path containing the data files
|
||||
-version=false: Prints the application version.
|
||||
|
||||
:Example: cgr-loader -flush
|
||||
|
||||
|
||||
2.3. cgr-console
|
||||
~~~~~~~~~~~~~~~
|
||||
Command line tool used to interface with the Rater (or Balancer). Able to execute sub-commands
|
||||
::
|
||||
|
||||
cgrrif@grace:~$ cgr-console -help
|
||||
Usage of cgr-console:
|
||||
-rpc_encoding="gob": RPC encoding used <gob|json>
|
||||
-server="127.0.0.1:2012": server address host:port
|
||||
-version=false: Prints the application version.
|
||||
cgrrif@grace:~$ cgr-console help_more
|
||||
2013/04/13 17:23:51
|
||||
Usage: cgr-console [cfg_opts...{-h}] <status|get_balance>
|
||||
|
||||
:Example: cgr-console status
|
||||
@@ -1,4 +0,0 @@
|
||||
Software design
|
||||
===============
|
||||
|
||||
To be written.
|
||||
@@ -48,9 +48,9 @@ copyright = u'2012, Radu Ioan Fericean'
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '1.0a1'
|
||||
version = '0.9.1'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '1.0a1'
|
||||
release = '0.9.1rc1'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
|
||||
81
docs/configuration.rst
Normal file
81
docs/configuration.rst
Normal file
@@ -0,0 +1,81 @@
|
||||
4. Configuration
|
||||
================
|
||||
|
||||
|
||||
cgr-rater configuration file
|
||||
----------------------------
|
||||
Organized into configuration sections. All configuration options come with defaults and we have tried our best to choose the best ones for a minimum of efforts necessary to run.
|
||||
|
||||
Bellow is the default configuration file which comes hardcoded into cgr-rater.
|
||||
|
||||
::
|
||||
|
||||
# CGRateS Configuration file
|
||||
#
|
||||
# This file contains the default configuration hardcoded into CGRateS.
|
||||
# This is what you get when you load CGRateS with an empty configuration file.
|
||||
# [global] must exist in all files, rest of the configuration is inter-changeable.
|
||||
|
||||
[global]
|
||||
# datadb_type = redis # The main database: <redis>.
|
||||
# datadb_host = 127.0.0.1 # Database host address.
|
||||
# datadb_port = 6379 # Port to reach the database.
|
||||
# datadb_name = 10 # The name of the database to connect to.
|
||||
# datadb_user = # Username to use when connecting to database.
|
||||
# datadb_passwd = # Password to use when connecting to database.
|
||||
# logdb_type = mongo # Log/stored database type to use: <same|postgres|mongo|redis>
|
||||
# logdb_host = 127.0.0.1 # The host to connect to. Values that start with / are for UNIX domain sockets.
|
||||
# logdb_port = 27017 # The port to reach the logdb.
|
||||
# logdb_name = cgrates # The name of the log database to connect to.
|
||||
# logdb_user = # Username to use when connecting to logdb.
|
||||
# logdb_passwd = # Password to use when connecting to logdb.
|
||||
|
||||
[balancer]
|
||||
# enabled = false # Start Balancer service: <true|false>.
|
||||
# listen = 127.0.0.1:2012 # Balancer listen interface: <disabled|x.y.z.y:1234>.
|
||||
# rpc_encoding = gob # RPC encoding used: <gob|json>.
|
||||
|
||||
[rater]
|
||||
# enabled = false # Enable Rater service: <true|false>.
|
||||
# balancer = disabled # Register to Balancer as worker: <enabled|disabled>.
|
||||
# listen = 127.0.0.1:2012 # Rater's listening interface: <internal|x.y.z.y:1234>.
|
||||
# rpc_encoding = gob # RPC encoding used: <gob|json>.
|
||||
|
||||
[scheduler]
|
||||
# enabled = false # Starts Scheduler service: <true|false>.
|
||||
|
||||
[mediator]
|
||||
# enabled = false # Starts Mediator service: <true|false>.
|
||||
# rater = 127.0.0.1:2012 # Address where to reach the Rater.
|
||||
# rpc_encoding = gob # RPC encoding used when talking to Rater: <gob|json>.
|
||||
# skipdb = false # Skips database checks for previous recorded prices: <true|false>.
|
||||
# pseudoprepaid = false # Execute debits together with pricing: <true|false>.
|
||||
# cdr_type = freeswitch_cdr # CDR type <freeswitch_cdr>.
|
||||
# cdr_in_dir = /var/log/freeswitch/cdr-csv # Absolute path towards the directory where the CDRs are kept.
|
||||
# cdr_out_dir =/var/log/cgrates/cdr_out # Absolute path towards the directory where processed CDRs will be exported.
|
||||
|
||||
[session_manager]
|
||||
# enabled = false # Starts SessionManager service: <true|false>.
|
||||
# switch_type = freeswitch # Defines the type of switch behind: <freeswitch>.
|
||||
# rater = 127.0.0.1:2012 # Address where to reach the Rater.
|
||||
# debit_interval = 5 # Interval to perform debits on.
|
||||
# rpc_encoding = gob # RPC encoding used when talking to Rater: <gob|json>.
|
||||
# default_reqtype = # Default request type to consider when missing from requests: <""|prepaid|postpaid>.
|
||||
# default_tor = 0 # Default Type of Record to consider when missing from requests.
|
||||
# default_tenant = 0 # Default Tenant to consider when missing from requests.
|
||||
# default_subject = 0 # Default rating Subject to consider when missing from requests.
|
||||
|
||||
[freeswitch]
|
||||
# server = 127.0.0.1:8021 # Adress where to connect to FreeSWITCH socket.
|
||||
# passwd = ClueCon # FreeSWITCH socket password.
|
||||
# reconnects = 5 # Number of attempts on connect failure.
|
||||
# uuid_index = 10 # Index of the UUID info in the CDR file.
|
||||
# direction_index = -1 # Index of the CallDirection info in the CDR file.
|
||||
# tor_index = -1 # Index of the TypeOfRecord info in the CDR file.
|
||||
# tenant_index = -1 # Index of the Tenant info in the CDR file.
|
||||
# subject_index = -1 # Index of the Subject info in the CDR file. -1 to query database instead of rater
|
||||
# account_index = -1 # Index of the Account info in the CDR file.
|
||||
# destination_index = -1 # Index of the Destination info in the CDR file.
|
||||
# time_start_index = -1 # Index of the TimeStart info in the CDR file.
|
||||
# duration_index = -1 # Index of the CallDuration info in the CDR file.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
.. CGRates documentation master file, created by
|
||||
.. CGRateS documentation master file, created by
|
||||
sphinx-quickstart on Mon Mar 5 10:59:27 2012.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to CGRates's documentation!
|
||||
Welcome to CGRateS's documentation!
|
||||
===================================
|
||||
|
||||
Contents:
|
||||
@@ -11,10 +11,13 @@ Contents:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro
|
||||
importing
|
||||
introduction
|
||||
architecture
|
||||
installation
|
||||
configuration
|
||||
administration
|
||||
advanced
|
||||
tutorial
|
||||
apicalls
|
||||
arhitecture
|
||||
miscellaneous
|
||||
|
||||
|
||||
|
||||
56
docs/installation.rst
Normal file
56
docs/installation.rst
Normal file
@@ -0,0 +1,56 @@
|
||||
3.Installation
|
||||
==============
|
||||
|
||||
CGRateS can be installed via packages as well as Go automated source install.
|
||||
We recommend using source installs for advanced users familiar with Go programming and packages for users not willing to be involved in the code building process.
|
||||
|
||||
3.1. Using packages
|
||||
-------------------
|
||||
Details will come here.
|
||||
|
||||
3.2. Using source
|
||||
-----------------
|
||||
|
||||
After the go environment is installed_ and configured_ issue the following commands:
|
||||
::
|
||||
|
||||
go get github.com/cgrates/cgrates
|
||||
|
||||
This command will install the trunk version of CGRateS together with all the necessary dependencies.
|
||||
|
||||
.. _installed: http://golang.org/doc/install
|
||||
.. _configured: http://golang.org/doc/code.html
|
||||
|
||||
Post-install
|
||||
--------------
|
||||
CGRateS needs at minimum one external database where to keep it's main data as well as logs of it's operation.
|
||||
|
||||
At present we support the following databases:
|
||||
As DataDB:
|
||||
- Redis_
|
||||
As LogDB:
|
||||
- PostgreSQL_
|
||||
- mongoDB_
|
||||
- Redis_
|
||||
|
||||
When using PostgreSQL_ as your LogDB, the following data table needs to be created and accessible to CGRateS LogDB user::
|
||||
|
||||
CREATE TABLE callcosts (
|
||||
uuid varchar(80) primary key,
|
||||
source varchar(32),
|
||||
direction varchar(32),
|
||||
tenant varchar(32),
|
||||
tor varchar(32),
|
||||
subject varchar(32),
|
||||
account varchar(32),
|
||||
destination varchar(32),
|
||||
cost real,
|
||||
conect_fee real,
|
||||
timespans text
|
||||
);
|
||||
|
||||
|
||||
.. _Redis: http://redis.io/
|
||||
.. _PostgreSQL: http://www.postgresql.org/
|
||||
.. _mongoDB: http://www.mongodb.org/
|
||||
|
||||
@@ -1,98 +0,0 @@
|
||||
Introduction
|
||||
============
|
||||
CGRateS is a very fast and easy scalable rating engine targeted especially for ISPs and Telecom Operators.
|
||||
|
||||
It is written in go (http://golang.org) and accessible from any language via JSON RPC. The code is well documented (go doc compliant API docs) and heavily tested.
|
||||
|
||||
After testing various databases like Kyoto_ cabinet, Redis_ or Mongodb_, the project focused on Redis as it delivers the best trade-off between speed, configuration and scalability. However connection to any database can be easily integrated by writing a simple adapter.
|
||||
|
||||
.. _kyoto: http://fallabs.com/kyotocabinet
|
||||
.. _Redis: http://redis.io
|
||||
.. _Mongodb: http://www.mongodb.org
|
||||
|
||||
Here are some of the configurations in which CGRateS can operate:
|
||||
|
||||
.. image:: images/Simple.png
|
||||
If the network does not require more than one rater to handle the calls. The balancer can be left out and the rater can be queried directly.
|
||||
|
||||
.. image:: images/Normal.png
|
||||
While the network grows more raters can be thrown into the stack to offer more requests per seconds workload. This implies the usage of the balancer to distribute the requests to the raters running on the different machines.
|
||||
|
||||
.. image:: images/Complicated.png
|
||||
Of course more session managers can serve multiple call switches and all of them are connected to the same balancer. We are planning to support multiple balancers for huge networks if the need arises.
|
||||
|
||||
|
||||
Features
|
||||
--------
|
||||
- Reliable and Fast ( very fast ;) ). To get an idea about speed, we have benchmarked 11000+ req/sec on a rather modest machine without requiring special tweaks in the kernel
|
||||
- Using most modern programing concepts like multiprocessor support, asynchronous code execution within microthreads
|
||||
- Built-in data caching system per call duration
|
||||
- In-Memory database with persistence
|
||||
- Use of Balancer assures High-Availability of Raters as well as increase of processing performance where that is required
|
||||
- Use of Linux enterprise ready tools to assure High-Availability of the Balancer where that is required (*Supervise* for Application level availability and *LinuxHA* for Host level availability)
|
||||
- Modular architecture
|
||||
- Easy to enhance functionality by rewriting custom session managers or mediators
|
||||
- Flexible API accessible via both Gob (Golang specific, increased performance) or JSON (platform independent, universally accesible)
|
||||
- Prepaid and Pseudo-Prepaid Controller
|
||||
- Mutiple Primary Balances per Account (eg: MONETARY, SMS, INTERNET_MINUTES, INTERNET_TRAFFIC)
|
||||
- Multiple Auxiliary Balances per Account (eg: Free Minutes per Destination, Volume Rates, Volume Discounts)
|
||||
- Concurrent sessions per account sharing the same balance with configurable debit interval (starting with 1 second)
|
||||
- Built-in Task-Scheduler supporting both one-time as well as recurrent actions (eg: TOPUP_MINUTES_PER_DESTINATION, DEBIT_MONETARY, RESET_BALANCE)
|
||||
- ActionTriggers ( useful for commercial offerings like receive amounts of monetary units if a specified number of minutes was charged in a month)
|
||||
- Highly configurable Rating
|
||||
- Connect Fees
|
||||
- Priced Units definition
|
||||
- Rate increments
|
||||
- Millisecond timestaps
|
||||
- Four decimal currencies
|
||||
- Multiple TypeOfRecord rating (eg: standard vs. premium calls, SMSes, Internet Traffic)
|
||||
- Rating subject concatenations for combined records (eg: location based rating for same user)
|
||||
- Recurrent rates definition (per year, month, day, dayOfWeek, time)
|
||||
- Rating Profiles activation times (eg: rates becoming active at specific time in future)
|
||||
- Multi-Tenant for both Prepaid as well as Rating
|
||||
- Flexible Mediator able to run multiple mediation processes on the same CDR.
|
||||
- Verbose action logging in persistent databases (eg: Postgres) to cope with country specific law requirements
|
||||
- Good documentation ( that's me :)
|
||||
- "Free as in Beer" with commercial support available on-demand.
|
||||
|
||||
|
||||
How does CGRateS work?
|
||||
----------------------
|
||||
Let's start with the most important function: finding the cost of a certain call. The call information comes to CGRateS as the following values: subject, destination, start time and end time. The engine will lookup in the database for the activation periods applicable to the received subject and destination. What are the activation periods?
|
||||
|
||||
The activation period is a structure describing different prices for a call on different intervals of time. This structure has an activation time, from this time on the activation period is in effect and one ore more (usually more than one) intervals with prices. An interval is looking like this:
|
||||
|
||||
::
|
||||
|
||||
Interval {
|
||||
Months
|
||||
MonthDays
|
||||
WeekDays
|
||||
StartTime, EndTime
|
||||
Weight, ConnectFee, Price, BillingUnit
|
||||
}
|
||||
|
||||
It specifies the Month, the MonthDay, the WeekDays and the StartTime and the EndTime when the Interval's Price is in effect.
|
||||
|
||||
For example the interval {"Month": [1], "WeekDays":[1,2,3,4,5]. "StartTime":"18:00:00", "Price":0.1, "BillingUnit": 1} specifies that the Price for the first month of each year from Monday to Friday starting 18:00 is 0.1 cents per second. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero ore any.
|
||||
|
||||
The ConnectFee specifies the connection price for the call if this interval is the first one from the call and the Weight will establishes which interval will set the price for a call segment if more then one applies to it.
|
||||
|
||||
For example there is an interval defining price for the weekdays and another interval that defines a special holiday prices. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the smaller Weight will give the price for the call in question. If both intervals have the same Weight than the interval with the smaller price wins. It is, however, a good practice to set the Weight for the defined intervals. For more information see :ref:`data-importing`.
|
||||
|
||||
So when there is a need to define new sets of prices just define new ActivationPeriods with the StartTime set to the moment when they become active.
|
||||
|
||||
Let's get back to the engine. After it finds the applicable ActivationPeriod(s) it will split the call interval in multiple time-spans attaching the appropriate ActivationPeriod and Interval to each them. The final price will be the sum of the prices of these times spans plus the ConnectionFee from the first time-span of the call.
|
||||
|
||||
The other functions relay on a user budget structure to manage the different quotas for postpaid and prepaid clients. The UserBudget keeps track of user credit, free SMS and minutes for every destination, Internet traffic and offers the volume discount and received call bonus. Let's take them one by one.
|
||||
|
||||
CGRateS provide api for adding/substracting user's money credit. The prepaid and postpaid are uniformly treated except that the prepaid is checked to be alway greater than zero and the postpaid is always lower than zero.
|
||||
|
||||
Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals conforming to user tariff plan or as the user buys more free SMS (for example).
|
||||
|
||||
The free (or special price) minutes must be handled a little differently because usually they are grouped by specific destinations (e.g. national minutes, ore minutes in the same network). So they are grouped in buckets and when a call is made the engine checks all applicable buckets to consume minutes according to that call.
|
||||
|
||||
Another special feature allows user to get a better price as the call volume increases each month. This can be added on one ore more thresholds so the more he/she talks the cheaper the calls.
|
||||
|
||||
Finally bonuses can be reworded to users who received a certain volume of calls. For information on how to define the bonuses see :ref:`data-importing`.
|
||||
|
||||
108
docs/introduction.rst
Normal file
108
docs/introduction.rst
Normal file
@@ -0,0 +1,108 @@
|
||||
1.Introduction
|
||||
==============
|
||||
CGRateS is a very fast and easy scalable rating engine targeted especially for ISPs and Telecom Operators.
|
||||
|
||||
It is written in Go (http://golang.org) and accessible from any language via JSON RPC. The code is well documented (go doc compliant API docs) and heavily tested.
|
||||
|
||||
After testing various databases like Kyoto_ cabinet, Redis_ or Mongodb_, the project focused on Redis as it delivers the best trade-off between speed, configuration and scalability. Despite that a connection to any database can be easily integrated by writing a simple adapter.
|
||||
|
||||
.. _kyoto: http://fallabs.com/kyotocabinet
|
||||
.. _Redis: http://redis.io
|
||||
.. _Mongodb: http://www.mongodb.org
|
||||
|
||||
To better understand the CGRateS architecture, bellow are some of the configurations in which CGRateS can operate:
|
||||
|
||||
.. image:: images/Simple.png
|
||||
|
||||
This scenario fits most of the simple installations. The Balancer can be left out and the Rater can be queried directly.
|
||||
|
||||
.. image:: images/Normal.png
|
||||
|
||||
While the network grows more Raters can be thrown into the stack to offer more requests per seconds workload. This implies the usage of the Balancer to distribute the requests to the Raters running on the different machines.
|
||||
|
||||
.. image:: images/Complicated.png
|
||||
|
||||
Of course more SessionManagers can serve multiple Telecom Switches and all of them are connected to the same Balancer. We are planning to support multiple Balancers for huge networks if the need arises.
|
||||
|
||||
|
||||
1.1. CGRateS Features
|
||||
---------------------
|
||||
- Reliable and Fast ( very fast ;) ). To get an idea about speed, we have benchmarked 11000+ req/sec on a rather modest machine without requiring special tweaks in the kernel.
|
||||
- Using most modern programming concepts like multiprocessor support, asynchronous code execution within microthreads.
|
||||
- Built-in data caching system per call duration.
|
||||
- In-Memory database with persistence over restarts.
|
||||
- Use of Balancer assures High-Availability of Raters as well as increase of processing performance where that is required.
|
||||
- Use of Linux enterprise ready tools to assure High-Availability of the Balancer where that is required (*Supervise* for Application level availability and *LinuxHA* for Host level availability).
|
||||
- Modular architecture
|
||||
- Easy to enhance functionality by rewriting custom session managers or mediators.
|
||||
- Flexible API accessible via both Gob (Golang specific, increased performance) or JSON (platform independent, universally accesible).
|
||||
- Prepaid, Postpaid and Pseudo-Prepaid Controller.
|
||||
- Mutiple Primary Balances per Account (eg: MONETARY, SMS, INTERNET_MINUTES, INTERNET_TRAFFIC).
|
||||
- Multiple Auxiliary Balances per Account (eg: Free Minutes per Destination, Volume Rates, Volume Discounts).
|
||||
- Concurrent sessions per account sharing the same balance with configurable debit interval (starting with 1 second).
|
||||
- Built-in Task-Scheduler supporting both one-time as well as recurrent actions (eg: TOPUP_MINUTES_PER_DESTINATION, DEBIT_MONETARY, RESET_BALANCE).
|
||||
- ActionTriggers ( useful for commercial offerings like receive amounts of monetary units if a specified number of minutes was charged in a month).
|
||||
- Highly configurable Rating.
|
||||
- Connect Fees.
|
||||
- Priced Units definition.
|
||||
- Rate increments.
|
||||
- Millisecond timestaps.
|
||||
- Four decimal currencies.
|
||||
- Multiple TypeOfRecord rating (eg: standard vs. premium calls, SMSes, Internet Traffic).
|
||||
- Rating subject concatenations for combined records (eg: location based rating for same user).
|
||||
- Recurrent rates definition (per year, month, day, dayOfWeek, time).
|
||||
- Rating Profiles activation times (eg: rates becoming active at specific time in future).
|
||||
- Multi-Tenant for both Prepaid as well as Rating.
|
||||
- Flexible Mediator able to run multiple mediation processes on the same CDR.
|
||||
- Verbose action logging in persistent databases (eg: Postgres) to cope with country specific law requirements.
|
||||
- Good documentation ( that's me :).
|
||||
- "Free as in Beer" with commercial support available on-demand.
|
||||
|
||||
|
||||
How does CGRateS work?
|
||||
----------------------
|
||||
Let's start with the most important function: finding the cost of a certain call.
|
||||
|
||||
The call information comes to CGRateS having the following information: subject, destination, start time and end time. The engine will lookup the database for the activation periods applicable to the received subject and destination.
|
||||
|
||||
What are the activation periods?
|
||||
|
||||
The activation period is a structure describing different prices for a call on different intervals of time. This structure has an activation time, which enables the complete on the activation period at some point in time and one ore more (usually more than one) intervals with prices.
|
||||
|
||||
::
|
||||
Interval {
|
||||
Months
|
||||
MonthDays
|
||||
WeekDays
|
||||
StartTime, EndTime
|
||||
Weight, ConnectFee, Price, BillingUnit
|
||||
}
|
||||
|
||||
An **Interval** specifies the Month, the MonthDay, the WeekDays and the StartTime and the EndTime when the Interval's price profile is in effect.
|
||||
|
||||
:Example: The Interval {"Month": [1], "WeekDays":[1,2,3,4,5], "StartTime":"18:00:00", "Price":0.1, "BillingUnit": 1} specifies that the Price for the first month of each year from Monday to Friday starting 18:00 is 0.1 cents per second. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero ore any.
|
||||
|
||||
The *ConnectFee* specifies the connection price for the call if this interval is the first one from the call.
|
||||
|
||||
The *Weight* will establish which interval will set the price for a call segment if more then one applies to it.
|
||||
|
||||
:Example: Let's assume there is an interval defining price for the weekdays and another interval that defines a special holiday prices. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the smaller Weight will give the price for the call in question. If both intervals have the same Weight than the interval with the smaller price wins. It is, however, a good practice to set the Weight for the defined intervals.
|
||||
|
||||
So when there is a need to define new sets of prices just define new ActivationPeriods with the StartTime set to the moment when they become active.
|
||||
|
||||
Let's get back to the engine. After it finds the applicable ActivationPeriod(s) it will split the call duration in multiple time-spans attaching the appropriate ActivationPeriod and Interval to each them. The final price will be the sum of the prices of these times spans plus the ConnectionFee from the first time-span of the call.
|
||||
|
||||
The other functions relay on a user budget structure to manage the different quotas for postpaid and prepaid clients. The UserBudget keeps track of user monetary balance, free SMS and minutes for every destination, Internet traffic and offers the volume discount and received call bonus.
|
||||
|
||||
Let's take them one by one.
|
||||
|
||||
CGRateS provide api for adding/substracting user's money credit. The prepaid and postpaid are uniformly treated except that the prepaid is checked to be always greater than zero and the postpaid can go bellow zero.
|
||||
|
||||
Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals based on the user tariff plan or as the user buys more free SMS (for example).
|
||||
|
||||
The free (or special price) minutes must be handled a little differently because usually they are grouped by specific destinations (e.g. national minutes, ore minutes in the same network). So they are grouped in buckets and when a call is made the engine checks all applicable buckets to consume minutes according to that call.
|
||||
|
||||
Another special feature allows user to get a better price as the call volume increases each month. This can be added on one ore more thresholds so the more he/she talks the cheaper the calls.
|
||||
|
||||
Finally bonuses can be rewarded to users who received a certain volume of calls.
|
||||
|
||||
2
docs/miscellaneous.rst
Normal file
2
docs/miscellaneous.rst
Normal file
@@ -0,0 +1,2 @@
|
||||
8. Miscellaneous
|
||||
================
|
||||
@@ -1,193 +0,0 @@
|
||||
Tutorial
|
||||
========
|
||||
|
||||
The general steps to get up and running with CGRateS are:
|
||||
|
||||
#. Create CSV files containing the initial data for CGRateS, see :ref:`data-importing`.
|
||||
#. Load the data in the databases using the loader tool.
|
||||
#. Start the balancer or rater and connect it to the call switch, see Running_.
|
||||
#. Start one ore more raters.
|
||||
#. Make API calls to the balancer/rater or just let the session manager do the work.
|
||||
|
||||
Instalation
|
||||
-----------
|
||||
Using packages
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Using source
|
||||
~~~~~~~~~~~~
|
||||
|
||||
After the go environment is installed_ and setup_ just issue the following commands:
|
||||
::
|
||||
|
||||
go get github.com/cgrates/cgrates
|
||||
|
||||
This will install the sources and compile all available tools
|
||||
|
||||
.. _installed: http://golang.org/doc/install
|
||||
.. _setup: http://golang.org/doc/code.html
|
||||
|
||||
|
||||
Running
|
||||
-------
|
||||
|
||||
The CGRateS suite is formed by three tools described bellow. We'll start with the most important one, cgr-rater which is configured with an ini style configuration file.
|
||||
|
||||
|
||||
cgr-rater
|
||||
~~~~~~~~~
|
||||
The cgr-rater can be provided with the balancer server address and can be configured to listen to a specific interface and port. It is an auxiliary tool only and is meant to be used for housekeeping duties (better alternative to curl inspection).
|
||||
::
|
||||
|
||||
rif@grace:~$ cgr-rater -help
|
||||
Usage of cgr-rater:
|
||||
-config="rater_standalone.config": Configuration file location.
|
||||
-version=false: Prints the application version.
|
||||
|
||||
|
||||
:Example: cgr-rater -config=full.config
|
||||
|
||||
Bellow there is a full configuration file:
|
||||
|
||||
::
|
||||
|
||||
[global]
|
||||
datadb_type = redis # The main database: redis|mongo|postgres.
|
||||
datadb_host = 127.0.0.1:6379 # The host to connect to. Values that start with / are for UNIX domain sockets.
|
||||
datadb_name = 10 # The name of the database to connect to.
|
||||
logdb_type = mongo # The logging database: redis|mongo|postgres|same.
|
||||
logdb_host = localhost # The host to connect to. Values that start with / are for UNIX domain sockets.
|
||||
logdb_name = cgrates # The name of the database to connect to.
|
||||
|
||||
[balancer]
|
||||
enabled = false # Start balancer server
|
||||
listen = 127.0.0.1:2001 # Balancer listen interface
|
||||
rpc_encoding = gob # Use json or gob for RPC encoding
|
||||
|
||||
[rater]
|
||||
enabled = true # Start the rating service
|
||||
listen = 127.0.0.1:2001 # Listening address host:port, internal for internal communication only
|
||||
balancer = disabled # If defined it will register to balancer as worker
|
||||
rpc_encoding = gob # Use json or gob for RPC encoding
|
||||
|
||||
[mediator]
|
||||
enabled = true # Start the mediator service
|
||||
cdr_path = /var/log/freeswitch # Freeswitch Master CSV CDR path
|
||||
cdr_out_path = /var/log/freeswitch/out # Freeswitch Master CSV CDR path
|
||||
rater = internal # Address where to access rater. Can be internal, direct rater address or the address of a balancer
|
||||
rpc_encoding = gob # Use json or gob for RPC encoding
|
||||
skipdb = true # Do not look in the database for logged cdrs, ask rater directly
|
||||
pseudo_prepaid = false # debit the call cost from user balance when getting the cost
|
||||
|
||||
[scheduler]
|
||||
enabled = true # Start the schedule service
|
||||
|
||||
[session_manager]
|
||||
enabled = true # Start the session manager service
|
||||
switch_type = freeswitch # The switch type to be used
|
||||
debit_period = 10 # The number of seconds to be debited in advance during a call
|
||||
rater = 127.0.0.1:2000 # Address where to access rater. Can be internal, direct rater address or the address of a balancer
|
||||
rpc_encoding = gob # Use json or gob for RPC encoding
|
||||
|
||||
[freeswitch]
|
||||
server = localhost:8021 # Freeswitch address host:port
|
||||
pass = ClueCon # Freeswtch address host:port
|
||||
direction_index = 0
|
||||
tor_index = 1
|
||||
tenant_index = 2
|
||||
subject_index = 3
|
||||
account_index = 4
|
||||
destination_index = 5
|
||||
time_start_index = 6
|
||||
time_end_index = 7
|
||||
|
||||
|
||||
There are various sections in the configuration file that define various services that the cgr-rater process can provide. If you are not interested in a certain service you can either leave it in the configuration with the enabled option set to false or remove the section entirely to reduce clutter.
|
||||
|
||||
The global sections define the databases to be used with used by CGRateS. The second database is used for logging the debit operations and various acctions operated on the accounts. The two databases can be the same type or different types. Currently we sopport redis, mongo and postgres (work in progress).
|
||||
|
||||
The balancer will open a JSON RPC server and an HTTP server ready for taking external requests. It will also open a rater server on witch the raters will register themselves when they start.
|
||||
|
||||
Session manager connects and monitors the freeswitch server issuing API request to other CGRateS components. It can run in standalone mode for minimal system configuration. It logs the calls information to a postgres database in order to be used by the mediator tool.
|
||||
|
||||
The scheduler is loading the timed actions form database and executes them as appropriate, It will execute all run once actions as they are loaded. It will reload all the action timings from the database when it received system HUP signal (pkill -1 cgr-rater).
|
||||
|
||||
The mediator parses the call logs written in the logging database by the session manager and writes the call costs to a freeswitch CDR file.
|
||||
|
||||
The structure of the table (as an SQL command) is the following::
|
||||
::
|
||||
|
||||
CREATE TABLE callcosts (
|
||||
uuid varchar(80) primary key,
|
||||
source varchar(32),
|
||||
direction varchar(32),
|
||||
tenant varchar(32),
|
||||
tor varchar(32),
|
||||
subject varchar(32),
|
||||
account varchar(32),
|
||||
destination varchar(32),
|
||||
cost real,
|
||||
conect_fee real,
|
||||
timespans text
|
||||
);
|
||||
|
||||
|
||||
|
||||
cgr-loader
|
||||
~~~~~~~~~~
|
||||
|
||||
This tool is used for importing the data from CSV files into the CGRateS database system. The structure of the CSV files is described in the :ref:`data-importing` chapter.
|
||||
|
||||
::
|
||||
|
||||
rif@grace:~$ cgr-loader -help
|
||||
Usage of cgr-loader:
|
||||
-dbhost="localhost": The database host to connect to.
|
||||
-dbname="10": he name/number of the database to connect to.
|
||||
-dbpass="": The database user's password.
|
||||
-dbport="6379": The database port to bind to.
|
||||
-dbtype="redis": The type of the database (redis|mongo|postgres)
|
||||
-dbuser="": The database user to sign in as.
|
||||
-flush=false: Flush the database before importing
|
||||
-path=".": The path containing the data files
|
||||
-version=false: Prints the application version.
|
||||
|
||||
|
||||
:Example: cgr-loader -flush
|
||||
|
||||
|
||||
cgr-console
|
||||
~~~~~~~~~~~
|
||||
The cgr-console is a command line tool used to access the balancer (or the rater directly) to call all the API methods offered by CGRateS. It is
|
||||
::
|
||||
|
||||
cgrrif@grace:~$ cgr-console -help
|
||||
Usage of cgr-console:
|
||||
-account="": The the user balance to be used
|
||||
-amount=0: Amount for different operations
|
||||
-cmd="": server address host:port
|
||||
-dest="": Call destination
|
||||
-direction="OUT": Call direction
|
||||
-end="": Time end (format: 2012-02-09T00:00:00Z)
|
||||
-json=false: Use JSON for RPC encoding.
|
||||
-server="127.0.0.1:2001": server address host:port
|
||||
-start="": Time start (format: 2012-02-09T00:00:00Z)
|
||||
-subject="": The client who made the call
|
||||
-tenant="": Tenant identificator
|
||||
-tor="0": Type of record
|
||||
-version=false: Prints the application version.
|
||||
|
||||
:Example: cgr-console -cmd=getcost -subject=rif -tenant=vdf -dest=419 -start=2012-02-09T00:00:00Z -end=2012-02-09T00:01:00Z
|
||||
|
||||
List of commands:
|
||||
- getcost
|
||||
- debit
|
||||
- maxdebit
|
||||
- getmaxsessiontime
|
||||
- debitbalance
|
||||
- debitsms
|
||||
- debitseconds
|
||||
- addrecievedcallseconds
|
||||
- flushcache
|
||||
- status
|
||||
- shutdown
|
||||
2
docs/tutorials.rst
Normal file
2
docs/tutorials.rst
Normal file
@@ -0,0 +1,2 @@
|
||||
7. Tutorials
|
||||
============
|
||||
Reference in New Issue
Block a user