uppal/cgrates
1
0
Fork 1
mirror of https://github.com/cgrates/cgrates.git synced 2026-02-11 18:16:24 +05:00
Code Issues Packages Projects Releases Wiki Activity

Updating documentation with cdrstats, derived_charging

Browse Source
This commit is contained in:
DanB
2014-08-17 14:23:17 +02:00
parent 988f3c6bf2
commit 616a81279e
10 changed files with 483 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/advanced.rst
View File

@@ -8,6 +8,8 @@
cdrserver
cdrclient
cdrexporter
cdrstats
derived_charging
history
ratinglogic

63
docs/cdrclient.rst
View File

@@ -18,8 +18,61 @@ Principles behind functionality:
- For every file processed, extract the information based on configuration and post it via configured mechanism to CDRS.
- The fields extracted out of each CDR row are the same ones depicted in the CDRS documentation (following primary and extra fields concept).
- Once the file processing completes, move it in it's original format in another folder (OUT) in order to avoid re-processing. Here it's worth mentioning the auto-detection of duplicated CDRs at server side based on accid and host fields.
- Advanced configuration like forking a number of simultaneous client instances monitoring different folders possible through the use of *.xml* configuration.
For the moment we support processing CDRs in the following formats:
Import Templates
----------------
To specifiy custom imports (for various sources) one can specify *Import Templates*. These are definable within both *.cfg* as well as *.xml* advanced configuration files.
For increased flexibility the Import Template can be defined using CGR-RSR fields capturing both ReGexp as well as static rules. The static values will be way faster in processing but limited in functionality.
CGR-RSR Regexp Rule
~~~~~~~~~~~~~~~~~~~
Format:
::
~field_id:s/regexp_search_and_capture_rule/output_teplate/
Example of usage:
::
Input CDR field:
{
"account": "First-Account123"
}
Capture Rule:
~account:s/^*+(Account123)$/$1-processed/
Result after processing:
{
"account": "Account123-processed"
}
CGR-RSR Static Rule
~~~~~~~~~~~~~~~~~~~
Format:
::
^field_id:static_value
Example of usage:
::
Input CDR field:
{
"account": "First-Account123"
}
Capture Rule:
^account:MasterAccount
Result after processing:
{
"account": "MasterAccount"
}
CDR Formats supported:
CDR .CSV
--------
@@ -28,10 +81,6 @@ Most widely used format by Telecom Switches.
Light to read and generic to process.
CDRC should be able to process in this way any .csv CDR, independent of the Telecom Switch generating them. Incompatibilities here can come out of answer time and duration formats which can vary between CDR writer implementations.
As answer time we support a number of formats already - rfc3339, SQL/MySQL, unix timestamp. As duration we support nanoseconds granularity in our code, however if time unit is not specified (eg: ms, s, m, h), we assume CDR duration will be in seconds.
CDR fields are extracted based on configured indexes in a file row (0 represents first field).
A particular configuration format it is represented by extra fields which need not only to be extracted by row index but also to be named since .csv format does not save field names/labels. CDRC uses the following convention for extra fields in the configuration: *<index_extrafield_1>:<label_extrafield_1>[,<index_extrafield_n>:<label_extrafield_n>]...*.
As answer time we support a number of formats already - rfc3339, SQL/MySQL, unix timestamp. As duration we support nanoseconds granularity in our code. Time unit can be specified (eg: ms, s, m, h), or if missing, will default to nanoseconds.
In case of *.csv* files the Import Template will contain indexes for the possition where primary fields are located (0 representing the first field) and fieldname/position format for extra fields which need not only to be extracted by row index but also to be named since .csv format does not save field names/labels. CDRC uses the following convention for extra fields in the configuration: *<label_extrafield_1>:<index_extrafield_1>[...,<label_extrafield_n>:<index_extrafield_n>]...*.

102
docs/cdrexporter.rst
View File

