diff --git a/docs/cgr-engine.rst b/docs/cgr-engine.rst index 55487fa3d..fbdf8811b 100644 --- a/docs/cgr-engine.rst +++ b/docs/cgr-engine.rst @@ -61,6 +61,7 @@ The components from the diagram can be found documented in the links bellow: sessions rals cdrs + cdre attributes chargers resources @@ -70,11 +71,9 @@ The components from the diagram can be found documented in the links bellow: filters dispatchers schedulers - cdre apiers loaders + caches datadb stordb - caches - - + \ No newline at end of file diff --git a/docs/resources.rst b/docs/resources.rst index 568e773b5..0a3201d4a 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -11,34 +11,6 @@ Both receiving of *Events* as well as operational commands on the virtual resour Due it's real-time nature, **ResourceS** are designed towards high throughput being able to process thousands of *Events* per second. This is doable since each *Resource* is a very light object, held in memory and eventually backed up in *DataDB*. -Processing logic ----------------- - -When a new *Event* is received, **ResourceS** will pass it to :ref:`FilterS` in order to find all *Resource* objects matching the *Event*. - -As a result of the selection process we will further get an ordered list of *Resource* which are matching the *Event* and are active at the request time. - -Depending of the *RPC API* used, we will have the following behavior further: - -ResourcesForEvent - Will simply return the list of *Resources* matching so far. - -AuthorizeResources - Out of *Resources* matching, ordered based on *Weight*, it will use the first one with available units to authorize the request. Returns *RESOURCE_UNAVAILABLE* error back in case of no available units found. No actual allocation is performed. - -AllocateResource - All of the *Resources* matching the event will be operated and requested units will be deducted, independent of being available or going on negative. The first one with value higher or equal to zero will be responsible of allocation and it's message will be returned as allocation message. If no allocation message is defined for the allocated resource, it's ID will be returned instead. - - If no resources are allocated *RESOURCE_UNAVAILABLE* will be returned as error. - -ReleaseResource - Will release all the previously allocated resources for an *UsageID*. If *UsageID* is not found (which can be the case of restart), will perform a standard search via *FilterS* and try to dealocate the resources matching there. - -Depending on configuration each *Resource* can be backed up regularly and asynchronously to DataDB so it can survive process restarts. - -After each resource modification (allocation or release) the :ref:`ThresholdS` will be notified with the *Resource* itself where mechanisms like notifications or fraud-detection can be triggered. - - Parameters ---------- @@ -128,6 +100,34 @@ Units Number of units allocated by this *ResourceUsage*. +Processing logic +---------------- + +When a new *Event* is received, **ResourceS** will pass it to :ref:`FilterS` in order to find all *Resource* objects matching the *Event*. + +As a result of the selection process we will further get an ordered list of *Resource* which are matching the *Event* and are active at the request time. + +Depending of the *RPC API* used, we will have the following behavior further: + +ResourcesForEvent + Will simply return the list of *Resources* matching so far. + +AuthorizeResources + Out of *Resources* matching, ordered based on *Weight*, it will use the first one with available units to authorize the request. Returns *RESOURCE_UNAVAILABLE* error back in case of no available units found. No actual allocation is performed. + +AllocateResource + All of the *Resources* matching the event will be operated and requested units will be deducted, independent of being available or going on negative. The first one with value higher or equal to zero will be responsible of allocation and it's message will be returned as allocation message. If no allocation message is defined for the allocated resource, it's ID will be returned instead. + + If no resources are allocated *RESOURCE_UNAVAILABLE* will be returned as error. + +ReleaseResource + Will release all the previously allocated resources for an *UsageID*. If *UsageID* is not found (which can be the case of restart), will perform a standard search via *FilterS* and try to dealocate the resources matching there. + +Depending on configuration each *Resource* can be backed up regularly and asynchronously to DataDB so it can survive process restarts. + +After each resource modification (allocation or release) the :ref:`ThresholdS` will be notified with the *Resource* itself where mechanisms like notifications or fraud-detection can be triggered. + + Use cases --------- diff --git a/docs/sessions.rst b/docs/sessions.rst index 424614bfc..0cda18dfb 100644 --- a/docs/sessions.rst +++ b/docs/sessions.rst @@ -4,4 +4,390 @@ SessionS ======== -TBD \ No newline at end of file +**SessionS** is a standalone subsystem within **CGRateS** responsible to manage virtual sessions based on events received. It is accessed via :ref:`CGRateS RPC APIs`. + + +Parameters +---------- + +SessionS +^^^^^^^^ + +Configured within **sessions** section within :ref:`JSON configuration ` via the following parameters: + +enabled + Will enable starting of the service. Possible values: . + +listen_bijson + Address where the *SessionS* listens for bidirectional JSON requests. + +chargers_conns + Connections towards :ref:`ChargerS` component to query charges for events. + +rals_conns + Connections towards :ref:`RALs` component to implement auth and balance reservation for events. + +cdrs_conns + Connections towards :ref:`CDRs` component where CDRs and session costs will be sent. + +resources_conns + Connections towards :ref:`ResourceS` component for resources management. + +thresholds_conns + Connections towards :ref:`ThresholdS` component to monitor and react to information within events. + +stats_conns + Connections towards :ref:`StatS` component to compute stat metrics for events. + +suppliers_conns + Connections towards :ref:`SupplierS` component to compute suppliers for events. + +attributes_conns + Connections towards :ref:`AttributeS` component for altering the events. + +replication_conns + Connections towards other :ref:`SessionS` components, used in case of session high-availability. + +debit_interval + Default debit interval in case of *\*prepaid* requests. Zero will disable automatic debits in favour of manual ones. + +store_session_costs + Used in case of decoupling events charging from CDR processing. The session costs debitted by *SessionS* will be stored into *StorDB.sessions_costs* table and merged into the CDR later when received. + +min_call_duration + Imposes a minimum call duration for event authorization. + +max_call_duration + Imposes the maximum call duration for event authorization. + +session_ttl + Enables automatic detection/removal of stale sessions. Zero will disable the functionality. + +session_ttl_max_delay + Used in tandem with *session_ttl* to randomize disconnects in order to avoid system peaks. + +session_ttl_last_used + Used in tandem with *session_ttl* to emulate the last used information for missing terminate event. + +session_ttl_usage + Used in tandem with *session_ttl* to emulate the total usage information for the incomplete session. + +session_indexes + List of fields to index out of events. Used to speed up response time for session queries. + +client_protocol + Protocol version used when acting as a JSON-RPC client (ie: force disconnecting the sessions). + +channel_sync_interval + Sync channels at regular intervals to detect stale sessions. Zero will disable this functionality. + +terminate_attempts + Limit the number of attempts to terminate a session in case of errors. + +alterable_fields + List of fields which are allowed to be changed by update/terminate events. + + +Processing logic +---------------- + +Depends on the implementation of particular *RPC API* used. + + +GetActiveSessions, GetActiveSessionsCount, GetPassiveSessions, GetPassiveSessionsCount +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Returns the list of sessions based on the received filters. + + +SetPassiveSession +^^^^^^^^^^^^^^^^^ + +Used by *CGRateS* in High-Availability setups to replicate sessions between different *SessionS* nodes. + + +ReplicateSessions +^^^^^^^^^^^^^^^^^ + +Starts manually a replication process. Useful in cases when a node comes back online or entering maintenance mode. + + +AuthorizeEvent, AuthorizeEventWithDigest +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +Used for event authorization. It's behaviour can be controlled via a number of different parameters: + + +GetAttributes + Activates altering of the event by :ref:`AttributeS`. + +AttributeIDs + Selects only specific attribute profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +AuthorizeResources + Activates event authorization via :ref:`ResourceS`. Returns *RESOURCE_UNAVAILABLE* if no resources left for the event. + +GetMaxUsage + Queries :ref:`RALs` for event's maximum usage allowed. + +ProcessThresholds + Sends the event to :ref:`ThresholdS` to be used in monitoring. + +ThresholdIDs + Selects only specific threshold profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +ProcessStats + Sends the event to :ref:`StatS` for computing stat metrics. + +StatIDs + Selects only specific stat profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +GetSuppliers + Sends the event to :ref:`SupplierS` to return the list of suppliers for it as part as authorization. + +SuppliersMaxCost + Mechanism to implement revenue assurance for suppliers coming from :ref:`SupplierS` component. Can be defined as a number or special meta variable: *\*event_cost*, assuring that the supplier cost will never be higher than event cost. + +SuppliersIgnoreErrors + Instructs to ignore suppliers with errors(ie: without price for specific destination in tariff plan). Without this setting the whole query will fail instead of just the supplier being ignored. + + +InitiateSession, InitiateSessionWithDigest +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Used in case of session initiation. It's behaviour can be influenced by following arguments: + + +GetAttributes + Activates altering of the event by :ref:`AttributeS`. + +AttributeIDs + Selects only specific attribute profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +AllocateResources + Process the event with :ref:`ResourceS`, allocating the matching requests. Returns *RESOURCE_UNAVAILABLE* if no resources left for the event. + +InitSession + Initiates the session executing following steps: + + * Fork session based on matched :ref:`ChargerS` profiles. + + * Start debit loops for *\*prepaid* requests if *DebitInterval* is higher than 0. + + * Index the session internally and start internal timers for detecting stale sessions. + +ProcessThresholds + Sends the event to :ref:`ThresholdS` to be used in monitoring. + +ThresholdIDs + Selects only specific threshold profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +ProcessStats + Sends the event to :ref:`StatS` for computing stat metrics. + +StatIDs + Selects only specific stat profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + + +UpdateSession +^^^^^^^^^^^^^ + +Used to update an existing session or initiating a new one if none found. It's behaviour can be influenced by the following arguments: + +GetAttributes + Use :ref:`AttributeS` to alter the event. + +AttributeIDs + Selects only specific attribute profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +UpdateSession + Involves charging mechanism into processing. Following steps are further executed: + + * Relocate session if *InitialOriginID* field is present in the event. + + * Initiate session if the *CGRID* is not found within the active sessions. + + * Update timers for session stale detection mechanism. + + * Debit the session usage for all the derived *\*prepaid* sessions. + + +TerminateSession +^^^^^^^^^^^^^^^^ + +Used to terminate an existing session or to initiate+terminate a new one. It's behaviour can be influenced by the following arguments: + +TerminateSession + Stop the charging process. Involves the following steps: + + * Relocate session if *InitialOriginID* field is present in the event. + + * Initiate session if the *CGRID* is not found within the active sessions. + + * Unindex the session so it does not longer show up in active sessions queries. + + * Stop the timer for session stale detection mechanism. + + * Stop the debit loops if exist. + + * Balance the charges (refund or debit more). + + * Store the session costs if configured. + + * Cache the session for later CDRs if configured. + +ReleaseResources + Will release the aquired resources within :ref:`ResourceS`. + +ProcessThresholds + Send the event to :ref:`ThresholdS` for monitoring. + +ThresholdIDs + Selects only specific threshold profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +ProcessStats + Send the event to :ref:`StatS` for building the stat metrics. + +StatIDs + Selects only specific stat profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + + + +ProcessMessage +^^^^^^^^^^^^^^ + +Optimized for event charging, without creating sessions based on it. Influenced by the following arguments: + +GetAttributes + Alter the event via :ref:`AttributeS`. + +AttributeIDs + Selects only specific attribute profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +AllocateResources + Alter the event via :ref:`ResourceS` for resource allocation. + +Debit + Debit the event via :ref:`RALs`. Uses :ref:`ChargerS` to fork the event if needed. + +ProcessThresholds + Send the event to :ref:`ThresholdS` for monitoring. + +ThresholdIDs + Selects only specific threshold profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +ProcessStats + Send the event to :ref:`StatS` for building the stat metrics. + +StatIDs + Selects only specific stat profiles (instead of discovering them via :ref:`FilterS`). Faster in processing than the discovery mechanism. + +GetSuppliers + Sends the event to :ref:`SupplierS` to return the list of suppliers for it. + +SuppliersMaxCost + Mechanism to implement revenue assurance for suppliers coming from :ref:`SupplierS` component. Can be a number or special meta variable: *\*event_cost*, assuring that the supplier cost will never be higher than event cost. + +SuppliersIgnoreErrors + Instructs to ignore suppliers with errors(ie: without price for specific destination in tariff plan). Without this setting the whole query will fail instead of just the supplier being ignored. + + + +ProcessCDR +^^^^^^^^^^ + +Build the CDR out of the event and send it to :ref:`CDRs`. It has the ability to use cached sessions for obtaining additional information like fields with values or derived charges, forking also the CDR based on that. + + +ProcessEvent +^^^^^^^^^^^^ + +Will generically process an event, having the ability to merge all the functionality of previous processing APIs. + +Instead of arguments, the options for enabling various functionaity will come in the form of *Flags*. These will be of two types: **main** and **auxiliary**, the last ones being considered suboptions of the first. The available flags are: + + +\*attributes + Activates altering of the event via :ref:`AttributeS`. + +\*cost + Queries :ref:`RALs` for event cost. + +\*resources + Process the event with :ref:`ResourceS`. Additional auxiliary flags can be specified here: + + **\*authorize** + Authorize the event. + + **\*allocate** + Allocate resources for the event. + + **\*release** + Release the resources used for the event. + +\*rals + Process the event with :ref:`RALs`. Auxiliary flags available: + + **\*auth** + Authorize the event. + + **\*init** + Initialize a session out of event. + + **\*update** + Update a sesssion (or initialize + update) out of event. + + **\*terminate + Terminate a session (or initialize + terminate) out of event. + +\*suppliers + Process the event with :ref:`Suppliers`. Auxiliary flags available: + + **\*ignore_errors** + Ignore the suppliers with errors instead of failing the request completely. + + **\*event_cost** + Ignore suppliers with cost higher than the event cost. + +\*thresholds + Process the event with :ref:`ThresholdS` for monitoring. + +\*stats + Process the event with :ref:`StatS` for metrics calculation. + +\*cdrs + Create a CDR out of the event with :ref:`CDRs`. + + +GetCost +^^^^^^^ + +Queries the cost for event from :ref:`RALs`. Additional processing options can be selected via the *Flags* argument. Possible flags: + +\*attributes + Use :ref:`AttributeS` to alter the event before cost being calculated. + + +SyncSessions +^^^^^^^^^^^^ + +Manually initiate a sync sessions mechanism. All the connections will be synced and stale sessions will be automatically disconnected. + + +ForceDisconnect +^^^^^^^^^^^^^^^ + +Disconnect the session matching the filter. + + +ActivateSessions +^^^^^^^^^^^^^^^^ + +Manually activate a session which is marked as passive. + + +DeactivateSessions +^^^^^^^^^^^^^^^^^^ + +Manually deactivate a session which is marked as active. \ No newline at end of file