uppal/cgrates
1
0
Fork 1
mirror of https://github.com/cgrates/cgrates.git synced 2026-02-22 07:38:45 +05:00
Code Issues Packages Projects Releases Wiki Activity

Doc:

Browse Source 
- Add some tarriff_plans fixes and added cdr_stats
    - Extend cdrstats documentation + provide examples
This commit is contained in:
Eloy Coto
2015-07-03 10:35:38 +01:00
parent 8fa60bed50
commit a7a8c397f4
2 changed files with 363 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/cdrstats.rst
View File

@@ -1,51 +1,80 @@
.. _cdrstats-main:
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.
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).
- Cache driven technology. But SaveInterval can be set to store this information
on redis.
- 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, TCC) 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.
- 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:
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
}
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
SaveInterval time.Duration // Interval to store the info into database
Metrics []string // ASR, ACD, ACC, TCC, TCD, PDD
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)
PddInterval []time.Duration // CDRFieldFilter on PddInterval, 2 or less items (>= Pdd, <Pdd)
Supplier []string // CDRFieldFilter on Suppliers
DisconnectCause []string // Filter on DisconnectCause
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
}
Metrics Types
-------------
.. _cdrstats-metrics:
- ACC *(Average Call Cost)*: Queue with the average call cost
- ACD *(Average Call Duration)*: Queue with the average call duration
- ASR *(Answer-Seizure Ratio)*: Queue with the answer ratio
- PDD *(Post Dial Delay )*: Queue with the average Post Dial Delay in seconds
- TCC *(Total Call Cost)*: Queue with the Total cost for the time frame.
- TCD *(Total Call Duration)*: Queue with the total call duration for the
time frame
ExternalQueries
---------------
@@ -58,3 +87,87 @@ To facilitate interaction there are four commands built in the provided *cgr-con
- *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.
Example use
-----------
When you work with balance maybe you want to keep a eye in your users, so you
can add a new queue for the last 5 hours to check that your customer it's not
hacked, this is an example:
**CDR stats:**
.. code-block:: javascript
"result":{
"CdrStats": [
{
"Accounts": "my_account",
"ActionTriggers": "FRAUD_CHECK",
"Categories": "",
"CdrHosts": "",
"CdrSources": "",
"CostInterval": "",
"DestinationPrefixes": "",
"Directions": "",
"DisconnectCauses": "",
"MediationRunIds": "",
"Metrics": "TCC",
"PddInterval": "",
"QueueLength": "0",
"RatedAccounts": "",
"RatedSubjects": "",
"ReqTypes": "",
"SaveInterval": "15s",
"SetupInterval": "",
"Subjects": "",
"Suppliers": "",
"TORs": "",
"Tenants": "foehn",
"TimeWindow": "5h",
"UsageInterval": ""
}
],
"CdrStatsId": "FRAUD_ACCOUNT",
"TPid": "test"
}
**Action Trigger:**
.. code-block:: javascript
"result": {
"ActionTriggers": [
{
"ActionsId": "LOG_WARNING",
"BalanceCategory": "",
"BalanceDestinationIds": "",
"BalanceDirection": "",
"BalanceExpirationDate": "",
"BalanceId": "",
"BalanceRatingSubject": "",
"BalanceSharedGroup": "",
"BalanceTimingTags": "",
"BalanceType": "",
"BalanceWeight": 0,
"Id": "",
"MinQueuedItems": 0,
"MinSleep": "3h",
"Recurrent": true,
"ThresholdType": "\\*max_tcc",
"ThresholdValue": 150,
"Weight": 10
}
],
"ActionTriggersId": "FRAUD_CHECK",
"TPid": "test"
}
Using *cgr-console* you can check the status of the queue anytime:
.. code-block:: bash
cgr-console 'cdrstats_metrics StatsQueueId="FRAUD_ACCOUNT"'

306
docs/tariff_plans.rst
View File

