diff --git a/config/config_defaults.go b/config/config_defaults.go index c7eae5609..9b890de03 100755 --- a/config/config_defaults.go +++ b/config/config_defaults.go @@ -178,7 +178,7 @@ const CGRATES_CFG_JSON = ` "schedulers": { "enabled": false, // start Scheduler service: - "cdrs_conns": [], // connections to CDRs for *cdrlog actions <*internal|x.y.z.y:1234> + "cdrs_conns": [], // connections to CDRs for *cdrlog actions <""|*internal|$rpc_conns_id> "filters": [], // only execute actions matching these filters }, @@ -225,15 +225,15 @@ const CGRATES_CFG_JSON = ` "filters": { // Filters configuration (*new) - "stats_conns": [], // connections to StatS for <*stats> filters, empty to disable stats functionality: <""|*internal|x.y.z.y:1234> - "resources_conns": [], // connections to ResourceS for <*resources> filters, empty to disable stats functionality: <""|*internal|x.y.z.y:1234> + "stats_conns": [], // connections to StatS for <*stats> filters, empty to disable stats functionality: <""|*internal|$rpc_conns_id> + "resources_conns": [], // connections to ResourceS for <*resources> filters, empty to disable stats functionality: <""|*internal|$rpc_conns_id> }, "rals": { "enabled": false, // enable Rating/Accounting service: - "thresholds_conns": [], // connections to ThresholdS for account/balance updates, empty to disable thresholds functionality: <""|*internal|x.y.z.y:1234> - "stats_conns": [], // connections to StatS for account/balance updates, empty to disable stats functionality: <""|*internal|x.y.z.y:1234> + "thresholds_conns": [], // connections to ThresholdS for account/balance updates, empty to disable thresholds functionality: <""|*internal|$rpc_conns_id> + "stats_conns": [], // connections to StatS for account/balance updates, empty to disable stats functionality: <""|*internal|$rpc_conns_id> "caches_conns":["*internal"], // connections to CacheS for account/balance updates "rp_subject_prefix_matching": false, // enables prefix matching for the rating profile subject "remove_expired":true, // enables automatic removal of expired balances @@ -257,11 +257,11 @@ const CGRATES_CFG_JSON = ` "extra_fields": [], // extra fields to store in CDRs for non-generic CDRs (ie: FreeSWITCH JSON) "store_cdrs": true, // store cdrs in StorDB "session_cost_retries": 5, // number of queries to session_costs before recalculating CDR - "chargers_conns": [], // connection to ChargerS for CDR forking, empty to disable billing for CDRs: <""|*internal|x.y.z.y:1234> - "rals_conns": [], // connections to RALs for cost calculation: <""|*internal|x.y.z.y:1234> - "attributes_conns": [], // connection to AttributeS for altering *raw CDRs, empty to disable attributes functionality: <""|*internal|x.y.z.y:1234> - "thresholds_conns": [], // connection to ThresholdS for CDR reporting, empty to disable thresholds functionality: <""|*internal|x.y.z.y:1234> - "stats_conns": [], // connections to StatS for CDR reporting, empty to disable stats functionality: <""|*internal|x.y.z.y:1234> + "chargers_conns": [], // connection to ChargerS for CDR forking, empty to disable billing for CDRs: <""|*internal|$rpc_conns_id> + "rals_conns": [], // connections to RALs for cost calculation: <""|*internal|$rpc_conns_id> + "attributes_conns": [], // connection to AttributeS for altering *raw CDRs, empty to disable attributes functionality: <""|*internal|$rpc_conns_id> + "thresholds_conns": [], // connection to ThresholdS for CDR reporting, empty to disable thresholds functionality: <""|*internal|$rpc_conns_id> + "stats_conns": [], // connections to StatS for CDR reporting, empty to disable stats functionality: <""|*internal|$rpc_conns_id> "online_cdr_exports":[], // list of CDRE profiles to use for real-time CDR exports }, @@ -336,14 +336,14 @@ const CGRATES_CFG_JSON = ` "sessions": { "enabled": false, // starts the session service: "listen_bijson": "127.0.0.1:2014", // address where to listen for bidirectional JSON-RPC requests - "chargers_conns": [], // connections to ChargerS for session forking <*internal|x.y.z.y:1234> - "rals_conns": [], // connections to RALs for rating/accounting <""|*internal|127.0.0.1:2013> - "cdrs_conns": [], // connections to CDRs for CDR posting <*internal|x.y.z.y:1234> - "resources_conns": [], // connections to ResourceS for resources monitoring <""|*internal|127.0.0.1:2013> - "thresholds_conns": [], // connections to ThresholdS for reporting session events <""|*internal|127.0.0.1:2013> - "stats_conns": [], // connections to StatS for reporting session events <""|*internal|127.0.0.1:2013> - "suppliers_conns": [], // connections to SupplierS for querying suppliers for event <""|*internal|127.0.0.1:2013> - "attributes_conns": [], // connections to AttributeS for altering event fields <""|*internal|127.0.0.1:2013> + "chargers_conns": [], // connections to ChargerS for session forking <""|*internal|$rpc_conns_id> + "rals_conns": [], // connections to RALs for rating/accounting <""|*internal|$rpc_conns_id> + "cdrs_conns": [], // connections to CDRs for CDR posting <""|*internal|$rpc_conns_id> + "resources_conns": [], // connections to ResourceS for resources monitoring <""|*internal|$rpc_conns_id> + "thresholds_conns": [], // connections to ThresholdS for reporting session events <""|*internal|$rpc_conns_id> + "stats_conns": [], // connections to StatS for reporting session events <""|*internal|$rpc_conns_id> + "suppliers_conns": [], // connections to SupplierS for querying suppliers for event <""|*internal|$rpc_conns_id> + "attributes_conns": [], // connections to AttributeS for altering event fields <""|*internal|$rpc_conns_id> "replication_conns": [], // replicate sessions towards these session services "debit_interval": "0s", // interval to perform debits on. "store_session_costs": false, // enable storing of the session costs within CDRs @@ -516,7 +516,7 @@ const CGRATES_CFG_JSON = ` "resources": { // ResourceS config "enabled": false, // starts ResourceLimiter service: . "store_interval": "", // dump cache regularly to dataDB, 0 - dump at start/shutdown: <""|$dur> - "thresholds_conns": [], // connections to ThresholdS for resource reporting, empty to disable thresholds functionality: <""|*internal|x.y.z.y:1234> + "thresholds_conns": [], // connections to ThresholdS for resource reporting, empty to disable thresholds functionality: <""|*internal|$rpc_conns_id> "indexed_selects":true, // enable profile matching exclusively on indexes //"string_indexed_fields": [], // query indexes based on these fields for faster processing "prefix_indexed_fields": [], // query indexes based on these fields for faster processing @@ -528,7 +528,7 @@ const CGRATES_CFG_JSON = ` "enabled": false, // starts Stat service: . "store_interval": "", // dump cache regularly to dataDB, 0 - dump at start/shutdown: <""|$dur> "store_uncompressed_limit": 0, // used to compress data - "thresholds_conns": [], // connections to ThresholdS for StatUpdates, empty to disable thresholds functionality: <""|*internal|x.y.z.y:1234> + "thresholds_conns": [], // connections to ThresholdS for StatUpdates, empty to disable thresholds functionality: <""|*internal|$rpc_conns_id> "indexed_selects":true, // enable profile matching exclusively on indexes //"string_indexed_fields": [], // query indexes based on these fields for faster processing "prefix_indexed_fields": [], // query indexes based on these fields for faster processing @@ -552,9 +552,16 @@ const CGRATES_CFG_JSON = ` //"string_indexed_fields": [], // query indexes based on these fields for faster processing "prefix_indexed_fields": [], // query indexes based on these fields for faster processing "nested_fields": false, // determines which field is checked when matching indexed filters(true: all; false: only the one on the first level) +<<<<<<< HEAD "attributes_conns": [], // connections to AttributeS for altering events before supplier queries: <""|*internal|127.0.0.1:2013> "resources_conns": [], // connections to ResourceS for *res sorting, empty to disable functionality: <""|*internal|x.y.z.y:1234> "stats_conns": [], // connections to StatS for *stats sorting, empty to disable stats functionality: <""|*internal|x.y.z.y:1234> +======= + "attributes_conns": [], // connections to AttributeS for altering events before supplier queries: <""|*internal|$rpc_conns_id> + "resources_conns": [], // connections to ResourceS for *res sorting, empty to disable functionality: <""|*internal|$rpc_conns_id> + "stats_conns": [], // connections to StatS for *stats sorting, empty to disable stats functionality: <""|*internal|$rpc_conns_id> + "rals_conns": [], // connections to Rater for calculating cost, empty to disable stats functionality: <""|*internal|$rpc_conns_id> +>>>>>>> fc52ff5ad... [Docs] RALs documentation "default_ratio":1 // default ratio used in case of *load strategy }, @@ -796,7 +803,7 @@ const CGRATES_CFG_JSON = ` //"string_indexed_fields": [], // query indexes based on these fields for faster processing "prefix_indexed_fields": [], // query indexes based on these fields for faster processing "nested_fields": false, // determines which field is checked when matching indexed filters(true: all; false: only the one on the first level) - "attributes_conns": [], // connections to AttributeS for API authorization, empty to disable auth functionality: <""|*internal|x.y.z.y:1234> + "attributes_conns": [], // connections to AttributeS for API authorization, empty to disable auth functionality: <""|*internal|$rpc_conns_id> }, diff --git a/docs/rals.rst b/docs/rals.rst index 8fa08134a..864a1a8a5 100644 --- a/docs/rals.rst +++ b/docs/rals.rst @@ -2,4 +2,522 @@ RALs ==== -TBD \ No newline at end of file +**RALs** is a standalone subsystem within **CGRateS** designed to handle two major tasks: :ref:`Rating` and :ref:`Accounting`. It is accessed via :ref:`CGRateS RPC APIs`. + + + +.. _Rating: + +Rating +------ + +Rating is the process responsible to attach costs to events. + +The costs are calculated based on the input data defined within :ref:`TariffPlan` in the following sections: + + +.. _RatingProfile: + +RatingProfile +^^^^^^^^^^^^^ + +Binds the event via a fixed number of fields to a predefined :ref:`RatingPlan`. Configured via the following parameters: + +Tenant + The tenant on the platform (one can see the tenant as partition ID). Matched from event or inherited from :ref:`JSON configuration `. + +Category + Freeform field used to "categorize" the event. Matched from event or inherited from :ref:`JSON configuration `. + +Subject + Rating subject matched from the event. In most of the cases this equals with the *Account* using the service. + +ActivationTime + Date and time when the profile becomes active. There is no match before this date. + +RatingPlanID + Identifier of the :ref:`RatingPlan` assigned to the event. + +FallbackSubjects + List of rating subjects which will be searched in order in case of missing rates in case of defined :ref:`RatingPlan`. This list is only considered at first level of iteration (not considering *FallbackSubjects* within interations). + +.. Note:: One *RatingProfile* entry is composed out of a unique combination of *Tenant* + *Category* + *Subject*. + + +.. _RatingPlan: + +RatingPlan +^^^^^^^^^^ + +Groups together rates per destination and relates them to event timing. Configured via the following parameters: + +ID + The tag uniquely idenfying each RatingPlan. There can be multiple entries grouped by the same ID. + +DestinationRatesID + The identifier of the :ref:`DestinationRate` set. + +TimingID + The itentifier of the :ref:`Timing` profile. + +Weight + Priority of matching rule (*DestinationRatesID*+*TimingID*). Higher value equals higher priority. + + +.. _DestinationRate: + +DestinationRate +^^^^^^^^^^^^^^^ + +Groups together destination with rate profiles and assigns them some properties used in the rating process. Configured via the following parameters: + +ID + The tag uniquely idenfying each DestinationRate profile. There can be multiple entries grouped by the same ID. + +DestinationsID + The identifier of the :ref:`Destination` profile. + +RatesID + The identifier of the :ref:`Rate` profile. + +RoundingMethod + Method used to round during float operations. Possible values: + + **\*up** + Upsize towards next integer value (ie: 0.11 -> 0.2) + + **\*middle** + Round at middle towards next integer value (ie: 0.11 -> 0.1, 0.16 -> 0.2) + + **\*down** + Downsize towards next integer (ie: 0.19 -> 0.1). + +RoundingDecimals + Number of decimals after the comma to use when rounding floats. + +MaxCost + Maximum cost threshold for an event or session. + +MaxCostStrategy + The strategy used once the maximum cost is reached. Can be one of following options: + + **\*free** + Anything above *MaxCost* is not charged + + **\*disconnect** + The session is disconnected forcefully. + + +.. _Destination: + +Destination +^^^^^^^^^^^ + +Groups list of prefixes under one *Destination* profile. Configured via the following parameters: + +ID + The tag uniquely idenfying each Destination profile. There can be multiple entries grouped by the same ID. + +Prefix + One prefix entry (can be also full destination string). + + +.. _Rate: + +Rate +^^^^ + +A *Rate* profile will contain all the individual rates applied for a matching event/session on a time interval. Configured via the following parameters: + +ID + The tag uniquely idenfying each *Rate* profile. There can be multiple entries grouped by the same ID. + +ConnectFee + One time charge applying when the session is opened. + +Rate + The rate applied for one rating increment. + +RateUnit + The unit raported to the usage received. + +RateIncrement + Splits the usage received into smaller increments. + +GroupIntervalStart + Activates the rate at specific usage within the event. + + +.. _Timing: + +Timing +^^^^^^ + +A *Timing* profile is giving time awarness to an event. Configured via the following parameters: + +ID + The tag uniquely idenfying each *Timing* profile. + +Years + List of years to match within the event. Defaults to the catch-all meta: *\*any*. + +Months + List of months to match within the event. Defaults to the catch-all meta: *\*any*. + +MonthDays + List of month days to match within the event. Defaults to the catch-all meta: *\*any*. + +WeekDays + List of week days to match within the event as integer values. Special case for *Sunday* which matches for both 0 and 7. + +Time + The exact time to match (mostly as time start). Defined in the format: *hh:mm:ss* + + + +.. Note:: Due to optimization, CGRateS encapsulates and stores the rating information into just three objects: *Destinations*, *RatingProfiles* and *RatingPlan* (composed out of *RatingPlan*, *DestinationRate*, *Rate* and *Timing* objects). + + + +.. Accounting: + +Accounting +---------- + +Accounting is the process of charging an *Account* on it's *Balances*. The amount of charges is decided by either internal configuration of each *Balance* or calculated by :ref:`Rating`. + + +.. _Account: + +Account +^^^^^^^ + +Is the central unit of the :ref:`Accounting`. It contains the following fields: + + +Tenant + The tenant to whom the account belogs. + +ID + The Account identifier which should be unique within a tenant. This should match with the event's *Account* field. + +BalanceMap + The pool of :ref:`Balances ` indexed by type. + +UnitCounters + Usage counters which are set out of thresholds defined in :ref:`ActionTriggers ` + +AllowNegative + Allows authorization independent on credit available. + +UpdateTime + Set on each update in DataDB. + +Disabled + Marks the account as disabled, making it invisible to charging. + + + +.. _Balance: + +Balance +^^^^^^^ + + +Is the unit container (wallet/bundle) of the :ref:`Account`. There can be unlimited number of *Balances* within one :ref:`Account`, groupped by their type. + +The following *BalanceTypes* are supported: + +\*voice + Coupled with voice calls, represents nanosecond units. + +\*data + Coupled with data sessions, represents units of data (virtual units). + +\*sms + Coupled with SMS events, represents number of SMS units. + +\*mms + Coupled with MMS events, represents number of MMS units. + +\*generic + Matching all types of events after specific ones, represents generic units (ie: for each x *voice minutes, y *sms units, z *data units will have ) + +\*monetary + Matching all types of events after specific ones, represents monetary units (can be interpreted as virtual currency). + + + +A *Balance* is made of the following fields: + +Uuid + Unique identifier within the system (unique hash generated for each *Balance*). + +ID + Idendificator configurable by the administrator. It is unique within an :ref:`Account`. + +Value + The *Balance's* value. + +ExpirationDate + The expiration time of this *Balance* + +Weight + Used to prioritize matching balances for an event. The higher the *Weight*, the more priority for the *Balance*. + +DestinationIDs + List of :ref:`Destination` profiles this *Balance* will match for, considering event's *Destination* field. + +RatingSubject + The rating subject this balance will use when calculating the cost. + + This will match within :ref:`RatingProfile`. If the rating profile starts with character *\**, special cost will apply, without interogating :ref:`Rating` for it. The following *metas* are available: + + **\*zero$xdur** + A *\*zero* followed by a duration will be the equivalent of 0 cost, charged in increments of *x* duration (ie: *\*zero1m*. + + **\*any** + Points out to default (same as undefined). Defaults are set to *\*zero1s* for voice and *\*zero1ns* for everything else. + +Categories + List of event *Category* fields this *Balance* will match for. + +SharedGroup + Pointing towards a shared balance ID. + +TimingIDs + List of :ref:`Timing` profiles this *Balance* will match for, considering event's *AnswerTime* field. + +Disabled + Makes the *Balance* invisible to charging. + +Factor + Used in case of of *\*generic* *BalanceType* to specify the conversion factors for different type of events. + +Blocker + A *blocking Balance* will prevent processing further matching balances when empty. + + + +.. ActionTrigger: + +ActionTrigger +------------- + +Is a mechanism to monitor Balance values during live operation and react on changes based on configured thresholds and actions. + +An *ActionTrigger* is made of the following attributes: + +ID + Identifier given by the administrator + +UniqueID + Per threshold identifier + +ThresholdType + Type of threshold configured. The following types are available: + + **\*min_balance** + Matches when the :ref:`Balance` value is smaller. + + **\*max_balance** + Matches when the :ref:`Balance` value is higher. + + **\*balance_expired** + Matches if :ref:`Balance` is expired. + + **\*min_event_counter** + Consider smaller aggregated values within event based on filters. + + **\*max_event_counter** + Consider higher aggregated values within event based on filters. + + **\*min_balance_counter** + Consider smaller :ref:`Balance` aggregated value based on filters. + + **\*max_balance_counter** + Consider higher :ref:`Balance` aggregated value based on filters. + +ThresholdValue + The value of the threshold to match. + +Recurrent + Execute *ActionTrigger* multiple times. + +MinSleep + Sleep in between executes. + +ExpirationDate + Time when the *ActionTrigger* will expire. + +ActivationDate + Only consider the *ActionTrigger* starting with this time. + +Balance + Filters selecting the balance/-s to monitor. + +Weight + Priority in the chain. Higher values have more priority. + +ActionsID + :ref:`Action` profile to call on match. + +MinQueuedItems + Avoid false positives if the number of items hit is smaller than this. + +Executed + Marks the *ActionTrigger* as executed. + +LastExecutionTime + Time when the *ActionTrigger* was executed last. + + +.. Action: + +Action +------ + +Actions are routines executed on demand (ie. by one of the three subsystems: :ref:`SchedulerS`, :ref:`ThresholdS` or :ref:`ActionTriggers`) or called by API by external scripts. + +An *Action has the following parameters: + +ID + *ActionSet* identifier. + +ActionType + The type of action to execute. Can be one of the following: + + **\*log** + Creates an entry in the log (either syslog or stdout). + + **\*reset_triggers** + Reset the matching :ref:`ActionTriggers ` + + **\*cdrlog** + Creates a CDR entry (used for example when automatically charging DIDs). The content of the generated CDR entry can be customized within a special template which can be passed in *ExtraParameters* of the *Action*. + + **\*set_recurrent** + Set the recurrent flag on the matching :ref:`ActionTriggers `. + + **\*unset_recurrent** + Unset the recurrent flag on the matching :ref:`ActionTriggers `. + + **\*allow_negative** + Set the *AllowNegative* flag on the :ref:`Balance`. + + **\*deny_negative** + Unset the *AllowNegative* flag on the :ref:`Balance`. + + **\*reset_account** + Re-init the :ref:`Account` by setting all of it's :ref:`Balance's Value ` to 0 and re-initialize counters and :ref:`ActionTriggers `. + + **\*topup_reset** + Reset the :ref:`Balance` matching the filters to 0 and add the top-up value to it. + + **\*topup** + Add the value to the :ref:`Balance` matching the filters. + + **\*debit_reset** + Reset the :ref:`Balance` matching the filters to 0 and debit the value from it. + + **\*debit** + Debit the value from the :ref:`Balance` matching the filters. + + **\*reset_counters** + Reset the :ref:`Balance` counters (used by :ref:`ActionTriggers ). + + **\*enable_account** + Unset the :ref:`Account` *Disabled* flag. + + **\*disable_account** + Set the :ref:`Account` *Disabled* flag. + + **\*http_post** + Post data over HTTP protocol to configured HTTP URL. + + **\*http_post_async** + Post data over HTTP protocol to configured HTTP URL without waiting for the feedback of the remote server. + + **\*mail_async** + Send data to configured email address in extra parameters. + + **\*set_ddestinations** + Update list of prefixes for destination ID starting with: *\*ddc* out of StatS. Used in scenarios like autodiscovery of homezone prefixes. + + **\*remove_account** + Removes the matching account from the system. + + **\*remove_balance** + Removes the matching :ref:`Balances ` out of the :ref:`Account`. + + **\*set_balance** + Set the matching balances. + + **\*transfer_monetary_default** + Transfer the value of the matching balances into the *\*default* one. + + **\*cgr_rpc** + Call a CGRateS API over RPC connection. The API call will be defined as template within the *ExtraParameters*. + + **\*topup_zero_negative** + Set the the matching balances to topup value if they are negative. + + **\*set_expiry** + Set the *ExpirationDate* for the matching balances. + + **\*publish_account** + Publish the :ref:`Account` and each individual :ref:`Balance` to the :ref:`ThresholdS`. + + **\*publish_balance** + Publish the matching :ref:`Balances ` to the :ref:`ThresholdS`. + + **\*remove_session_costs** + Removes entries from the :ref:`StorDB.session_costs ` table. Additional filters can be specified within the *ExtraParameters*. + + **\*remove_expired** + Removes expired balances of type matching the filter. + + **\*cdr_account** + Creates the account out of last *CDR* saved in :ref:`StorDB` matching the account details in the filter. The *CDR* should contain *AccountSummary* within it's *CostDetails*. + + +Configuration +------------- + +The *RALs* is configured within **rals** section from :ref:`JSON configuration ` via the following parameters: + +enabled + Will enable starting of the service. Possible values: . + +thresholds_conns + Connections towards :ref:`ThresholdS` component, used for :ref:`Account` notifications. + +stats_conns + Connections towards :ref:`StatS` component, used for :ref:`Account` ralated metrics. + +caches_conns + Connections towards :ref:`CacheS` used for data reloads. + +rp_subject_prefix_matching + Enabling prefix matching for rating *Subject* field. + +remove_expired + Enable automatic removal of expired :ref:`Balances `. + +max_computed_usage + Prevent usage rating calculations per type of records to avoid memory overload. + +max_increments + The maximum number of increments generated as part of rating calculations. + +balance_rating_subject + Default rating subject for balances, per balance type. + + +Use cases +--------- + +* Classic rater calculating costs for events using :ref:`Rating`. +* Account bundles for fixed and mobile networks (xG) using :ref:`Accounting`. +* Volume discounts in real-time using :ref:`Accounting`. +* Fraud detection with automatic mitigation using :ref:`ActionTriggers