mirror of
https://github.com/cgrates/cgrates.git
synced 2026-02-11 18:16:24 +05:00
[Docs] Adding ResourceS documentation
This commit is contained in:
DanB
@@ -11,6 +11,5 @@
|
||||
cdrstats
|
||||
derived_charging
|
||||
ratinglogic
|
||||
filters
|
||||
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Configuration
|
||||
The **DiameterAgent** is configured within *diameter_agent* section from :ref:`JSON configuration <configuration>`.
|
||||
|
||||
|
||||
Sample config
|
||||
Sample config
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
With explanations in the comments:
|
||||
@@ -283,11 +283,14 @@ asr_template
|
||||
templates
|
||||
Group fields based on their usability. Can be used in both processor templates as well as hardcoded within CGRateS functionality (ie *\*err* or *\*asr*). The IDs are unique, defining the same id in multiple configuration places/files will result into overwrite.
|
||||
|
||||
*\*err*: is a hardcoded template used when *DiameterAgent* cannot parse the incoming message. Aside from logging the error via internal logger the message defined via *\*err* template will be sent out.
|
||||
**\*err***
|
||||
Is a hardcoded template used when *DiameterAgent* cannot parse the incoming message. Aside from logging the error via internal logger the message defined via *\*err* template will be sent out.
|
||||
|
||||
*\*asr*: can be activated via *asr_template* config key to enable sending of *Diameter* *ASR* message to *DiameterClient*.
|
||||
**\*asr**
|
||||
Can be activated via *asr_template* config key to enable sending of *Diameter* *ASR* message to *DiameterClient*.
|
||||
|
||||
*\*cca*: defined for convenience to follow the standard for the fields used in *Diameter* *CCA* messages.
|
||||
**\*cca**
|
||||
Defined for convenience to follow the standard for the fields used in *Diameter* *CCA* messages.
|
||||
|
||||
request_processors
|
||||
List of processor profiles applied on request/replies.
|
||||
@@ -305,7 +308,7 @@ filters
|
||||
|
||||
For the dynamic content (prefixed with *~*) following special variables are available:
|
||||
|
||||
* **\*vars**
|
||||
**\*vars**
|
||||
Request related shared variables between processors, populated especially by core functions. The data put inthere is not automatically transfered into requests sent to CGRateS, unless instructed inside templates.
|
||||
|
||||
Following vars are automatically set by core:
|
||||
@@ -318,7 +321,7 @@ filters
|
||||
* **\*appid**: current request application id (out of diameter dictionary)
|
||||
* **\*cmd**: current command short naming (out of diameter dictionary) plus *R" as suffix - ie: *CCR*
|
||||
|
||||
* **\*req**
|
||||
**\*req**
|
||||
Diameter request as it comes from the *DiameterClient*.
|
||||
|
||||
Special selector format defined in case of groups *\*req.Path.To.Attribute[$groupIndex]* or *\*req.Absolute.Path.To.Attribute[~AnotherAttributeRelativePath($valueAnotherAttribute)]*.
|
||||
@@ -326,16 +329,16 @@ filters
|
||||
Example 1: *~\*req.Multiple-Services-Credit-Control.Rating-Group[1]* translates to: value of the group attribute at path Multiple-Services-Credit-Control.Rating-Group which is located in the second group (groups start at index 0).
|
||||
Example 2: *~\*req.Multiple-Services-Credit-Control.Used-Service-Unit.CC-Input-Octets[~Rating-Group(1)]* which translates to: value of the group attribute at path: *Multiple-Services-Credit-Control.Used-Service-Unit.CC-Input-Octets* where Multiple-Services-Credit-Control.Used-Service-Unit.Rating-Group has value of "1".
|
||||
|
||||
* **\*rep**
|
||||
**\*rep**
|
||||
Diameter reply going to *DiameterClient*.
|
||||
|
||||
* **\*cgreq**
|
||||
**\*cgreq**
|
||||
Request sent to CGRateS.
|
||||
|
||||
* **\*cgrep**
|
||||
**\*cgrep**
|
||||
Reply coming from CGRateS.
|
||||
|
||||
* **\*diamreq**
|
||||
**\*diamreq**
|
||||
Diameter request generated by CGRateS (ie: *ASR*).
|
||||
|
||||
flags
|
||||
@@ -349,103 +352,107 @@ flags
|
||||
|
||||
Implemented **main** flags are (in order of priority, and not working simultaneously unless specified):
|
||||
|
||||
* **\*log**
|
||||
**\*log**
|
||||
Logs the Diameter request/reply. Can be used together with other *main* actions.
|
||||
|
||||
* **\*none**
|
||||
**\*none**
|
||||
Disable transfering the request from *Diameter* to *CGRateS* side. Used mostly to pasively answer *Diameter* requests or troubleshoot (mostly in combination with *\*log* flag).
|
||||
|
||||
* **\*dryrun**
|
||||
**\*dryrun**
|
||||
Together with not transfering the request on CGRateS side will also log the *Diameter* request/reply, useful for troubleshooting.
|
||||
|
||||
* **\*auth**
|
||||
**\*auth**
|
||||
Sends the request for authorization on CGRateS.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts**, **\*suppliers**, **\*suppliers_ignore_errors**, **\*suppliers_event_cost** which are used to influence the auth behavior on CGRateS side. More info on that can be found on the **SessionS** component's API behavior.
|
||||
|
||||
* **\*initiate**
|
||||
**\*initiate**
|
||||
Initiates a session out of request on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts** which are used to influence the auth behavior on CGRateS side.
|
||||
|
||||
* **\*update**
|
||||
**\*update**
|
||||
Updates a session with the request on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*accounts** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*terminate**
|
||||
**\*terminate**
|
||||
Terminates a session using the request on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*thresholds**, **\*stats**, **\*resources**, **\*accounts** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*message**
|
||||
**\*message**
|
||||
Process the request as individual message charging on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts**, **\*suppliers**, **\*suppliers_ignore_errors**, **\*suppliers_event_cost** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
|
||||
* **\*event**
|
||||
**\*event**
|
||||
Process the request as generic event on CGRateS side.
|
||||
|
||||
Auxiliary flags available: all flags supported by the "SessionSv1.ProcessEvent" generic API
|
||||
|
||||
* **\*cdrs**
|
||||
**\*cdrs**
|
||||
Build a CDR out of the request on CGRateS side. Can be used simultaneously with other flags (except *\*dry_run)
|
||||
|
||||
|
||||
path
|
||||
Defined within field, specifies the path where the value will be written. Possible values:
|
||||
|
||||
* **\*vars**
|
||||
**\*vars**
|
||||
Write the value in the special container, *\*vars*, available for the duration of the request.
|
||||
|
||||
* **\*cgreq**
|
||||
**\*cgreq**
|
||||
Write the value in the request object which will be sent to CGRateS side.
|
||||
|
||||
* **\*cgrep**
|
||||
**\*cgrep**
|
||||
Write the value in the reply returned by CGRateS.
|
||||
|
||||
* **\*rep**
|
||||
**\*rep**
|
||||
Write the value to reply going out on *Diameter* side.
|
||||
|
||||
* **\*diamreq**
|
||||
**\*diamreq**
|
||||
Write the value to request built by *DiameterAgent* to be sent out on *Diameter* side.
|
||||
|
||||
type
|
||||
Defined within field, specifies the logic type to be used when writing the value of the field. Possible values:
|
||||
|
||||
* **\*none**
|
||||
**\*none**
|
||||
Pass
|
||||
|
||||
* **\*filler**
|
||||
**\*filler**
|
||||
Fills the values with an empty string
|
||||
|
||||
* **\*constant**
|
||||
**\*constant**
|
||||
Writes out a constant
|
||||
|
||||
* **\*remote_host**
|
||||
**\*remote_host**
|
||||
Writes out the Address of the remote *DiameterClient* sending us the request
|
||||
|
||||
* **\*variable**
|
||||
**\*variable**
|
||||
Writes out the variable value, overwriting previous one set
|
||||
|
||||
* **\*composed**
|
||||
**\*composed**
|
||||
Writes out the variable value, postpending to previous value set
|
||||
|
||||
* **\*usage_difference**
|
||||
**\*group**
|
||||
Writes out the variable value, postpending to the list of variables with the same path
|
||||
|
||||
**\*usage_difference**
|
||||
Calculates the usage difference between two arguments passed in the *value*. Requires 2 arguments: *$stopTime;$startTime*
|
||||
|
||||
* **\*cc_usage**
|
||||
**\*cc_usage**
|
||||
Calculates the usage out of *CallControl* message. Requires 3 arguments: *$reqNumber;$usedCCTime;$debitInterval*
|
||||
|
||||
* **\*sum**
|
||||
**\*sum**
|
||||
Calculates the sum of all arguments passed within *value*. It supports summing up duration, time, float, int autodetecting them in this order.
|
||||
|
||||
* **\*difference**
|
||||
**\*difference**
|
||||
Calculates the difference between all arguments passed within *value*. Possible value types are (in this order): duration, time, float, int.
|
||||
|
||||
* **\*value_exponent**
|
||||
**\*value_exponent**
|
||||
Calculates the exponent of a value. It requires two values: *$val;$exp*
|
||||
|
||||
* **\*template**
|
||||
Specifies a template of fields to be injected here. Value should be one of the template ids defined.
|
||||
**\*template**
|
||||
Specifies a template of fields to be injected here. Value should be one of the template ids defined.
|
||||
|
||||
|
||||
58
docs/ers.rst
58
docs/ers.rst
@@ -115,7 +115,7 @@ With explanations in the comments:
|
||||
}
|
||||
|
||||
|
||||
Config params
|
||||
Config params
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Most of the parameters are explained in :ref:`JSON configuration <configuration>`, hence we mention here only the ones where additional info is necessary or there will be particular implementation for *EventReaderService*.
|
||||
@@ -175,16 +175,16 @@ timezone
|
||||
filters
|
||||
List of filters to pass for the reader to process the event. For the dynamic content (prefixed with *~*) following special variables are available:
|
||||
|
||||
* **\*vars**
|
||||
**\*vars**
|
||||
Request related shared variables between processors, populated especially by core functions. The data put inthere is not automatically transfered into requests sent to CGRateS, unless instructed inside templates.
|
||||
|
||||
* **\*req**
|
||||
**\*req**
|
||||
Request read from the source. In case of file content without field name, the index will be passed instead of field source path.
|
||||
|
||||
* **\*hdr**
|
||||
**\*hdr**
|
||||
Header values (available only in case of *\*file_fwv*). In case of file content without field name, the index will be passed instead of field source path.
|
||||
|
||||
* **\*trl**
|
||||
**\*trl**
|
||||
Trailer values (available only in case of *\*file_fwv*). In case of file content without field name, the index will be passed instead of field source path.
|
||||
|
||||
flags
|
||||
@@ -198,98 +198,98 @@ flags
|
||||
|
||||
Implemented **main** flags are (in order of priority, and not working simultaneously unless specified):
|
||||
|
||||
* **\*log**
|
||||
**\*log**
|
||||
Logs the Event read. Can be used together with other *main* flags.
|
||||
|
||||
**\*none**
|
||||
Disable transfering the Event from *Reader* to *CGRateS* side.
|
||||
|
||||
* **\*dryrun**
|
||||
**\*dryrun**
|
||||
Together with not transfering the Event on CGRateS side will also log it, useful for troubleshooting.
|
||||
|
||||
* **\*auth**
|
||||
**\*auth**
|
||||
Sends the Event for authorization on CGRateS.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts**, **\*suppliers**, **\*suppliers_ignore_errors**, **\*suppliers_event_cost** which are used to influence the auth behavior on CGRateS side. More info on that can be found on the **SessionS** component's API behavior.
|
||||
|
||||
* **\*initiate**
|
||||
**\*initiate**
|
||||
Initiates a session out of Event on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*update**
|
||||
**\*update**
|
||||
Updates a session with the Event on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*accounts** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*terminate**
|
||||
**\*terminate**
|
||||
Terminates a session using the Event on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*thresholds**, **\*stats**, **\*resources**, **\*accounts** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*message**
|
||||
**\*message**
|
||||
Process the Event as individual message charging on CGRateS side.
|
||||
|
||||
Auxiliary flags available: **\*attributes**, **\*thresholds**, **\*stats**, **\*resources**, **\*accounts**, **\*suppliers**, **\*suppliers_ignore_errors**, **\*suppliers_event_cost** which are used to influence the behavior on CGRateS side.
|
||||
|
||||
* **\*event**
|
||||
**\*event**
|
||||
Process the Event as generic event on CGRateS side.
|
||||
|
||||
Auxiliary flags available: all flags supported by the "SessionSv1.ProcessEvent" generic API
|
||||
|
||||
* **\*cdrs**
|
||||
**\*cdrs**
|
||||
Build a CDR out of the Event on CGRateS side. Can be used simultaneously with other flags (except *\*dry_run)
|
||||
|
||||
path
|
||||
Defined within field, specifies the path where the value will be written. Possible values:
|
||||
|
||||
* **\*vars**
|
||||
**\*vars**
|
||||
Write the value in the special container, *\*vars*, available for the duration of the request.
|
||||
|
||||
* **\*cgreq**
|
||||
**\*cgreq**
|
||||
Write the value in the request object which will be sent to CGRateS side.
|
||||
|
||||
* **\*hdr**
|
||||
**\*hdr**
|
||||
Header values (available only in case of *\*file_fwv*). In case of file content without field name, the index will be passed instead of field source path.
|
||||
|
||||
* **\*trl**
|
||||
**\*trl**
|
||||
Trailer values (available only in case of *\*file_fwv*). In case of file content without field name, the index will be passed instead of field source path.
|
||||
|
||||
|
||||
type
|
||||
Defined within field, specifies the logic type to be used when writing the value of the field. Possible values:
|
||||
|
||||
* **\*none**
|
||||
**\*none**
|
||||
Pass
|
||||
|
||||
* **\*filler**
|
||||
**\*filler**
|
||||
Fills the values with an empty string
|
||||
|
||||
* **\*constant**
|
||||
**\*constant**
|
||||
Writes out a constant
|
||||
|
||||
* **\*remote_host**
|
||||
**\*remote_host**
|
||||
Writes out the Address of the remote host sending us the Event
|
||||
|
||||
* **\*variable**
|
||||
**\*variable**
|
||||
Writes out the variable value, overwriting previous one set
|
||||
|
||||
* **\*composed**
|
||||
**\*composed**
|
||||
Writes out the variable value, postpending to previous value set
|
||||
|
||||
* **\*usage_difference**
|
||||
**\*usage_difference**
|
||||
Calculates the usage difference between two arguments passed in the *value*. Requires 2 arguments: *$stopTime;$startTime*
|
||||
|
||||
* **\*sum**
|
||||
**\*sum**
|
||||
Calculates the sum of all arguments passed within *value*. It supports summing up duration, time, float, int autodetecting them in this order.
|
||||
|
||||
* **\*difference**
|
||||
**\*difference**
|
||||
Calculates the difference between all arguments passed within *value*. Possible value types are (in this order): duration, time, float, int.
|
||||
|
||||
* **\*value_exponent**
|
||||
**\*value_exponent**
|
||||
Calculates the exponent of a value. It requires two values: *$val;$exp*
|
||||
|
||||
* **\*template**
|
||||
**\*template**
|
||||
Specifies a template of fields to be injected here. Value should be one of the template ids defined.
|
||||
|
||||
|
||||
|
||||
@@ -2,4 +2,121 @@ ResourceS
|
||||
=========
|
||||
|
||||
|
||||
TBD
|
||||
**ResourceS** is a standalone subsystem part of the **CGRateS** infrastructure, designed allocate virtual resources for the generic *Events* (hashmaps) it receives.
|
||||
|
||||
Both receiving of *Events* as well as operational commands on the virtual resources is performed via a complete set of :ref:`CGRateS RPC APIs<remote-management>`.
|
||||
|
||||
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
|
||||
----------
|
||||
|
||||
ResourceS
|
||||
^^^^^^^^^
|
||||
|
||||
**ResourceS** is the **CGRateS** component responsible of handling the *Resources*.
|
||||
|
||||
It is configured within *resources* section from :ref:`JSON configuration <configuration>` via the following parameters:
|
||||
|
||||
enabled
|
||||
Will enable starting of the service. Possible values: <true|false>.
|
||||
|
||||
indexed_selects
|
||||
Enable profile matching exclusively on indexes. If not enabled, the *ResourceProfiles* are checked one by one which for a larger number can slow down the processing time. Possible values: <true|false>.
|
||||
|
||||
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 uncommented and 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.
|
||||
|
||||
|
||||
ResourceProfile
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
The **ResourceProfile** is the configuration of a *Resource*. This will be performed over :ref:`CGRateS RPC APIs<remote-management>` or *.csv* files. A profile is comprised out of the following parameters:
|
||||
|
||||
Tenant
|
||||
The tenant on the platform (one can see the tenant as partition ID).
|
||||
|
||||
ID
|
||||
Identifier for the *ResourceProfile*, unique within a *Tenant*.
|
||||
|
||||
FilterIDs
|
||||
List of *FilterProfiles* which should match in order to consider the *ResourceProfile* 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.
|
||||
|
||||
UsageTTL
|
||||
Autoexpire resource allocation after this time duration.
|
||||
|
||||
Limit
|
||||
The number of allocations this resource is entitled to.
|
||||
|
||||
AllocationMessage
|
||||
The message returned when this resource is responsible for allocation.
|
||||
|
||||
Blocker
|
||||
When specified, no futher resources are processed after this one.
|
||||
|
||||
Stored
|
||||
Enable offline backups for this resource
|
||||
|
||||
Weight
|
||||
Order the *Resources* matching the event. Higher value - higher priority.
|
||||
|
||||
ThresholdIDs
|
||||
List of ThresholdProfiles targetted by the *Resource*. If empty, the match will be done in :ref:`ThresholdS` component.
|
||||
|
||||
|
||||
|
||||
|
||||
ResourceUsage
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
A **ResourceUsage** represents a counted allocation within a *Resource*. The following parameters are present within:
|
||||
|
||||
Tenant
|
||||
The tenant on the platform (one can see the tenant as partition ID).
|
||||
|
||||
ID
|
||||
Identifier for the *ResourceUsage*.
|
||||
|
||||
ExpiryTime
|
||||
Exact time when this allocation expires.
|
||||
|
||||
Units
|
||||
Number of units allocated by this *ResourceUsage*.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user