@@ -5,7 +5,60 @@ Component to retrieve rated CDRs from internal CDRs database.
Although nowadays it is custom to read a storage/database with tools, we do not recommend doing it so due to possibility that reads can slow down complete rating system. For this purpose we have created exporter plugins which are meant to work in tight relationship with CGRateS internal components in order to best optimize performance and avoid system locks.
For the moment we support exporting CDRs over the following interfaces:
Export Templates
----------------
For advanced needs CGRateS Export Templates are configurable via *.cfg*, *.xml* as well as directly within RPC call requesting the export to be performed.
Inside each Export Template one can either specify simple CDR field ids or use CGR-RSR fields capturing both Regexp as well as static rules.
CGR-RSR Regexp Rule
~~~~~~~~~~~~~~~~~~~
Format:
::
~field_id:s/regexp_search_and_capture_rule/output_teplate/
Example of usage:
::
Input CDR field:
{
"account": "First-Account123"
}
Capture Rule:
~account:s/^*+(Account123)$/$1-processed/
Result after processing:
{
"account": "Account123-processed"
}
CGR-RSR Static Rule
~~~~~~~~~~~~~~~~~~~
Format:
::
^field_id:static_value
Example of usage:
::
Input CDR field:
{
"account": "First-Account123"
}
Capture Rule:
^account:MasterAccount
Result after processing:
{
"account": "MasterAccount"
}
Export interfaces implemented:
CGR-CSV
@@ -21,29 +74,31 @@ Principles behind exports:
rpc.call("ApierV1.ExportCsvCdrs",{"TimeStart":"1383823746","TimeEnd":"1383833746"} )
- On each export call there will be a .csv format file generated using ',' as separator. Location of the export folder is definable inside *cgrates.cfg*.
- File name of the export will appear like: *cdrs_$(timestamp).csv* where $(timestamp) will be replaced by unix timestamp of the server running the export process.
- On each export call there will be a .csv format file generated using configured separator. Location of the export folder is definable inside *cgrates.cfg*.
- File name of the export will appear like: *cdrs_$(timestamp).csv* where $(timestamp) will be replaced by unix timestamp of the server running the export process or requested via API call.
- Each exported file will have as content all the CDRs inside time interval defined in the API call. Both TimeStart and TimeEnd are optional, hence being able to obtain a full export of the available CDRs with one API call.
- To be noted here that CGRateS does not keep anywhere a history of exports, hence it is the responsibility of the system administrator to make sure that his exports are not doubled.
- Each line within the exported file will follow an internally predefined template:
- If not otherwise defined, each line within the exported file will follow an internally predefined template:
cgrid,mediation_runid,tor,accid,reqtype,direction,tenant,category,account,subject,destination,setup_time,answer_time,usage,cost
::
$(cgrid),$(accid),$(cdrhost),$(reqtype),$(direction),$(tenant),$(tor),$(account),$(subject),$(destination),$(answer_time),$(duration),$(cost),$(extra_cdr_fields)
$(cgrid),$(mediation_runid),$(tor),$(accid),$(reqtype),$(direction),$(direction),$(tenant),$(category),$(account),$(subject),$(destination),$(setup_time),$(answer_time),$(usage),$(cost)
The significance of the fields exported:
- cgrid: unique identifier for one CDR within CGRateS records
- accid: represents the unique accounting id given by the switch generating the CDR
- cdrhost: represents the ip of the host generating the CDR
- reqtype: matching the supported request types by the CGRateS
- direction: matching the supported direction identifiers of the CGRateS
- tenant: tenant whom this call belongs
- tor: TypeOfRecord for the CDR
- tor: type of record, meta-field, should map to one of the TORs hardcoded inside the server <*voice|*data|*sms>
- accid: represents the unique accounting id given by the telecom switch generating the CDR
- cdrhost: represents the IP address of the host generating the CDR (automatically populated by the server)
- cdrsource: formally identifies the source of the CDR (free form field)
- reqtype: matching the supported request types by the **CGRateS**, accepted values are hardcoded in the server <prepaid|postpaid|pseudoprepaid|rated>.
- direction: matching the supported direction identifiers of the CGRateS <*out>
- tenant: tenant whom this record belongs
- category: free-form filter for this record, matching the category defined in rating profiles.
- account: account id (accounting subsystem) the record should be attached to
- subject: rating subject (rating subsystem) this call should be attached to
- subject: rating subject (rating subsystem) this record should be attached to
- destination: destination to be charged
- answer_time: time of the record (in case of tor=call this would be answer time of the call). This will arrive as either unix timestamp or datetime RFC3339 compatible.
- duration: used in case of tor=call like, representing the total duration of the call
- setup_time: set-up time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
- answer_time: answer time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
- usage: event usage information (eg: in case of tor=*voice this will represent the total duration of a call)
- extra_cdr_fields:
- selected list of cdr_extra fields via *cgrates.cfg* configuration or
- alphabetical order of the cdr extra fields stored in cdr_extra table
@@ -52,5 +107,16 @@ Principles behind exports:
Sample CDR export file content which was made available at path: */var/log/cgrates/cdr/out/cgr/csv/cdrs_1384104724.csv*
::
649ac3f5a7de07993448ed4354f484669c7df383,bsbfdsaf,192.168.1.1,rated,*out,itsyscom.com,call,dan,dan,+4986517174963,2013-11-07 09:42:26 +0100 CET,10,-1.0000,Jitsi
7d5768f6b50c413ec938481d65c8d74fce38fb06,bvbfdsaf,192.168.1.1,rated,*out,itsyscom.com,call,dan,dan,+4986517174963,2013-11-07 12:29:06 +0100 CET,10,-1.0000,Jitsi
dbafe9c8614c785a65aabd116dd3959c3c56f7f6,default,*voice,dsafdsaf,rated,*out,cgrates.org,call,1001,1001,1002,2013-11-07T08:42:25Z,2013-11-07T08:42:26Z,10000000000,1.0100
CGR-FWV
-------
Fixed width form of export CDR. Advanced template configuration available via *.xml* configuration file.
Hybrid CSV-FWV
--------------
For advanced needs **CGRateS** supports exporting the CDRs as combination between *.csv* and *.fwv* formats.

67
docs/cdrserver.rst
View File

