SessionS¶
SessionS is a standalone subsystem within CGRateS responsible to manage virtual sessions based on events received. It is accessed via CGRateS RPC APIs.
Parameters¶
SessionS¶
Configured within sessions section within JSON configuration via the following parameters:
- enabled
- Will enable starting of the service. Possible values: <true|false>.
- listen_bijson
- Address where the SessionS listens for bidirectional JSON requests.
- chargers_conns
- Connections towards ChargerS component to query charges for events.
- rals_conns
- Connections towards RALs component to implement auth and balance reservation for events.
- cdrs_conns
- Connections towards CDRs component where CDRs and session costs will be sent.
- resources_conns
- Connections towards ResourceS component for resources management.
- thresholds_conns
- Connections towards ThresholdS component to monitor and react to information within events.
- stats_conns
- Connections towards StatS component to compute stat metrics for events.
- routes_conns
- Connections towards RouteS component to compute routes for events.
- attributes_conns
- Connections towards AttributeS component for altering the events.
- replication_conns
- Connections towards other 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.
- default_usage
- Imposes the default usage for each tipe of call.
- 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 AttributeS.
- AttributeIDs
- Selects only specific attribute profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- AuthorizeResources
- Activates event authorization via ResourceS. Returns RESOURCE_UNAVAILABLE if no resources left for the event.
- GetMaxUsage
- Queries RALs for event’s maximum usage allowed.
- ProcessThresholds
- Sends the event to ThresholdS to be used in monitoring.
- ThresholdIDs
- Selects only specific threshold profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- ProcessStats
- Sends the event to StatS for computing stat metrics.
- StatIDs
- Selects only specific stat profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- GetRoutes
- Sends the event to RouteS to return the list of routes for it as part as authorization.
- RoutesMaxCost
- Mechanism to implement revenue assurance for routes coming from RouteS component. Can be defined as a number or special meta variable: *event_cost, assuring that the route cost will never be higher than event cost.
- RoutesIgnoreErrors
- Instructs to ignore routes with errors(ie: without price for specific destination in tariff plan). Without this setting the whole query will fail instead of just the route 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 AttributeS.
- AttributeIDs
- Selects only specific attribute profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- AllocateResources
- Process the event with 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 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 ThresholdS to be used in monitoring.
- ThresholdIDs
- Selects only specific threshold profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- ProcessStats
- Sends the event to StatS for computing stat metrics.
- StatIDs
- Selects only specific stat profiles (instead of discovering them via 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 AttributeS to alter the event.
- AttributeIDs
- Selects only specific attribute profiles (instead of discovering them via 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 ResourceS.
- ProcessThresholds
- Send the event to ThresholdS for monitoring.
- ThresholdIDs
- Selects only specific threshold profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- ProcessStats
- Send the event to StatS for building the stat metrics.
- StatIDs
- Selects only specific stat profiles (instead of discovering them via 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 AttributeS.
- AttributeIDs
- Selects only specific attribute profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- AllocateResources
- Alter the event via ResourceS for resource allocation.
- Debit
- Debit the event via RALs. Uses ChargerS to fork the event if needed.
- ProcessThresholds
- Send the event to ThresholdS for monitoring.
- ThresholdIDs
- Selects only specific threshold profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- ProcessStats
- Send the event to StatS for building the stat metrics.
- StatIDs
- Selects only specific stat profiles (instead of discovering them via FilterS). Faster in processing than the discovery mechanism.
- GetRoutes
- Sends the event to RouteS to return the list of routes for it.
- RoutesMaxCost
- Mechanism to implement revenue assurance for routes coming from RouteS component. Can be a number or special meta variable: *event_cost, assuring that the route cost will never be higher than event cost.
- RoutesIgnoreErrors
- Instructs to ignore routes with errors(ie: without price for specific destination in tariff plan). Without this setting the whole query will fail instead of just the route being ignored.
ProcessCDR¶
Build the CDR out of the event and send it to 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 AttributeS.
- *cost
- Queries RALs for event cost.
- *resources
Process the event with 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 RALs. Auxiliary flags available:
- *authorize
- Authorize the event.
- *initiate
- 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.
- *routes
Process the event with RouteS. Auxiliary flags available:
- *ignore_errors
- Ignore the routes with errors instead of failing the request completely.
- *event_cost
- Ignore routes with cost higher than the event cost.
- *thresholds
- Process the event with ThresholdS for monitoring.
- *stats
- Process the event with StatS for metrics calculation.
- *cdrs
- Create a CDR out of the event with CDRs.
GetCost¶
Queries the cost for event from RALs. Additional processing options can be selected via the Flags argument. Possible flags:
- *attributes
- Use 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.