From 0a3da32c6bd49761b72b62db409c3bb46afd6e22 Mon Sep 17 00:00:00 2001 From: DanB Date: Fri, 21 Feb 2020 17:13:45 +0100 Subject: [PATCH] [Docs] Adding ThresholdS documentation --- docs/attributes.rst | 5 +- docs/cdrs.rst | 2 + docs/filters.rst | 1 + docs/resources.rst | 2 + docs/sessions.rst | 2 + docs/stats.rst | 2 +- docs/suppliers.rst | 21 +++++-- docs/thresholds.rst | 147 ++++++++++++++++++++++++++++++++++++++++++- engine/thresholds.go | 2 +- 9 files changed, 176 insertions(+), 8 deletions(-) diff --git a/docs/attributes.rst b/docs/attributes.rst index c99f9d0a2..5c3a8b2db 100644 --- a/docs/attributes.rst +++ b/docs/attributes.rst @@ -43,6 +43,7 @@ nested_fields process_runs Limit the number of loops when processing an Event. The event loop is however clever enough to stop when the same processing occurs or no more additional profiles are matching, so higher numbers are ignored if not needed. +.. _AttributeProfile: AttributeProfile ^^^^^^^^^^^^^^^^ @@ -71,9 +72,11 @@ Weight Used in case of multiple profiles matching an event. The higher, the better (0 has lowest possible priority). Attributes - List of [Attribute](#attribute) objects part of this profile + List of :ref:`Attribute` objects part of this profile. +.. _Attribute: + Attribute ^^^^^^^^^ diff --git a/docs/cdrs.rst b/docs/cdrs.rst index be310f0b1..3b07c17dd 100644 --- a/docs/cdrs.rst +++ b/docs/cdrs.rst @@ -1,3 +1,5 @@ +.. _CDRs: + CDRs ==== diff --git a/docs/filters.rst b/docs/filters.rst index adf0575f8..11f35c631 100644 --- a/docs/filters.rst +++ b/docs/filters.rst @@ -11,6 +11,7 @@ In order to be used in event processing, a Filter profile will be attached insid A subsystem can use a *Filter* via *FilterProfile* or in-line (ad-hock in the same place where subsystem profile is defined). + Filter profile -------------- diff --git a/docs/resources.rst b/docs/resources.rst index 7c4579a46..568e773b5 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -1,3 +1,5 @@ +.. _ResourceS: + ResourceS ========= diff --git a/docs/sessions.rst b/docs/sessions.rst index 4fdab0a32..424614bfc 100644 --- a/docs/sessions.rst +++ b/docs/sessions.rst @@ -1,3 +1,5 @@ +.. _SessionS: + SessionS ======== diff --git a/docs/stats.rst b/docs/stats.rst index 13da95d6f..485caf58b 100644 --- a/docs/stats.rst +++ b/docs/stats.rst @@ -107,7 +107,7 @@ Following metrics are implemented: \*asr `Answer-seizure ratio `_. Relies on *AnswerTime* field in the *Event*. \*acd - `Average call duration `. Uses *AnswerTime* and *Usage* fields in the *Event*. + `Average call duration `_. Uses *AnswerTime* and *Usage* fields in the *Event*. \*tcd Total call duration. Uses *Usage* out of *Event*. diff --git a/docs/suppliers.rst b/docs/suppliers.rst index d9401b627..e62c78af1 100644 --- a/docs/suppliers.rst +++ b/docs/suppliers.rst @@ -1,3 +1,11 @@ +.. _Asterisk: https://www.asterisk.org/ +.. _FreeSWITCH: https://freeswitch.com/ +.. _Kamailio: https://www.kamailio.org/w/ +.. _OpenSIPS: https://opensips.org/ + + +.. _Suppliers: + SupplierS ========= @@ -5,18 +13,19 @@ SupplierS **SupplierS** is a standalone subsystem within **CGRateS** responsible to compute a list of suppliers which can be used for a specific event received to process. It is accessed via :ref:`CGRateS RPC APIs`. As most of the other subsystems, it is performance oriented, stored inside *DataDB* but cached inside the *cgr-engine* process. -Caching can be done dynamically/on-demand or at start-time/precached and it is configurable within *cache* section in the .json configuration file. +Caching can be done dynamically/on-demand or at start-time/precached and it is configurable within *cache* section in the :ref:`JSON configuration `. Processing logic ---------------- -When a new *Event* is received, **SupplierS** will pass it to :ref:`FilterS` in order to find all *SupplierProfiles* matching the *Event*. +When a new *Event* is received, **SupplierS** will pass it to :ref:`FilterS` in order to find all :ref:`SupplierProfiles` matching the *Event*. -As a result of the selection process we will get a single *SupplierProfile* matching the *Event* is active at the *EventTime* and has a higher priority than the other matching *SupplierProfiles*. +As a result of the selection process we will get a single :ref:`SupplierProfile` matching the *Event*, is active at the *EventTime* and has a higher priority than the other matching :ref:`SupplierProfiles`. Depending on the *Strategy* defined in the *SupplierProfile*, further steps will be taken (ie: query cost, stats, ordering) for each of the individual *SupplierIDs* defined within the *SupplierProfile*. + APIs logic ---------- @@ -73,6 +82,8 @@ default_ratio Default ratio used in case of *load strategy +.. _SupplierProfile: + SupplierProfile ^^^^^^^^^^^^^^^ @@ -131,9 +142,11 @@ Weight Priority in case of multiple *SupplierProfiles* matching an *Event*. Higher *Weight* will have more priority. Suppliers - List of *Supplier* objects which are part of this *SupplierProfile* + List of :ref:`Supplier` objects which are part of this *SupplierProfile* +.. _Supplier: + Supplier ^^^^^^^^ diff --git a/docs/thresholds.rst b/docs/thresholds.rst index 32f1c71ee..b3b8ee11b 100644 --- a/docs/thresholds.rst +++ b/docs/thresholds.rst @@ -1,5 +1,150 @@ +.. _ThresholdS: + ThresholdS ========== -TBD \ No newline at end of file +**ThresholdS** is a standalone subsystem within **CGRateS** responsible to execute a list of *Actions* for a specific event received to process. It is accessed via :ref:`CGRateS RPC APIs`. + +As most of the other subsystems, it is performance oriented, stored inside *DataDB* but cached inside the *cgr-engine* process. +Caching can be done dynamically/on-demand or at start-time/precached and it is configurable within *cache* section in the :ref:`JSON configuration `. + + +Processing logic +---------------- + +When a new *Event* is received, **ThresholdS** will pass it to :ref:`FilterS` in order to find all *SupplierProfiles* matching the *Event*. + +As a result of the selection process we will get a list of :ref:`Thresholds` matching the *Event* and are active at the *EventTime*. + + + +APIs logic +---------- + + +GetThresholdIDs +^^^^^^^^^^^^^^^ + +Returns a list of *ThresholdIDs* configured on a *Tenant*. + + +GetThresholdsForEvent +^^^^^^^^^^^^^^^^^^^^^ + +Returns a list of :ref:`Thresholds` matching the event. + + +GetThreshold +^^^^^^^^^^^^ + +Returns a specific :ref:`Threshold` based on it's *Tenant* and *ID*. + + +ProcessEvent +^^^^^^^^^^^^ + +Technically processes the *Event*, executing all the *Actions* configured within all the matching :ref:`Thresholds`. + + +Parameters +---------- + + +ThresholdS +^^^^^^^^^^ + +**ThresholdS** is the **CGRateS** component responsible for handling the :ref:`Thresholds`. + +It is configured within **thresholds** section from :ref:`JSON configuration ` via the following parameters: + +enabled + Will enable starting of the service. Possible values: . + +store_interval + Time interval for backing up the thresholds into *DataDB*. + +indexed_selects + Enable profile matching exclusively on indexes. If not enabled, the :ref:`Thresholds` are checked one by one which for a larger number can slow down the processing time. Possible values: . + +string_indexed_fields + Query string indexes based only on these fields for faster processing. If commented out, each field from the event will be checked against indexes. If defined as empty list, no fields will be checked. + +prefix_indexed_fields + Query prefix indexes based only on these fields for faster processing. If defined as empty list, no fields will be checked. + +nested_fields + Applied when all event fields are checked against indexes, and decides whether subfields are also checked. + + +.. _ThresholdProfile: + +ThresholdProfile +^^^^^^^^^^^^^^^^ + +Contains the configuration to create a :ref:`Threshold`. Following fields can be defined: + +Tenant + The tenant on the platform (one can see the tenant as partition ID). + +ID + The profile identificator. + +FilterIDs + List of *FilterProfileIDs* which should match in order to consider the profile matching the event. + +ActivationInterval + The time interval when this profile becomes active. If undefined, the profile is always active. Other options are start time, end time or both. + +MaxHits + Limit number of hits for this threshold. Once this is reached, the threshold is considered disabled. + +MinHits + Only execute actions after this number is reached. + +MinSleep + Disable the threshold for consecutive hits for the duration of *MinSleep*. + +Blocker + Do not process thresholds who's *Weight* is lower. + +Weight + Sorts the execution of multiple thresholds matching the event. The higher the *Weight* is, the higher the priority to be executed. + +ActionIDs + List of *Actions* to execute for this threshold. + +Async + If true, do not wait for actions to complete. + + +.. _Threshold: + +Threshold +^^^^^^^^^ + +Represents one threshold, instantiated from a :ref:`ThresholdProfile`. It contains the following fields: + + +Tenant + The tenant on the platform (one can see the tenant as partition ID). + +ID + The threshold identificator. + +Hits + Number of hits so far. + +Snooze + If initialized, it will contain the time when this threshold will become active again. + + + +Use cases +--------- + +* Improve network transparency and automatic reaction to outages monitoring stats produced by :ref:`StatS`. +* Monitor active channels used by a supplier/customer/reseller/destination/weekends/etc out of :ref:`ResourceS` events. +* Monitor balance consumption out of *Account* events. +* Monitor calls out of :ref:`CDRs` events or :ref:`SessionS`. +* Fraud detection with automatic mitigation based of all events mentioned above. \ No newline at end of file diff --git a/engine/thresholds.go b/engine/thresholds.go index cf702c3ed..5edea97d7 100644 --- a/engine/thresholds.go +++ b/engine/thresholds.go @@ -385,7 +385,7 @@ func (tS *ThresholdService) V1GetThresholdsForEvent(args *ArgsProcessEvent, repl return } -// V1GetQueueIDs returns list of queueIDs registered for a tenant +// V1GetQueueIDs returns list of thresholdIDs configured for a tenant func (tS *ThresholdService) V1GetThresholdIDs(tenant string, tIDs *[]string) (err error) { prfx := utils.ThresholdPrefix + tenant + ":" keys, err := tS.dm.DataDB().GetKeysForPrefix(prfx)