@@ -1,42 +1,44 @@
CDR Server
==========
An important component of every rating system is represented by the CDR Server. CGRateS includes an out of the box CDR Server component, controlable in the configuration file and supporting multiple interfaces for CDR feeds. This component makes the CDRs real-time accessible (raported to the time of receiving them) to CGRateS subsystems.
An important component of every rating system is represented by the CDR Server. CGRateS includes an out of the box CDR Server component, controlable in the configuration file and supporting multiple interfaces for CDR feeds. This component makes the CDRs real-time accessible (influenced by the time of receiving them) to CGRateS subsystems.
For the moment we support receiving CDRs over the following interfaces:
Following interfaces are supported:
CDR-CGR
-------
Available as handler within http server, it represents the lightest and fastest way to get CDRs inside CGRateS in real-time.
Available as handler within http server.
To feed CDRs in via this interface, one must use url of the form: <http://$ip_configured:$port_configured/cgr>.
The CDR fields are received via http form (although for simplicity we support inserting them within query parameters as well) and are expected to be urlencoded in order to transport special characters reliably. All fields are expected by CGRateS as string, particular conversions being done on processing each CDR.
The fields received are splitt into two different categories based on CGRateS interest in them:
The fields received are split into two different categories based on CGRateS interest in them:
Primary fields: the fields which CGRateS needs for it's own operations and are stored into cdrs_primary table of storDb.
- accid: represents the unique accounting id given by the switch generating the CDR
- cdrhost: represents the ip of the host generating the CDR
- cdrsource: formally identifies the source of the CDR
- reqtype: matching the supported request types by the CGRateS
- direction: matching the supported direction identifiers of the CGRateS
- tenant: tenant whom this call belongs
- tor: TypeOfRecord for the CDR
- tor: type of record, meta-field, should map to one of the TORs hardcoded inside the server <*voice|*data|*sms>
- accid: represents the unique accounting id given by the telecom switch generating the CDR
- cdrhost: represents the IP address of the host generating the CDR (automatically populated by the server)
- cdrsource: formally identifies the source of the CDR (free form field)
- reqtype: matching the supported request types by the **CGRateS**, accepted values are hardcoded in the server <prepaid|postpaid|pseudoprepaid|rated>.
- direction: matching the supported direction identifiers of the CGRateS <*out>
- tenant: tenant whom this record belongs
- category: free-form filter for this record, matching the category defined in rating profiles.
- account: account id (accounting subsystem) the record should be attached to
- subject: rating subject (rating subsystem) this call should be attached to
- subject: rating subject (rating subsystem) this record should be attached to
- destination: destination to be charged
- answer_time: time of the record (in case of tor=call this would be answer time of the call). Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
- duration: used in case of tor=call like, representing the total duration of the call
- setup_time: set-up time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
- answer_time: answer time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
- usage: event usage information (eg: in case of tor=*voice this will represent the total duration of a call)
Extra fields: any field coming in via the http request and not a member of primary fields list. These fields are stored as json encoded into *cdrs_extra* table of storDb.
Example of sample CDR generated simply using curl:
::
curl --data "curl --data "accid=iiaasbfdsaf&cdrhost=192.168.1.1&cdrsource=curl_cdr&reqtype=rated&direction=*out&tenant=192.168.56.66&tor=call&account=dan&subject=dan&destination=%2B4986517174963&answer_time=1383813746&duration=1&sip_user=Jitsi&subject2=1003" http://127.0.0.1:2080/cgr
curl --data "curl --data "tor=*voice&accid=iiaasbfdsaf&cdrhost=192.168.1.1&cdrsource=curl_cdr&reqtype=rated&direction=*out&tenant=192.168.56.66&category=call&account=dan&subject=dan&destination=%2B4986517174963&answer_time=1383813746&usage=1&sip_user=Jitsi&subject2=1003" http://127.0.0.1:2080/cgr
CDR-FS_JSON
@@ -66,3 +68,38 @@ The mechanism of extracting CDR information out of JSON encoded CDR received fro
- Fields stored at request in cdr_extra and definable in configuration file under *extra_fields*.
- Once the content will be filtered, the real CDR object will be processed, stored into storDb under *cdrs_primary* and *cdrs_extra* tables and, if configured, it will be passed further for mediation.
CDR-RPC
-------
Available as RPC handler on top of CGR APIs exposed (in-process as well as GOB-RPC and JSON-RPC). This interface is used for example by CGR-SM component capturing the CDRs over event interface (eg: OpenSIPS or FreeSWITCH-ZeroConfig scenario)
The RPC function signature looks like this:
::
CDRSV1.ProcessCdr(cdr *utils.StoredCdr, reply *string) error
The simplified StoredCdr object is represented by following:
::
type StoredCdr struct {
CgrId string
OrderId int64 // Stor order id used as export order id
TOR string // type of record, meta-field, should map to one of the TORs hardcoded inside the server <*voice|*data|*sms>
AccId string // represents the unique accounting id given by the telecom switch generating the CDR
CdrHost string // represents the IP address of the host generating the CDR (automatically populated by the server)
CdrSource string // formally identifies the source of the CDR (free form field)
ReqType string // matching the supported request types by the **CGRateS**, accepted values are hardcoded in the server <prepaid|postpaid|pseudoprepaid|rated>.
Direction string // matching the supported direction identifiers of the CGRateS <*out>
Tenant string // tenant whom this record belongs
Category string // free-form filter for this record, matching the category defined in rating profiles.
Account string // account id (accounting subsystem) the record should be attached to
Subject string // rating subject (rating subsystem) this record should be attached to
Destination string // destination to be charged
SetupTime time.Time // set-up time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
AnswerTime time.Time // answer time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
Usage time.Duration // event usage information (eg: in case of tor=*voice this will represent the total duration of a call)
ExtraFields map[string]string // Extra fields to be stored in CDR
}

60
docs/cdrstats.rst Normal file
View File