@@ -21,29 +21,38 @@ profiles.
:file: ../data/tariffplans/tutorial/RatingProfiles.csv
:header-rows: 1
Tenant
Direction:
Can be \*in or \*out for the INBOUND and OUTBOUND calls.
Tenant:
Used to distinguish between carriers if more than one share the same
database in the CGRates system.
TOR
Category:
Type of record specifies the kind of transmission this rate profile applies
to.
Direction
Can be IN or OUT for the INBOUND and OUTBOUND calls.
Subject
Subject:
The client/user for who this profile is detailing the rates.
RatesFallbackSubject
This specifies another profile to be used in case the call destination will
not be found in the current profile. The same tenant, tor and direction will
be used.
RatesTimingTag
Forwards to a tag described in the rates timing file to be used for this
profile.
ActivationTime
ActivationTime:
Multiple rates timings/prices can be created for one profile with different
activation times. When a call is made the appropriate profile(s) will be
used to rate the call. So future prices can be defined here and the
activation time can be set as appropriate.
RatingPlanId:
This specifies the profile to be used in case the call destination.
RatesFallbackSubject:
This specifies another profile to be used in case the call destination will
not be found in the current profile. The same tenant, tor and direction will
be used.
CdrStatQueueIds:
Stat Queue associated with this account
4.2.2. Rating Plans
~~~~~~~~~~~~~~~~~~~
@@ -54,13 +63,16 @@ described once and various combinations are made possible.
:file: ../data/tariffplans/tutorial/RatingPlans.csv
:header-rows: 1
Tag
Tag:
A string by which this rates timing will be referenced in other places by.
RatesTag
DestinationRatesTag:
The rating tag described in the rates file.
TimingTag
TimingTag:
The timing tag described in the timing file
Weight
Weight:
If multiple timings cab be applied to a call the one with the lower weight
wins. An example here can be the Christmas day: we can have a special timing
for this day but the regular day of the week timing can also be applied to
@@ -78,18 +90,31 @@ various timings.
:header-rows: 1
Tag
Tag:
A string by which this rate will be referenced in other places by.
DestinationsTag
The destination tag which these rates apply to.
ConnectFee
ConnectFee:
The price to be charged once at the beginning of the call to the specified
destination.
Price
Rate:
The price for the billing unit expressed in cents.
BillingUnit
RateUnit:
The billing unit expressed in seconds
RateIncrement:
The time gap for the rate
GroupIntervalStart:
When the rate starts
.. seealso:: Rateincrement and GroupIntervalStart are when the calls has
different rates in the timeframe. For example, the first 30 seconds of the
calls has a rate of €0.1 and after that €0.2. The rate for this will the same
TAG with two RateIncrements
4.2.4. Timings
~~~~~~~~~~~~~~
Describes the time periods that have different rates attached to them.
@@ -98,18 +123,25 @@ Describes the time periods that have different rates attached to them.
:file: ../data/tariffplans/tutorial/Timings.csv
:header-rows: 1
Tag
Tag:
A string by which this timing will be referenced in other places by.
Months
Years:
Integers or \*any in case of always
Months:
Integers from 1=January to 12=December separated by semicolons (;)
specifying the months for this time period.
MonthDays
MonthDays:
Integers from 1 to 31 separated by semicolons (;) specifying the month days
for this time period.
WeekDays
WeekDays:
Integers from 1=Monday to 7=Sunday separated by semicolons (;) specifying
the week days for this time period.
StartTime
Time:
The start time for this time period. \*now will be replaced with the time of
the data importing.
@@ -122,9 +154,10 @@ logical destination group. A prefix can appear in multiple destination groups.
.. csv-table::
:file: ../data/tariffplans/tutorial/Destinations.csv
:header-rows: 1
Tag
Tag:
A string by which this destination will be referenced in other places by.
Prefix
Prefix:
The prefix or caller id to be added to the specified destination.
4.2.6. Account actions
@@ -145,18 +178,23 @@ Balance types are: MONETARY, SMS, INTERNET, INTERNET_TIME, MINUTES.
:file: ../data/tariffplans/tutorial/AccountActions.csv
:header-rows: 1
Tenant
Tenant:
Used to distinguish between carriers if more than one share the same
database in the CGRates system.
Account
Account:
The identifier for the user's account.
Direction
Can be IN or OUT for the INBOUND and OUTBOUND calls.
ActionTimingsTag
Direction:
Can be \*in or \*out for the INBOUND and OUTBOUND calls.
ActionPlanTag:
Forwards to a timed action group that will be used on this account.
ActionTriggersTag
ActionTriggersTag:
Forwards to a triggered action group that will be applied to this account.
4.2.7 Action triggers
~~~~~~~~~~~~~~~~~~~~~~
@@ -170,10 +208,13 @@ trigger resetting.
:file: ../data/tariffplans/tutorial/ActionTriggers.csv
:header-rows: 1
Tag
Tag:
A string by which this action trigger will be referenced in other places by.
ThresholdType
UniqueID:
Unique id for the trigger in multiple ActionTriggers
ThresholdType:
The threshold type. Can have one of the following:
+ **\*min_counter**: Fire when counter is less than ThresholdValue
@@ -186,18 +227,24 @@ ThresholdType
+ **\*max_acd**: Fire when ACD is greater than ThresholdValue
+ **\*min_acc**: Fire when ACC(Average call cost) is less than ThresholdValue
+ **\*max_acc**: Fire when ACC is greater than ThresholdValue
+ **\*min_tcc**: Fire when TCC(Total call cost) is less than ThresholdValue
+ **\*max_tcc**: Fire when TCC is greater than ThresholdValue
+ **\*min_tcd**: fire when TCD(total call duration) is less than thresholdvalue
+ **\*max_tcd**: fire when TCD is greater than thresholdvalue
+ **\*min_pdd**: Fire when PDD(Post Dial Delay) is less than ThresholdValue
+ **\*max_pdd**: Fire when PDD is greater than ThresholdValue
ThresholdValue
ThresholdValue:
The value of the balance counter that will trigger this action.
Recurrent(Boolean)
Recurrent(Boolean):
In case of trigger we can fire recurrent while it's active, or only the
first time.
MinSleep
MinSleep:
When Threshold is triggered we can sleep for the time specified.
BalanceTag
BalanceTag:
Specifies the balance counter by which this action will be triggered. Can
be:
@@ -207,7 +254,7 @@ BalanceTag
+ **INTERNET_TIME**
+ **MINUTES**
BalanceType
BalanceType:
Specifies the balance type for this action:
+ **\*voice**: units of call minutes
@@ -215,35 +262,38 @@ BalanceType
+ **\*data**: units of data
+ **\*monetary**: units of money
BalanceDirection
BalanceDirection:
Can be **\*in** or **\*out** for the INBOUND and OUTBOUND calls.
BalanceCategory
BalanceCategory:
Category of the call/trigger
BalanceDestinationTag
BalanceDestinationTag:
Destination of the call/trigger
BalanceRatingSubject
BalanceRatingSubject:
BalanceSharedGroup
BalanceSharedGroup:
Shared Group of the call/trigger
BalanceExpiryTime
BalanceExpiryTime:
BalanceTimingTags
BalanceTimingTags:
BalanceWeight
BalanceWeight:
StatsMinQueuedItems
StatsMinQueuedItems:
Min of items that need to have a queue to reach this Trigger
ActionsTag
ActionsTag:
Forwards to an action group to be executed when the threshold is reached.
Weight
Weight:
Specifies the order for these triggers to be evaluated. If there are
multiple triggers are fired in the same time the ones with the lower weight
will be executed first.
DestinationTag
DestinationTag:
This field is used only if the balanceTag is MINUTES. If the balance counter
monitors call minutes this field indicates the destination of the calls for
which the minutes are recorded.a
@@ -255,13 +305,16 @@ DestinationTag
:file: ../data/tariffplans/tutorial/ActionPlans.csv
:header-rows: 1
Tag
Tag:
A string by which this action timing will be referenced in other places by.
ActionsTag
ActionsTag:
Forwards to an action group to be executed when the timing is right.
TimingTag
TimingTag:
A timing (one time or recurrent) at which the action group will be executed
Weight
Weight:
Specifies the order for these timings to be evaluated. If there are multiple
action timings set to be execute on the same time the ones with the lower
weight will be executed first.
@@ -280,33 +333,37 @@ Tag
Action
The action type. Can have one of the following:
+ **CALL_URL_ASYNC**: Send a http request to the following url Asynchronous
+ **CALL_URL**: Send a http request to the following url
+ **CDRLOG**: Log the current action in the storeDB
+ **DEBIT**: Debit account balance.
+ **LOG**: Logs the other action values (for debugging purposes).
+ **MAIL_ASYNC**: Send a email to the direction
+ **RESET_ALL_COUNTERS**: Sets all counters to 0
+ **RESET_COUNTER**: Sets the counter for the BalanceTag to 0
+ **RESET_POSTPAID**: Set account to postpaid, reset all it's balances.
+ **RESET_PREPAID**: Set account to prepaid, reset all it's balances.
+ **RESET_TRIGGERS**: Marks all action triggers as ready to be executed.
+ **SET_POSTPAID**: Sets account to postpaid, maintains it's balances.
+ **SET_PREPAID**: Sets account to prepaid, maintains it's balances. Makes sense after an account was set to POSTPAID and admin wants it back.
+ **TOPUP**: Add account balance. If the specific balance is not defined, define it (example: minutes per destination).
+ **TOPUP_RESET**: Add account balance. If previous balance found of the same type, reset it before adding.
+ **\*allow_negative**: Allow to the account to have negative balance
+ **\*call_url**: Send a http request to the following url
+ **\*call_url_async**: Send a http request to the following url Asynchronous
+ **\*cdrlog**: Log the current action in the storeDB
+ **\*debit**: Debit account balance.
+ **\*deny_negative**: Deny to the account to have negative balance
+ **\*disable_account**: Disable account in the platform
+ **\*enable_account**: Enable account in the platform
+ **\*log**: Logs the other action values (for debugging purposes).
+ **\*mail_async**: Send a email to the direction
+ **\*reset_account**: Sets all counters to 0
+ **\*reset_counter**: Sets the counter for the BalanceTag to 0
+ **\*reset_counters**: Sets *all* the counters for the BalanceTag to 0
+ **\*reset_triggers**: reset all the triggers for this account
+ **\*set_recurrent**: (pending)
+ **\*topup**: Add account balance. If the specific balance is not defined, define it (example: minutes per destination).
+ **\*topup_reset**: Add account balance. If previous balance found of the same type, reset it before adding.
+ **\*unset_recurrent**: (pending)
+ **\*unlimited**: (pending)
ExtraParameters:
In Extra Parameter field you can define a argument for the action. In case
of call_url Action, extraParameter will be the url action. In case of
mail_async the email that you want to receive.
BalanceTag
BalanceTag:
The balance on which the action will operate
Units
The units which will be operated on the balance BalanceTag.
BalanceType
BalanceType:
Specifies the balance type for this action:
@@ -315,31 +372,31 @@ BalanceType
+ **\*data**: units of data
+ **\*monetary**: units of money
BalanceDirection
BalanceDirection:
Can be **\*in** or **\*out** for the INBOUND and OUTBOUND calls.
DestinationTag
DestinationTag:
This field is used only if the balanceTag is MINUTES. Specifies the
destination of the minutes to be operated.
RatingSubject
RatingSubject:
The ratingSubject of the Actions
SharedGroup
SharedGroup:
In case of the account uses any shared group for the balances.
ExpiryTime
ExpiryTime:
TimingTags
TimingTags:
Timming tag when the action can be executed. Default ALL.
Units
Units:
Number of units for decrease the balance. Only use if BalanceType is voice.
BalanceWeight
BalanceWeight:
Weight
Weight:
If there are multiple actions in a group, they will be executed in the order
of their weight (smaller first).
@@ -386,3 +443,80 @@ the table *rated_cdrs* with the runID derived_run1, and the subject 1002.
This feature it's useful in the case that you want to rated the calls 2 times,
for example rated for different tenants or resellers.
4.2.10. CDR Stats
~~~~~~~~~~~~~~~~~~
CDR Stats enabled some realtime statistics in your platform for multiple
purposes, you can read more, see :ref:`cdrstats-main`
.. csv-table::
:file: ../data/tariffplans/tutorial/CdrStats.csv
:header-rows: 1
ID:
Tag name for the Queue id
QueueLength:
Maximum number of calls in this queue
TimeWindow:
Window frame to store the calls
Save Interval:
Each interval queue stats will save in the stordb
Metric:
Type of metric see :ref:`cdrstats-metric`
SetupInterval:
TOR:
CdrHost
CdrSource:
ReqType:
Filter by reqtype
Tenant:
Used to distinguish between carriers if more than one share the same
database in the CGRates system.
Category:
Type of record specifies the kind of transmission this rate profile applies
to.
Account:
The identifier for the user's account.
Subject:
The client/user for who this profile is detailing the rates.
DestinationPrefix:
Filter only by destinations prefix. Can be multiple separated with ;
PDDInterval:
UsageInterval:
Supplier:
DisconnectCause:
MediationRunids:
RatedAccount:
Filter by rated account
RatedSubject:
Filter by rated subject
CostInterval
Filter by cost
ActionTriggers:
ActionTriggers associated with this queue