@@ -0,0 +1,60 @@
CDR Stats Server
================
Collects CDRs from various sources (eg: CGR-CDRS, CGR-Mediator, CGR-SM, third-party CDR source via RPC) and builds real-time stats based on them. Each StatsQueue has attached *ActionTriggers* with monitoring and actions capabilities.
Principles of functionality:
- Standalone component (can be started individually on remote hardware, isolated form other CGRateS compoenents).
- Performance oriented. Should be able to process tens of thousands of CDRs per second.
- No database storage involved, cache driven. If archiving is requested, this should be achieved through external means (eg: an external process regularly querying specific StatsQueue).
- Stats are build within *StatsQueues* a CDR Stats Server being able to support unlimited number of StatsQueues. Each CDR will be passed to all of StatsQueues available and will be processed by individual StatsQueue based on configuration.
- Stats will be build inside Metrics (eg: ASR, ACD, ACC) and attached to specific StatsQueue.
- Each StatsQueue will have attached one *ActionTriggers* profile which will monitor Metrics values and react on thresholds reached (unlimited number of thresholds and reactions configurable).
- CDRs are processed by StatsQueues if they pass CDR field filters.
- CDRs are auto-removed from StatsQueues in a *fifo* manner if the QueueLength is reached or if they do not longer fit within TimeWindow defined.
Configuration
-------------
Individual StatsQueue configurations are loaded inside TariffPlan defitions, one configuration object is internally represented as:
::
type CdrStats struct {
Id string // Config id, unique per config instance
QueueLength int // Number of items in the stats buffer
TimeWindow time.Duration // Will only keep the CDRs who's call setup time is not older than time.Now()-TimeWindow
Metrics []string // ASR, ACD, ACC
SetupInterval []time.Time // CDRFieldFilter on SetupInterval, 2 or less items (>= start interval,< stop_interval)
TOR []string // CDRFieldFilter on TORs
CdrHost []string // CDRFieldFilter on CdrHosts
CdrSource []string // CDRFieldFilter on CdrSources
ReqType []string // CDRFieldFilter on ReqTypes
Direction []string // CDRFieldFilter on Directions
Tenant []string // CDRFieldFilter on Tenants
Category []string // CDRFieldFilter on Categories
Account []string // CDRFieldFilter on Accounts
Subject []string // CDRFieldFilter on Subjects
DestinationPrefix []string // CDRFieldFilter on DestinationPrefixes
UsageInterval []time.Duration // CDRFieldFilter on UsageInterval, 2 or less items (>= Usage, <Usage)
MediationRunIds []string // CDRFieldFilter on MediationRunIds
RatedAccount []string // CDRFieldFilter on RatedAccounts
RatedSubject []string // CDRFieldFilter on RatedSubjects
CostInterval []float64 // CDRFieldFilter on CostInterval, 2 or less items, (>=Cost, <Cost)
Triggers ActionTriggerPriotityList
}
ExternalQueries
---------------
The Metrics calculated are available to be real-time queried via RPC methods.
To facilitate interaction there are four commands built in the provided *cgr-console* tool:
- *cdrstats_queueids*: returns the queue ids processing CDR Stats.
- *cdrstats_metrics*: returns metrics calculated within specific CDRStatsQueue.
- *cdrstats_reload*: reloads the CdrStats configurations out of DataDb.
- *cdrstats_reset*: resets calculated metrics for one specific or all StatsQueues.

256
docs/cgrates_cfg.rst
View File

@@ -8,115 +8,169 @@ Bellow is the default configuration file which comes hardcoded into cgr-engine,
::
[global]
# ratingdb_type = redis # Rating subsystem database: <redis>.
# ratingdb_host = 127.0.0.1 # Rating subsystem database host address.
# ratingdb_port = 6379 # Rating subsystem port to reach the database.
# ratingdb_name = 10 # Rating subsystem database name to connect to.
# ratingdb_user = # Rating subsystem username to use when connecting to database.
# ratingdb_passwd = # Rating subsystem password to use when connecting to database.
# accountdb_type = redis # Accounting subsystem database: <redis>.
# accountdb_host = 127.0.0.1 # Accounting subsystem database host address.
# accountdb_port = 6379 # Accounting subsystem port to reach the database.
# accountdb_name = 11 # Accounting subsystem database name to connect to.
# accountdb_user = # Accounting subsystem username to use when connecting to database.
# accountdb_passwd = # Accounting subsystem password to use when connecting to database.
# stordb_type = mysql # Stor database type to use: <mysql>
# stordb_host = 127.0.0.1 # The host to connect to. Values that start with / are for UNIX domain sockets.
# stordb_port = 3306 # The port to reach the logdb.
# stordb_name = cgrates # The name of the log database to connect to.
# stordb_user = cgrates # Username to use when connecting to stordb.
# stordb_passwd = CGRateS.org # Password to use when connecting to stordb.
# dbdata_encoding = msgpack # The encoding used to store object data in strings: <msgpack|json>
# rpc_json_listen = 127.0.0.1:2012 # RPC JSON listening address
# rpc_gob_listen = 127.0.0.1:2013 # RPC GOB listening address
# http_listen = 127.0.0.1:2080 # HTTP listening address
# default_reqtype = rated # Default request type to consider when missing from requests: <""|prepaid|postpaid|pseudoprepaid|rated>.
# default_tor = call # Default Type of Record to consider when missing from requests.
# default_tenant = cgrates.org # Default Tenant to consider when missing from requests.
# default_subject = cgrates # Default rating Subject to consider when missing from requests.
# rounding_method = *middle # Rounding method for floats/costs: <*up|*middle|*down>
# rounding_decimals = 4 # Number of decimals to round float/costs at
# ratingdb_type = redis # Rating subsystem database: <redis>.
# ratingdb_host = 127.0.0.1 # Rating subsystem database host address.
# ratingdb_port = 6379 # Rating subsystem port to reach the database.
# ratingdb_name = 10 # Rating subsystem database name to connect to.
# ratingdb_user = # Rating subsystem username to use when connecting to database.
# ratingdb_passwd = # Rating subsystem password to use when connecting to database.
# accountdb_type = redis # Accounting subsystem database: <redis>.
# accountdb_host = 127.0.0.1 # Accounting subsystem database host address.
# accountdb_port = 6379 # Accounting subsystem port to reach the database.
# accountdb_name = 11 # Accounting subsystem database name to connect to.
# accountdb_user = # Accounting subsystem username to use when connecting to database.
# accountdb_passwd = # Accounting subsystem password to use when connecting to database.
# stordb_type = mysql # Stor database type to use: <mysql>
# stordb_host = 127.0.0.1 # The host to connect to. Values that start with / are for UNIX domain sockets.
# stordb_port = 3306 # The port to reach the logdb.
# stordb_name = cgrates # The name of the log database to connect to.
# stordb_user = cgrates # Username to use when connecting to stordb.
# stordb_passwd = CGRateS.org # Password to use when connecting to stordb.
# dbdata_encoding = msgpack # The encoding used to store object data in strings: <msgpack|json>
# rpc_json_listen = 127.0.0.1:2012 # RPC JSON listening address
# rpc_gob_listen = 127.0.0.1:2013 # RPC GOB listening address
# http_listen = 127.0.0.1:2080 # HTTP listening address
# default_reqtype = rated # Default request type to consider when missing from requests: <""|prepaid|postpaid|pseudoprepaid|rated>.
# default_category = call # Default Type of Record to consider when missing from requests.
# default_tenant = cgrates.org # Default Tenant to consider when missing from requests.
# default_subject = cgrates # Default rating Subject to consider when missing from requests.
# rounding_decimals = 10 # System level precision for floats
# http_skip_tls_veify = false # If enabled Http Client will accept any TLS certificate
# xmlcfg_path = # Path towards additional config defined in xml file
[balancer]
# enabled = false # Start Balancer service: <true|false>.
[balancer]
# enabled = false # Start Balancer service: <true|false>.
[rater]
# enabled = false # Enable RaterCDRSExportPath service: <true|false>.
# balancer = # Register to Balancer as worker: <""|internal|127.0.0.1:2013>.
[rater]
# enabled = false # Enable RaterCDRSExportPath service: <true|false>.
# balancer = # Register to Balancer as worker: <""|internal|127.0.0.1:2013>.
[scheduler]
# enabled = false # Starts Scheduler service: <true|false>.
[scheduler]
# enabled = false # Starts Scheduler service: <true|false>.
[cdrs]
# enabled = false # Start the CDR Server service: <true|false>.
# extra_fields = # Extra fields to store in CDRs
# mediator = # Address where to reach the Mediator. Empty for disabling mediation. <""|internal>
[cdrs]
# enabled = false # Start the CDR Server service: <true|false>.
# extra_fields = # Extra fields to store in CDRs for non-generic CDRs
# mediator = # Address where to reach the Mediator. Empty for disabling mediation. <""|internal>
# cdrstats = # Address where to reach the cdrstats service: <internal|x.y.z.y:1234>
# store_disable = false # When true, CDRs will not longer be saved in stordb, useful for cdrstats only scenario
[cdre]
# cdr_format = csv # Exported CDRs format <csv>
# extra_fields = # List of extra fields to be exported out in CDRs
# export_dir = /var/log/cgrates/cdr/cdrexport/csv # Path where the exported CDRs will be placed
[cdre]
# cdr_format = csv # Exported CDRs format <csv>
# data_usage_multiply_factor = 0.0 # Multiply data usage before export (eg: convert from KBytes to Bytes)
# cost_multiply_factor = 0.0 # Multiply cost before export (0.0 to disable), eg: add VAT
# cost_rounding_decimals = -1 # Rounding decimals for Cost values. -1 to disable rounding
# cost_shift_digits = 0 # Shift digits in the cost on export (eg: convert from EUR to cents)
# mask_destination_id = # Destination id containing called addresses to be masked on export
# mask_length = 0 # Length of the destination suffix to be masked
# export_dir = /var/log/cgrates/cdre # Path where the exported CDRs will be placed
# export_template = cgrid,mediation_runid,tor,accid,reqtype,direction,tenant,category,account,subject,destination,setup_time,answer_time,usage,cost
# Exported fields template <""|fld1,fld2|*xml:instance_name>
[cdrc]
# enabled = false # Enable CDR client functionality
# cdrs = internal # Address where to reach CDR server. <internal|127.0.0.1:2080>
# run_delay = 0 # Sleep interval in seconds between consecutive runs, 0 to use automation via inotify
# cdr_type = csv # CDR file format <csv|freeswitch_csv>.
# csv_separator = , # Separator used in case of csv files. One character only supported and needs to be right after equal sign
# cdr_in_dir = /var/log/cgrates/cdrc/in # Absolute path towards the directory where the CDRs are stored.
# cdr_out_dir = /var/log/cgrates/cdrc/out # Absolute path towards the directory where processed CDRs will be moved.
# cdr_source_id = csv # Free form field, tag identifying the source of the CDRs within CGRS database.
# tor_field = 2 # TypeOfRecord field identifier. Use index number in case of .csv cdrs.
# accid_field = 3 # Accounting id field identifier. Use index number in case of .csv cdrs.
# reqtype_field = 4 # Request type field identifier. Use index number in case of .csv cdrs.
# direction_field = 5 # Direction field identifier. Use index numbers in case of .csv cdrs.
# tenant_field = 6 # Tenant field identifier. Use index numbers in case of .csv cdrs.
# category_field = 7 # Type of Record field identifier. Use index numbers in case of .csv cdrs.
# account_field = 8 # Account field identifier. Use index numbers in case of .csv cdrs.
# subject_field = 9 # Subject field identifier. Use index numbers in case of .csv CDRs.
# destination_field = 10 # Destination field identifier. Use index numbers in case of .csv cdrs.
# setup_time_field = 11 # Setup time field identifier. Use index numbers in case of .csv cdrs.
# answer_time_field = 12 # Answer time field identifier. Use index numbers in case of .csv cdrs.
# usage_field = 13 # Usage field identifier. Use index numbers in case of .csv cdrs.
# extra_fields = # Extra fields identifiers. For .csv, format: <label_extrafield_1>:<index_extrafield_1>[...,<label_extrafield_n>:<index_extrafield_n>]
[cdrc]
# enabled = false # Enable CDR client functionality
# cdrs = internal # Address where to reach CDR server. <internal|127.0.0.1:2080>
# cdrs_method = http_cgr # Mechanism to use when posting CDRs on server <http_cgr>
# run_delay = 0 # Sleep interval in seconds between consecutive runs, 0 to use automation via inotify
# cdr_type = csv # CDR file format <csv|freeswitch_csv>.
# cdr_in_dir = /var/log/cgrates/cdr/cdrc/in # Absolute path towards the directory where the CDRs are stored.
# cdr_out_dir = /var/log/cgrates/cdr/cdrc/out # Absolute path towards the directory where processed CDRs will be moved.
# cdr_source_id = freeswitch_csv # Free form field, tag identifying the source of the CDRs within CGRS database.
# accid_field = 0 # Accounting id field identifier. Use index number in case of .csv cdrs.
# reqtype_field = 1 # Request type field identifier. Use index number in case of .csv cdrs.
# direction_field = 2 # Direction field identifier. Use index numbers in case of .csv cdrs.
# tenant_field = 3 # Tenant field identifier. Use index numbers in case of .csv cdrs.
# tor_field = 4 # Type of Record field identifier. Use index numbers in case of .csv cdrs.
# account_field = 5 # Account field identifier. Use index numbers in case of .csv cdrs.
# subject_field = 6 # Subject field identifier. Use index numbers in case of .csv CDRs.
# destination_field = 7 # Destination field identifier. Use index numbers in case of .csv cdrs.
# answer_time_field = 8 # Answer time field identifier. Use index numbers in case of .csv cdrs.
# duration_field = 9 # Duration field identifier. Use index numbers in case of .csv cdrs.
# extra_fields = # Extra fields identifiers. For .csv, format: <label_extrafield_1>:<index_extrafield_1>[...,<label_extrafield_n>:<index_extrafield_n>]
[mediator]
# enabled = false # Starts Mediator service: <true|false>.
# reconnects = 3 # Number of reconnects to rater/cdrs before giving up.
# rater = internal # Address where to reach the Rater: <internal|x.y.z.y:1234>
# cdrstats = internal # Address where to reach the cdrstats service: <internal|x.y.z.y:1234>
# store_disable = false # When true, CDRs will not longer be saved in stordb, useful for cdrstats only scenario
[mediator]
# enabled = false # Starts Mediator service: <true|false>.
# rater = internal # Address where to reach the Rater: <internal|x.y.z.y:1234>
# rater_reconnects = 3 # Number of reconnects to rater before giving up.
# run_ids = # Identifiers of each extra mediation to run on CDRs
# reqtype_fields = # Name of request type fields to be used during extra mediation. Use index number in case of .csv cdrs.
# direction_fields = # Name of direction fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# tenant_fields = # Name of tenant fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# tor_fields = # Name of tor fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# account_fields = # Name of account fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# subject_fields = # Name of fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# destination_fields = # Name of destination fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# answer_time_fields = # Name of time_answer fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
# duration_fields = # Name of duration fields to be used during extra mediation. Use index numbers in case of .csv cdrs.
[session_manager]
# enabled = false # Starts SessionManager service: <true|false>.
# switch_type = freeswitch # Defines the type of switch behind: <freeswitch>.
# rater = internal # Address where to reach the Rater.
# rater_reconnects = 3 # Number of reconnects to rater before giving up.
# debit_interval = 10 # Interval to perform debits on.
# max_call_duration = 3h # Maximum call duration a prepaid call can last
[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.
[cdrstats]
# enabled = false # Starts the cdrstats service: <true|false>
# queue_length = 50 # Number of items in the stats buffer
# time_window = 1h # Will only keep the CDRs who's call setup time is not older than time.Now()-TimeWindow
# metrics = ASR, ACD, ACC # Stat metric ids to build
# setup_interval = # Filter on CDR SetupTime
# tors = # Filter on CDR TOR fields
# cdr_hosts= # Filter on CDR CdrHost fields
# cdr_sources = # Filter on CDR CdrSource fields
# req_types = # Filter on CDR ReqType fields
# directions = # Filter on CDR Direction fields
# tenants = # Filter on CDR Tenant fields
# categories = # Filter on CDR Category fields
# accounts = # Filter on CDR Account fields
# subjects = # Filter on CDR Subject fields
# destination_prefixes = # Filter on CDR Destination prefixes
# usage_interval = # Filter on CDR Usage
# mediation_run_ids = # Filter on CDR MediationRunId fields
# rated_accounts = # Filter on CDR RatedAccount fields
# rated_subjects = # Filter on CDR RatedSubject fields
# cost_intervals = # Filter on CDR Cost
[history_server]
# enabled = false # Starts History service: <true|false>.
# history_dir = /var/log/cgrates/history # Location on disk where to store history files.
# save_interval = 1s # Interval to save changed cache into .git archive
[session_manager]
# enabled = false # Starts SessionManager service: <true|false>
# switch_type = freeswitch # Defines the type of switch behind: <freeswitch>
# rater = internal # Address where to reach the Rater <""|internal|127.0.0.1:2013>
# cdrs = # Address where to reach CDR Server, empty to disable CDR capturing <""|internal|127.0.0.1:2013>
# reconnects = 3 # Number of reconnects to rater/cdrs before giving up.
# debit_interval = 10 # Interval to perform debits on.
# min_call_duration = 0s # Only authorize calls with allowed duration bigger than this
# max_call_duration = 3h # Maximum call duration a prepaid call can last
[history_agent]
# enabled = false # Starts History as a client: <true|false>.
# server = internal # Address where to reach the master history server: <internal|x.y.z.y:1234>
[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.
# min_dur_low_balance = 5s # Threshold which will trigger low balance warnings for prepaid calls (needs to be lower than debit_interval)
# low_balance_ann_file = # File to be played when low balance is reached for prepaid calls
# empty_balance_context = # If defined, prepaid calls will be transfered to this context on empty balance
# empty_balance_ann_file = # File to be played before disconnecting prepaid calls on empty balance (applies only if no context defined)
# cdr_extra_fields = # Extra fields to store in CDRs in case of processing them
[mailer]
# server = localhost # The server to use when sending emails out
# auth_user = cgrates # Authenticate to email server using this user
# auth_passwd = CGRateS.org # Authenticate to email server with this password
# from_address = cgr-mailer@localhost.localdomain # From address used when sending emails out
[opensips]
# listen_udp = 127.0.0.1:2020 # Address where to listen for datagram events coming from OpenSIPS
# mi_addr = 127.0.0.1:8020 # Adress where to reach OpenSIPS mi_datagram module
# events_subscribe_interval = 60s # Automatic events subscription to OpenSIPS, 0 to disable it
# reconnects = 3 # Number of attempts on connect failure.
[derived_charging]
# run_ids = # Identifiers of additional sessions control.
# run_filters = # List of cdr field filters for each run.
# reqtype_fields = # Name of request type fields to be used during additional sessions control <""|*default|field_name>.
# direction_fields = # Name of direction fields to be used during additional sessions control <""|*default|field_name>.
# tenant_fields = # Name of tenant fields to be used during additional sessions control <""|*default|field_name>.
# category_fields = # Name of tor fields to be used during additional sessions control <""|*default|field_name>.
# account_fields = # Name of account fields to be used during additional sessions control <""|*default|field_name>.
# subject_fields = # Name of fields to be used during additional sessions control <""|*default|field_name>.
# destination_fields = # Name of destination fields to be used during additional sessions control <""|*default|field_name>.
# setup_time_fields = # Name of setup_time fields to be used during additional sessions control <""|*default|field_name>.
# answer_time_fields = # Name of answer_time fields to be used during additional sessions control <""|*default|field_name>.
# usage_fields = # Name of usage fields to be used during additional sessions control <""|*default|field_name>.
# combined_chargers = true # Combine accounts specific derived_chargers with server configured ones <true|false>.
[history_server]
# enabled = false # Starts History service: <true|false>.
# history_dir = /var/log/cgrates/history # Location on disk where to store history files.
# save_interval = 1s # Interval to save changed cache into .git archive
[history_agent]
# enabled = false # Starts History as a client: <true|false>.
# server = internal # Address where to reach the master history server: <internal|x.y.z.y:1234>
[mailer]
# server = localhost # The server to use when sending emails out
# auth_user = cgrates # Authenticate to email server using this user
# auth_passwd = CGRateS.org # Authenticate to email server with this password
# from_address = cgr-mailer@localhost.localdomain # From address used when sending emails out

37
docs/derived_charging.rst Normal file
View File

@@ -0,0 +1,37 @@
DerivedCharging
===============
DerivedCharging is the process of forking original request into a number (configured) of emulated ones, derived from the original parameters. This mechanism used in combination with multi-tenancy supported by default by **CGRateS** can give out complex charging scenarios, needed for example in case of whitelabel-ing.
DerivedCharging occurs in two separate places:
- SessionManager: necessary to handle each derived (emulated) session in it's individuall loop (eg: individual resellers will have their own charging policies implemented, some paying per minute, others per second and so on) and keep them in sync (eg: one reseller is left out of money, original call should be disconnected and all emulated sessions should end their debit loops).
- Mediator: necessary to fork the CDRs into a number of derived ones influenced by the derived charging configuration and rate them individually.
Configuration
-------------
DerivedCharging is configured in two places:
- Platform level configured within *cgrates.cfg* file.
- Account level configured as part of TarrifPlans defition or interactively via RPC methods.
One DerivedCharger object will be configured by an internal object like:
::
type DerivedCharger struct {
RunId string // Unique runId in the chain
RunFilters string // Only run the charger if all the filters match
ReqTypeField string // Field containing request type info, number in case of csv source, '^' as prefix in case of static values
DirectionField string // Field containing direction info
TenantField string // Field containing tenant info
CategoryField string // Field containing tor info
AccountField string // Field containing account information
SubjectField string // Field containing subject information
DestinationField string // Field containing destination information
SetupTimeField string // Field containing setup time information
AnswerTimeField string // Field containing answer time information
UsageField string // Field containing usage information
}
**CGRateS** is able to attach an unlimited number of DerivedChargers to a single request, based on configuration.

2
docs/freeswitch.rst
View File

@@ -1,7 +1,7 @@
8.1. FreeSWITCH integration
================================
FreeSWITCH_ used as Telecom Switch is fully supported by all of the 3 rating modes: prepaid/postpaid/pseudoprepaid.
FreeSWITCH_ used as Telecom Switch is fully supported by all of the 4 rating modes: prepaid/postpaid/pseudoprepaid/rated.
A typical use case would be like the one in the diagram bellow:
.. image:: images/CGRateSFSTypicalUsage.png

40
engine/cdrstats.go
View File

@@ -52,26 +52,26 @@ func NewCdrStatsFromCdrStatsCfg(csCfg *config.CdrStatsConfig) *CdrStats {
}
type CdrStats struct {
Id string // Config id, unique per config instance
QueueLength int // Number of items in the stats buffer
TimeWindow time.Duration // Will only keep the CDRs who's call setup time is not older than time.Now()-TimeWindow
Metrics []string // ASR, ACD, ACC
SetupInterval []time.Time // 2 or less items (>= start interval,< stop_interval)
TOR []string
CdrHost []string
CdrSource []string
ReqType []string
Direction []string
Tenant []string
Category []string
Account []string
Subject []string
DestinationPrefix []string
UsageInterval []time.Duration // 2 or less items (>= Usage, <Usage)
MediationRunIds []string
RatedAccount []string
RatedSubject []string
CostInterval []float64 // 2 or less items, (>=Cost, <Cost)
Id string // Config id, unique per config instance
QueueLength int // Number of items in the stats buffer
TimeWindow time.Duration // Will only keep the CDRs who's call setup time is not older than time.Now()-TimeWindow
Metrics []string // ASR, ACD, ACC
SetupInterval []time.Time // CDRFieldFilter on SetupInterval, 2 or less items (>= start interval,< stop_interval)
TOR []string // CDRFieldFilter on TORs
CdrHost []string // CDRFieldFilter on CdrHosts
CdrSource []string // CDRFieldFilter on CdrSources
ReqType []string // CDRFieldFilter on ReqTypes
Direction []string // CDRFieldFilter on Directions
Tenant []string // CDRFieldFilter on Tenants
Category []string // CDRFieldFilter on Categories
Account []string // CDRFieldFilter on Accounts
Subject []string // CDRFieldFilter on Subjects
DestinationPrefix []string // CDRFieldFilter on DestinationPrefixes
UsageInterval []time.Duration // CDRFieldFilter on UsageInterval, 2 or less items (>= Usage, <Usage)
MediationRunIds []string // CDRFieldFilter on MediationRunIds
RatedAccount []string // CDRFieldFilter on RatedAccounts
RatedSubject []string // CDRFieldFilter on RatedSubjects
CostInterval []float64 // CDRFieldFilter on CostInterval, 2 or less items, (>=Cost, <Cost)
Triggers ActionTriggerPriotityList
}

32
utils/storedcdr.go
View File

@@ -30,22 +30,22 @@ import (
// Kinda standard of internal CDR, complies to CDR interface also
type StoredCdr struct {
CgrId string
OrderId int64 // Stor order id used as export order id
TOR string
AccId string
CdrHost string
CdrSource string
ReqType string
Direction string
Tenant string
Category string
Account string
Subject string
Destination string
SetupTime time.Time
AnswerTime time.Time
Usage time.Duration
ExtraFields map[string]string
OrderId int64 // Stor order id used as export order id
TOR string // type of record, meta-field, should map to one of the TORs hardcoded inside the server <*voice|*data|*sms>
AccId string // represents the unique accounting id given by the telecom switch generating the CDR
CdrHost string // represents the IP address of the host generating the CDR (automatically populated by the server)
CdrSource string // formally identifies the source of the CDR (free form field)
ReqType string // matching the supported request types by the **CGRateS**, accepted values are hardcoded in the server <prepaid|postpaid|pseudoprepaid|rated>.
Direction string // matching the supported direction identifiers of the CGRateS <*out>
Tenant string // tenant whom this record belongs
Category string // free-form filter for this record, matching the category defined in rating profiles.
Account string // account id (accounting subsystem) the record should be attached to
Subject string // rating subject (rating subsystem) this record should be attached to
Destination string // destination to be charged
SetupTime time.Time // set-up time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
AnswerTime time.Time // answer time of the event. Supported formats: datetime RFC3339 compatible, SQL datetime (eg: MySQL), unix timestamp.
Usage time.Duration // event usage information (eg: in case of tor=*voice this will represent the total duration of a call)
ExtraFields map[string]string // Extra fields to be stored in CDR
MediationRunId string
RatedAccount string // Populated out of rating data
RatedSubject string