Accounting events 🔗

• in dialog scope - the call was successfully established:

• success event. Such events generate an accounting record when:
  • in transaction scope - the transaction when successfully completed (with a 2xx reply):

• it dialog scope - the call was successfully established:

• missed call event. Such events may occur only during the dialog setup phase (during the lifetime of the transaction for the initial INVITE), when a call attempt (or branch) was not established, as the UAS destination rejected or declined the call; There can be multiple such events per a single SIP call (due SIP forking). Note that a SIP call generating an accounting success event may also generate one or more missed call event because of the SIP branches (call attempts) that failed during serial or parallel forking; The missed call events are also known as UAS-side accounting (as they are related to the relation between OpenSIPS and callee/UAS side).

• failed transaction event. Such event is generated only in the transaction scope, when a transaction fails (reply code >=300) on the UAC side of OpenSIPS - this is a complementary event for the successful transaction event.

When doing accounting, one can choose between a variety of engines or even combine them together:

• enable multiple missed calls events during SIP serial forking. Let's take the case when there is a call for user Alice but Alice has multiple contacts registered (via SIP registration), like Contact1, Contact2 and Contact3. The order for serial forking should be Contact1, Contact2 and Contact3. That is first time we try to call Contact1, if Contact1 does not respond Contact2 shall be tried and the last try should be made to Contact3. Last, but not least, if the call is to established (to any of the contacts), the call will be accounted.

In the script, everything that concerns the lookup() function was moved into a route, in order to use it multiple times. For the initial call, we'll get the URI of the caller from the From header. The URI of the callee is in the R-URI:

In case our call leg to Bob (as described above) fails, script execution will resume from the failure_route, where we will do serial forking to the redirect URI (to Charlie). In failure route, the redirected URI is resolved in the same way we did with the first uri, using lookup function. Now the leg Bob to Charlie is about to start, so we'll create a new leg and populate the $acc_leg variables accordingly for this new leg. The caller URI will be the callee URI of the previous leg, while the callee U will be the new redirect URI:

Concepts such as accounting events (missed calls, failed calls) , the accounting scope (transaction, dialog), accounting backends (database, log, radius) are explained and covered by full script examples. More complex scenarios including advanced features like extra accounting (extending the CDR format and collecting information from the entire call), and multi-leg accounting (multiple CDR records per SIP call) are also covered.

Everything in this tutorial is backed up with practical examples which you can run and dissect in order to get a better picture about how accounting works, and what are the best accounting options for your needs. Most of the features presented in this tutorial are available in versions starting with OpenSIPS 2.2, where there has been a major rework affecting the accounting module. Nevertheless, this rework continued with OpenSIPS 2.3 when comes to simplifying the user experience in regards to the scripting.

• SIP dialog level accounting: the generated accounting record covers a whole SIP call/dialog; such accounting record is also known as CDR (Call Detail Record). This record, in addition to the transaction-scope accounting records, may contain information from the dialog level (call duration, BYE reason, RTP stats); In terms of usage, the dialog accounting is armed/set while handling the initial INVITE request; the CDR itself will be generated when the SIP dialog ends(that is when all the messages belonging to a dialog have been processed, including the replies for BYE messages);

        # new caller is the callee of the previous leg
        $acc_leg(caller) = $(acc_leg(callee)[-2]);
        # new callee is the new destination

To conclude, if you do SIP stateless processing or if you need to manually account some really custom corner-cases, you should use the SIP message level accounting. Otherwise, if in stateful mode, for non-INVITE traffic, the SIP transaction level accounting gives you the best results - a single accounting record aggregating all the transaction related information. For INVITE based sessions, the SIP dialog level accounting is the easiest and most powerful way to get ready to use CDRs.

      $acc_leg(caller) = $fu;
      $acc_leg(callee) = $ru;

If using db backend two rows will be generated, one with the leg from Alice to Bob and one with the leg from Bob to Charlie. The non-leg fields will be the same in all the legs:

Here it is the full OpenSIPS config file used in this example.

In case our call leg to Bob, as described above, fails and we will get into failure route where we will do serial forking to the redirect URI (to Charlie). In failure route, the redirected URI is resolved in the same way we did with the first uri, using lookup function. Now the leg Bob to Charlie is about to start, so we'll create a new leg and populate the $acc_leg variables accordingly for this new leg. The caller URI will be the callee URI of the previous leg, while the callee U will be the new redirect URI:

    if ( $avp(redirect_uri)!=NULL ) {
        # set the new destination
        $ru = $avp(redirect_uri);

        $var(prev_callee) = $acc_leg(callee);
        # create a new call leg
        acc_new_leg();
        $acc_leg(caller) = $var(prev_callee);
        $acc_leg(callee) = $ru;

        t_on_failure("missed_call");
        route(lookup);
        exit;
    }

For one redirect, we will have two account lines. One for the missed call from Alice to Bob

ACC: call missed: timestamp=1474899448;created=1474899444;setuptime=4;method=INVITE; from_tag=1766231375;to_tag=;call_id=604787970;code=408;reason=Request Timeout; src_ip=10.0.0.101;dst_ip=10.0.0.203;caller=Alice;callee=Bob

and the CDR record, with both legs, Alice to Bob and Bob to Charlie:

  src_ip=10.0.0.101;dst_ip=10.0.0.203;caller=Alice;callee=Bob;caller=Bob;callee=Charlie

If using db engine two rows will be generated, one with the leg from Alice to Bob and one with the leg from Bob to Charlie. The non-leg fields will be the same in all the legs:

|   created  | .... |reason|   src_ip   |   dst_ip   | caller | callee  |
| 1474899444 | .... |  OK  | 10.0.0.101 | 10.0.0.203 | Alice  |   Bob   |
| 1474899444 | .... |  OK  | 10.0.0.101 | 10.0.0.203 |  Bob   | Charlie |

This is the full OpenSIPS config file used for this example.

Sometimes the extra values are not enough. One such scenario is when user Alice calls to user Bob, but Bob doesn't not respond and he's got a redirect to user Charlie. In this case we have two logical legs, from Alice to Bob and from Bob to Charlie. And we want to get separate accounting information for each of these legs. In OpenSIPS, this is called multi-leg accounting or per-leg accounting.

In our example, we want to account the caller and callee usernames for each leg (as they we differ for the two legs). Depending on the accounting backend, when using multi-leg accounting, a single accounting records may translate into multiple backend records (one for each leg). For example, if using db backend, you will have one row per leg in the accounting table (this is because in SQL the format of the table is fixed, and it cannot vary with the number of legs).

This is the full OpenSIPS config file used for this example.

The same is the case for $acc_leg variable. The only difference is that this variable can be indexed using the leg number. No index means the current leg. You can also get the number of the last leg using $acc_current_leg variable. New additional legs can be created with acc_new_leg() function.

In the script, everything that concerns lookup function was moved into a route, in order to use it multiple times. For the initial call, we'll get the URI of the caller from the From header. The URI of the callee is in the R-URI:

Starting from the previous script, we try to add extra accounting information about the IP addresses where the call was originated from and terminated to. First of all we need to define the additional data that will be added to our accounted information in the modparam section using the extra_fields parameter

   modparam("acc", "extra_fields", "log: src_ip; dst_ip")

   modparam("acc", "extra_fields", "log: src_ip->src_ip; src_ip->dst_ip")

In terms of scripting, all we need to do is to set the $acc_extra variable with the values we what. In the current scenario we set the IPs as follow:

• for the originating IP of the call we consider the source IP of the INVITE (initial request), so in request route, when handling initial SIP requests, we do (see line 224):

        $acc_extra(src_ip) = $si;

• for the termination IP of the call we consider the source IP of final SIP reply (>=200), so in the onreply route, when handling SIP replies, we do (see line 268):

    if ( $rs >= 200 )
        $acc_extra(dst_ip) = $si;

@]

The CDR for the current call will contain the new extra values, as we set them [@

  call_id=604787970;code=200;reason=OK;src_ip=10.0.0.101;dst_ip=10.0.0.203

Here it is the full OpenSIPS config file used in this example.

There are cases when you may need to extend your accounting capabilities and to add some additional custom values to the accounting records (in addition to the default fields). This is called extra accounting - shortly, you define some new accounting fields and set what values is to be placed into them.

Starting from the previous script, we try to add extra accounting information about the caller's and callee's URI. First of all we need to define the additional data that will be added to our accounted information in the modparam section using the extra_fields parameter

   modparam("acc", "extra_fields", "log: caller_uri; callee_uri")

   modparam("acc", "extra_fields", "log: caller_uri->callee_uri; callee_uri->callee_uri")

The first part of the declaration is the backend for which the extra fields are defined, in this case the log backend. The definitions are in form of script-tag -> backend-tag. The script-tag is the tag to be used in OpenSIPS script to reference the $acc_extra variable, which will hold all our extra values. The scope of the variable depends on the accounting type used. If the cdr flag is used when calling do_accounting(), the variable will be visible for the whole duration of the dialog, else it will be visible as long as the transaction will be visible. The backend-tag is where the values will be stored in the accounting backend ( for log it is a display label, for db it is a column name or for aaa it is an RADIUS/DIAMETER AVP name).

In terms of scripting, all we need to do is to set the $acc_extra variable with the values we what. In the current scenario we set the domains

        $acc_extra(caller_uri) = $ru;
        $acc_extra(callee_uri) = $tu;

  call_id=604787970;code=200;reason=OK;caller_uri=sip:alice@opensips.org;callee_uri=sip:bob@opensips.org

The leg_fields module parameter defines a list of new fields that will be different from leg to leg (all the other fields - the default and extra accounting ones - will be the same for all the legs). Each set of leg_fields values will translate into a separate leg for the call.

• add dialog scope (cdr keyword) when setting the success event for the INVITE requests

To get directly CDR as accounting records, when doing do_accounting() (line 193) for initial INVITEs (which create SIP calls/dialogs), we need to switch it from transaction scope to dialog scope, by using the cdr keyword to the flags:

Once again, this is the full OpenSIPS config file we used for this example.

• SIP message level accounting: the generated accounting record covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request(), acc_db_request(), acc_aaa_request() or acc_evi_request() depending on the backend used;
• SIP transaction level accounting: the generated accounting record covers a SIP transaction (the duration and data from the SIP request and all its replies); such accounting is used when OpenSIPS acts as a stateful SIP proxy; this accounting is armed/set during the request processing, but the accounting record itself will be generated when the SIP transaction (including all its branches) will be completed;
• SIP dialog level accounting: the generated accounting record covers a whole SIP call/dialog; such accounting record is also known as CDR (Call Data Record). This record, in addition to the transaction-scope accounting records, may contain information from the dialog level (call duration, BYE reason, RTP stats); In terms of usage, the dialog accounting is armed/set while handling the initial INVITE request; the CDR itself will be generated when the SIP dialog ends(that is when all the messages belonging to a dialog have been processed, including the replies for BYE messages);

• success event. Such even generates an accounting record when:

This mechanism allows you to extend the accounting record field by adding custom fields to it (with data collected anytime during the scope of the accounting).
The extra_fields module parameter allows the definition of a list of new fields to be added to the format of the accounting record. During the script processing, those fields may be populated anywhere and anytime as you are still in the scope of that accounting action.
There is a special script variable defined for this mechanism called $acc_extra which can be populated with whatever you want; the $acc_extra variable is persistent across the whole accounting scope - for example, if you do transaction based accounting, you can collect data (to be pushed into the extra accounting fields) during the request handling, in reply route or during a call forking in failure route.\\

There are SIP scenarios where there is a need to get multiple accounting records for a single SIP call. Typically this happens when implementing call redirect or call forward and the actual SIP call consists out of several call legs (logical calls between SIP entities).\\

                                # do accounting, even if the transaction fails

• enable multiple missed calls events during SIP serial forking. Let's take the case when there is a call for user Alice but Alice has multiple contacts registered (via SIP registration), like Contact1, Contact2 and Contacct3. The order for serial forking should be Contact1, Contact2 and Contact3. That is first time we try to call Contact1, if Contact1 does not respond Contact2 shall be tried and the last try should be made to Contact3. Last, but not least, if the call is to established (to any of the contacts), the call will be accounted.

This is the config file corresponding to this scenario. All below explanations are relative to this script.

If do_accounting() would not have been called again, in case of failure, only the first missed call would have been accounted. The flag resets each time a missed call is accounted. The next_branches() function call will get the next destination for us. If we still have contacts to call to we arm the failure route again in order to be able to send the call to the next destination.

A missed call event will be generated for each destination that did not accept the call:

The reply code and the reason may change depending on the scenario. If at least one of the contacts answered and the call is established, the CDR (as success event) will be generated after the call ended:

Here, besides the basic information that is present in every accounting record we can see the the additional fields call_start_time, and the call duration both in seconds and milliseconds.

To achieve this behavior we do the following changes to the accounting functions:

• add dialog scope (cdr keyword) when setting the success event for the INVITE requests
• as we do accounting at dialog level (we get CDRs directly), there is no need to separately account the BYE transaction, so we remove any accounting for them
• enable missed call event also in failure route, so we can get such events during the sequential steps of the serial forking.

Now, in terms of scripting we remove the do_accounting() for the BYE transactions (as we do accounting at dialog level, not transaction level any more) - see the sequential request block, line 127 where the accounting call was stripped out.

To get directly CDR as accounting records, when doing do_accounting() (line 193) for initial INVITEs (which create SIP calls/dialogs), we need to switch it from transaction scope to dialog scope, by using the cdr keyword to the flags:

        # account only INVITEs
	if (is_method("INVITE")) {
		do_accounting("log", "cdr");
	}

Keep in mind that the CDR flag affects only the calls(dialogs).

To enable serial forking (for all the registered contacts) the following lines were added after a successful lookup into location table. The code is serializing the found contact based on their priority (Q parameter) - first we send the call to the higher priority contacts and in case of failure (no call established), we serial fork the call to the next contacts with lower priority (see serialize_branches() description) . This re-attempting (serial forking) is done until there are no more contacts left.

If do_accounting() would not have been called again, in case of failure, only the first missed call would have been accounted. The flag resets each time a missed call is accounted. The next_branches() function call will get the next destination for us. If we still have contacts to call to we arm the failure route again in order to be able to send the message to next destination.

CDR-based and serial forking accounting

In this new example, we extend the accounting functionality offered by the previous script in order to additionally achieve :

• enable dialog level accounting so we can get CDRs (as accounting records)
• enable multiple missed calls events during SIP serial forking. Let's take the case when there is a call for user Alice but Alice has multiple contacts registered (via SIP registration), like Contact1, Contact2 and Contacct3. The order for serial forking should be Contact1, Contact2 and Contact3. That is first time we try to call Contact1, if Contact1 does not respond Contact2 shall be tried and the last try should be made to Contact3. Last, but not least, if the call is to established (to any of the contacts), the CDR will be accounted.

To achieve this behavior we do the following extensions to the accounting functions:

• add dialog scope (cdr keyword) when setting the success event for the INVITE transactions
• enable missed call event in failure route, when doing serial forking.

First of all, in order to be able to use the CDR engine, dialog module needs to be loaded (we do it here in the simplest possible way):

Also in the request route, when handling the initial requests, for INVITE requests we do (see line 194):

The last do_accounting() usage in the script (line 231) is for triggering the missed call events for the calls (INVITE requests) sent to our registered users.

Once again, this is the full OpenSIPS config file we used for this example.

The last do_accounting() usage in the script is for triggering the missed call events for the calls (INVITE requests) sent to our registered users.

In the routing section of the script the do_accounting() function is used for setting the accounting process (as events, scope and backend). In all case the log backend is used, which means that all the accounting records will be pushed as logs. This script is logging to syslog service, using log facility LOG_DAEMON (see log_facility ) with log level L_NOTICE (see log_level).

Here is an example of how the accounted lines should look line in your syslog

Now, let's walk through the opensips.cfg and explain step by step all the accounting related actions.

When processing the SIP requests in the request route, when handling the sequential request, the do_accounting() function is used (see line 127) to trigger accounting records on success and failed transactions(reply code >= 300) events for all the BYE transactions:

http://opensips.org/pub/docs/tutorials/accounting/images/acc_event_success_dialog.png

http://opensips.org/pub/docs/tutorials/accounting/images/acc_event_missed.png

http://opensips.org/pub/docs/tutorials/accounting/images/acc_event_failed.png

http://opensips.org/pub/docs/tutorials/accounting/images/acc_event_success.png

The OpenSIPS default config file provides a simple accounting support. This will be used as a starting point in our quest to understand and script more and more complex accounting scenarios.

In this script, we want to get accounting records only for call related requests - for INVITE and BYE transactions. So, the accounting is done only at transaction level and the following accounting events are configured:

• success event for the INVITE transactions
• success event and failed transaction event for the BYE transactions - we want an accounting record no matter response code we get for the BYE.

The syslog backend shall be used for accounting - this has the keyword log.

In the routing section of the script the do_accounting() function is used for setting the accounting process (as events, scope and backend). In all case the log backend is used, which means that all the accounting records will be pushed as logs. This script is logging to syslog service, using log facility LOG_DAEMON (see log_facility ) with log level L_NOTICE (see log_level.

When handling the SIP requests in the request route, inside the block for sequential request, the do_accounting() function is used at line 127:

This line will trigger for all the BYE transactions the success and the failed transactions(reply code >= 300) accounting events. Here is an example of how the accounted lines should look line in your syslog

If the failed option is not used, the do_accounting() will not trigger the failed transactions event and the above record will not be generated (since the transaction completes with a 400 reply code).

Also in the request route, when handling the initial requests, for INVITE requests we do (see line xxx):

Since no flag is specified, only success events will be accounted for the transaction:

The last do_accounting() usage in the script is for enabling missed call events for the calls (INVITE requests) sent to our registered users.

Accounting scopes

The accounting may have different scopes and it may be in-line with different SIP elements :

• SIP message level accounting: the generated CDR covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request(), acc_db_request(), acc_aaa_request() or acc_evi_request() depending on the backend used;
• SIP transaction level accounting: the generated CDR covers a SIP transaction (the duration and data from the SIP request and all its replies); such accounting is used when OpenSIPS acts as a stateful SIP proxy; this accounting is armed/set during the request processing, but the CDR itself will be generated when the SIP transaction (including all its branches) will be completed;
• SIP dialog level accounting: the generated CDR covers a whole SIP call/dialog; such CDR may additionally (to the SIP transaction CDRs) contain information from the dialog level (call duration, BYE reason, RTP stats); In terms of usage, the dialog accounting is armed/set while handling the initial INVITE request; the CDR itself will be generated when the SIP dialog ends(that is when all the messages belonging to a dialog have been processed, including the replies for BYE messages);

OpenSIPS can account different events during the accounting scope, such as:

• success event. Such even generates a CDR when:
  • in transaction scope the transaction when successfully completed (with a 2xx reply);

• it dialog scope when the call was successfully established ;

• missed call event. Such event may be generated only during the dialog setup phase (during the lifetime of the transaction for the initial INVITE), when a call attempt (or branch) did not established, as the UAS destination rejected or declined the call; There can be multiple such events per a single SIP call (due SIP forking). Note that a SIP call generating a accounting success event may also generate some missed call event because of the SIP branches (call attempts) that failed during serial or parallel forking; The missed call events are also known as UAS-side accounting (as they are related to the relation between OpenSIPS and callee/UAS side).

• failed transaction event. Such event is generated only in the transaction scope, when a transaction fails (reply code >=300) on the UAC side of OpenSIPS - this is a complementary event for the successfully transaction event.

In case our call to B, as described above, fails and we will get into failure route where we will fetch the next destination as usual. For redirects, we check if the new destination is a local uri, meaning that we have to resolve the same way we did with the first uri, using lookup function. Now the call from B to C starts, so we'll create a new leg. We need to store the name of the caller before calling next_branches() function, because after this call we will lose it:

In case our call to B, as described above, fails we will get into failure route where we will fetch the next destination as usual. For redirects, we check if the new destination is a local uri, meaning that we have to resolve the same way we did with the first uri, using lookup function. Now the call from B to C starts, so we'll create a new leg. We need to store the name of the caller before calling next_branches() function, because after this call we will lose it:

Sometimes the extra values are not enough. One such scenario is when user A calls to user B, but B doesn't not respond and he's got a redirect to user C. In this case we have two legs, from A to B and from B to C. We may need to account separate information for these legs. In the current scenario caller and callee usernames for both legs will be accounted. There are backends that will generate multiple accounting requests, one for each leg. For example, if using db backend, you will have one line in your table for each leg. All dialogs will be accounted with their CDRs including each destination that we have a missed call with. The backend that will be used is the same as in the previous examples, the syslog backend.

The first part of the declaration is the backend for which the values are declared, in this case the log backend. The following are declarations in form of script-tag->account-tag. The script-tag is the tag used for referencing $acc_extra variable, which will hold all our extra values. The scope of the variable depends on the accounting type used. If the cdr flag is used when calling do_accounting(), the variable will be visible for the whole duration of the dialog, else it will be visible as long as the transaction will be visible. The account-tag is how the information will be identified when accounted, that is the tag identifier for log, column name for db or AVP name for aaa.

This mechanism allows you to extend the CDR field by adding custom fields to it (with data collected anytime during the scope of the accounting).\\

There are SIP scenarios where there is a need to get multiple CDRs for a single SIP call. Typically this happens when implementing call redirect or call forward and the actual SIP call consists out of several call legs (logical calls between SIP entities).\\

Concepts such as accounting events (missed calls, failed calls) , the accounting scope (transaction, dialog), accounting backends (database, log, radius) are explained and covered by full script examples. More complex scenarios including advanced features like extra accounting (extending the CDR format and collecting information from the entire call), and multi-leg accounting (multiple CDR records per SIP call) are also covered.\\

Concepts such as accounting events (missed calls, failed calls) , the accounting scope (transaction, dialog), accounting backends (database, log, radius) are explained and covered by full script examples. More complex scenarios including advanced features like extra accounting (extending the CDR format and collect information from the entire call), and multi-leg accounting (multiple CDR records per SIP call) are also covered.
Everything in this tutorial is backed up with practical examples which you can run and dissect in order to get a better picture about how accounting works, and what are the best accounting options for your needs. Most of the features presented in this tutorial are available in versions starting with OpenSIPS 2.2, where there has been a major rework affecting the accounting module. There are many great improvements over previous versions of OpenSips which will ultimately help you to better understand and use the accounting module.

Concepts such as accounting events (missed calls, failed calls) , the accounting scope (transaction, dialog), accounting backends (database, log, radius) are explained and covered by full script examples. For more complex scenarios, advanced features like extra accounting (extend the CDR format and collect information from the entire call) and multi-leg accounting (multiple CDR records per SIP call) are described and put to work.\\

SIP call accounting is a sensitive and challenging task. The flexibility and complexity of OpenSIPS escalates the need to understand the complete details of the accounting approaches. This tutorial explains all the elements and notions about accounting, as well as how to take full advantage of the powerful accounting engine provided by OpenSIPS.\\

SIP call accounting is a sensitive and challenging task. Even more, the flexibility and complexity of OpenSIPS escalates the understanding and the correctness of the accounting approaches. This tutorial explains all the elements and notions about accounting, as well as how to take full advantage of the powerful accounting engine provided by OpenSIPS.\\

http://opensips.org/images/tutorials/acc_event_success.png

http://opensips.org/images/tutorials/acc_event_missed.png

http://opensips.org/images/tutorials/acc_event_failed.png

http://opensips.org/images/tutorials/acc_event_success.png

http://opensips.org/images/tutorials/acc_event_missed.png

http://opensips.org/images/tutorials/acc_event_failed.png

• message level accounting: the generated CDR covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request(), acc_db_request(), acc_aaa_request() or acc_evi_request() depending on the backend used;

First example will account successful INVITE transactions and all BYE transactions, no matter the response code. The syslog backend shall be used for accounting which has the keyword log. No missed calls shall be accounted.

In this scenario, the default script has be modified, in order to show you how all the missed calls can be accounted when it comes to serial forking. Let's take the case when there is a call for user X but X has multiple contacts, let's call them A, B and C. The order for serial forking should be A, B and C. That is first time we try to call A, if A does not respond B shall be tried and the last try should be made to C. Last, but not least, if the call is to happen(any of A,B or C will respond), CDR will also be accounted. This will happen only for the internally registered users using usrloc module. Same backend shall be used as in the previous example, the syslog daemon.

provision additional information in their account entries. In order to do this we will use the extra accounting engine, with which we will be able to add additional information together with the basic information that is provided by default. All dialogs will be accounted with their CDRs including each destination that we have a missed call with. The backend that will be use is the same as in the previous examples, the syslog backend.

Sometimes the extra values are not enough. One such scenario is when user A calls to user B, but B doesn't not respond and he's got a redirect to user C. In this case we have two legs, from A to B and from B to C. We may need to account separate information for these legs. In the current scenario caller and callee usernames for both legs will be accounted. There are backends that will generate multiple accounting requests, one for each leg. For example, if using db backend, you will have one line in your table for each leg. All dialogs will be accounted with their CDRs including each destination that we have a missed call with. The backend that will be use is the same as in the previous examples, the syslog backend.

The first part of the declaration is the backend for which the values are declared, in this case the log backend. The following are declarations in form of script-tag->account-tag. The script-tag is the tag used for referencing $acc_extra variable, which will hold all our extra values. The scope of the variable depends on the accounting type used. If the cdr flag is used, the variable will be visible for the whole duration of the dialog, else it will be visible as long as the transaction will be visible. The account-tag is how the information will be identified when accounted, that is the tag identifier for log, column name for db or AVP name for aaa. As concers the script, all we need to do is to set $acc_extra variable. In the current scenario we set the domains

The same is the case for $acc_leg variable. The only difference is that this variable can be indexed using the leg number. No index means the current leg. You can also get the number of the last leg using $acc_current_leg variable. New legs can be created with acc_new_leg() function.

If the call is a redirect, we will create a new leg and populate $acc_leg accordingly. The name of the calle will be in the URI populated by next_branches() function.

• message level accounting: the generated CDR covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request(), acc_db_request(), acc_aaa_request() or acc_evi_request() depending on the backend used;

Next every section in the script where do_accounting() function is used will be explained. First of all, we can see that, for every call the log backend is used, which will mean that all the accounted information will go wherever all the other logs will go, that is the LOCAL0 facility of the syslog service for this configuration. One can change this behaviour by modifying the log_facility parameter in the acc modparam section.

The first time we can see do_accounting() function used is on line 127 where the following is used

Not using the failed flag for do_accounting() would have resulted in not having this account line, since the reply code is 400.

The last do_accounting() usage in the script is related only to calls to registered users

The last do_accounting() call from the default script was changed to

To enable serial forking the following lines were added below do_accounting() call.

If do_accounting() would not have been called again, in case of failure, only the first missed call would have been accounted. The flag resets each time a missed call is accounted. next_branches() function call will get the next destination for us. If we still have contacts to call to we arm the failure route again in order to be able to send the message to next destination.

• message level accounting: the generated CDR covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request, acc_db_request, acc_aaa_request or acc_evi_request depending on the backend used;

There are cases when you may need to add some extra values to the default accounted information. Since version 2.3 this engine was modified in order to make it easier for the users to

Starting from the previous script, we try to add extra information about the caller's and callee's domains. First of all we need to define the additional data that will be added to our accounted information in the modparam section using the extra_fields parameter

CDR and serial forking accounting

Extra fields accounting

Multi-leg accounting

ACC: transaction answered: timestamp=1474540760;method=BYE; from_tag=2whdajbp4e-dzLdUwo8-coqaNKKh.oSp;to_tag=11562SIPpTag012; call_id=ezUcDyVPC9jgwtk35eamdhmIo31RSScI;code=400;reason=Reason

ACC: transaction answered: timestamp=1474540997;method=INVITE; from_tag=U49E.iWKOkX1URnBlpKMD.0hM4rIM2U0;to_tag=1173610.0.0.1351; call_id=vonxx1.d4qh9nfPmFBpu46u7Vvq5c8re;code=200;reason=OK

ACC: call missed: timestamp=1474637733;method=INVITE; from_tag=1931529157;to_tag=;call_id=182969767;code=408;reason=Request Timeout

ACC: call ended: created=1474639265;call_start_time=1474639281; duration=5;ms_duration=4250;setuptime=16;method=INVITE;from_tag=1515466979; to_tag=1284910.0.0.1351;call_id=1766189979;code=200;reason=OK

ACC: call ended: created=1474899444;call_start_time=1474899448; duration=5;ms_duration=4762;setuptime=4;method=INVITE;from_tag=1766231375;to_tag=2826210.0.0.1351; call_id=604787970;code=200;reason=OK;caller_domain=X.X.X.X;callee_domain=X.X.X.X

ACC: call missed: timestamp=1474899448;created=1474899444;setuptime=4;method=INVITE; from_tag=1766231375;to_tag=;call_id=604787970;code=408;reason=Request Timeout; caller_domain=10.0.0.135;callee_domain=10.0.0.135;caller=A;callee=B

ACC: call ended: created=1474899444;call_start_time=1474899448;duration=5;ms_duration=4762; setuptime=4;method=INVITE;from_tag=1766231375;to_tag=2826210.0.0.1351;call_id=604787970;code=200;reason=OK; caller_domain=10.0.0.135;callee_domain=10.0.0.135;caller=A;callee=B;caller=B;callee=C

The extra_fields module parameter allows the definition of a list of new fields to be added to the CDR formt. During the script processing, those fields may be populated anywhere and anytime as you are still in the scope of that accounting action. There is a special script variable defined for this mechanism called $acc_extra which can be populated with whatever you want; the $acc_extra variable is persistent across the whole accounting scope - for example, if you do transaction based accounting, you can collect data (to be pushed into the extra accounting fields) during the request handling, in reply route or during a call forking in failure route.
NOTE that you need to take care and adjust your backend (database or radius) to accommodate the extra added values!!

There are SIP scenario where there is a need to get multiple CDRs for a single SIP call. Typically this happens when implementing call redirect or call forward and the actual SIP call consists out of several call legs (logical calls between SIP entities).
The leg_fields module parameter defines a list of new fields that will be different from leg to leg (all the other fields - the default and extra accounting ones - will be the same for all the legs). Each set of leg_fields values will translate into a separate leg for the call.
As said, this shall be useful when logically, there are multiple legs inside a SIP call - like A calls to B and B redirects the call to C, meaning that there are two legs for this call: A to B and B to C. It is the script writer's job to decide whether a new leg has to be created by using acc_new_leg() script function. The variable used to hold the per-leg fields is $acc_leg - anytime, in the context of that leg, you can set the values for the per-leg fields.
NOTE that you need to take care and adjust your backend (database or radius) to accommodate the extra added values!!

Basic accounting

This mechanism allow you to extend the CDR field by adding custom fields to it (with data collected anytime during the scope of the accounting).
The extra_fields module parameter allows the definition of a list of new fields to be added to the CDR formt. During the script processing, those fields may be populated anywhere and anytime as you are still in the scope of that accounting action. There is a special script variable defined for this mechanism called $acc_extra which can be populated with whatever you want; the $acc_extra variable is persistent across the whole accounting scope - for example, if you do transaction based accounting, you can collect data (to be pushed into the extra accounting fields) during the request handling, in reply route or during a call forking in failure route.

Accounting scopes

Accounting backends

Extending the accounting engine

Extra accounting fields

This mechanism allow you to extend the CDR field by adding custom fields to it (with data collected anytime during the scope of the accounting).

Multi-leg accounting

Accounting scope

The accounting CDR may have different scopes and may get aligned to different SIP entities :

• message level accounting: the generated CDR covers only the currently processed SIP request; this is also known as manual accounting, where the CDR is generated on the spot by using one of the script functions acc_log_request, acc_db_request, acc_aaa_request or acc_evi_request depending on the backend used;
• transaction level accounting: the generated CDR covers only one SIP transaction; such accounting is used when OpenSIPS is used as a stateful SIP proxy; the accounting is triggered when the request is processed and the CDR will be generated when the SIP transaction (including all its branches) will be completed;
• dialog level accounting: the generated CDR covers a whole SIP call; you have to enable it when the initial INVITE is processed and the actual CDR will be generated when the dialog ends(that is when all the messages belonging to a dialog have been processed, including the replies for BYE messages);

Documentation -> Tutorials -> Call Accounting

Overview

The SIP call accounting is a sensitive and challenging task. Even more, the flexibility and complexity of OpenSIPS escalates the understanding and the correctness of the accounting approaches. This tutorial explains all the elements and notions about accounting, as well as how to take full advantage of the powerful accounting engine provided by OpenSIPS.
Concepts as accounting events (missed calls, failed calls) , the accounting scope (transaction, dialog), accounting backends (database, log, radius) are explained and covered by full script examples. For more complex scenarios, advanced features like extra accounting (extend the CDR format and collect information from the entire call) and multi-leg accounting (multiple CDR records per SIP call) are described and put to work.
Everything in this tutorial is backed up with practical examples which you can run and disect in order to get a better picture about how accouting works and what can be the best option for your needs. Most of the features presented in this tutorial are available in versions starting with OpenSIPS 2.2, when there's been a major rework affecting the accounting module. There are many great improvements since the previous version which will ultimately help you having an easier jobs understanding and using the module.

Accounting events

OpenSIPS can account different events happening during a transaction/dialog lifetime, such as:

• successful transactions/dialogs: transaction/call has successfully established from the UAC/caller perspective; it can be only one such event per SIP call;
• missed calls: a call branch did not established, as the UAS rejected or declined the call attempted ; there can be multiple such events per a single SIP call (due SIP forking). Note that a SIP call that generated a ACC successfully established event may generate some missed call event (for the SIP branches that failed during serial or parallel forking); The missed call events are also known as UAS-side accounting (as they are related to the relation between OpenSIPS and callee/UAS side).
• failed transaction: generated when a transaction fails (reply code >=300) on the UAC side of OpenSIPS - this is a complementary event for the successfully transaction event.

Sometimes the extra values are not enough. One such scenario is when user A calls to user B, but B doesn't not respond and he's got a redirect to user C. In this case we have two legs, from A to B and from B to C. We may need to account separate information for these legs. In the current scenario caller and callee usernames for both legs will be accounted. There are backends that will generate multiple accounting requests, one for each leg. For example, if using db backend, you will have one line in your table for each leg.

The modparam declaration for leg_fields is very similar to the extra_fields

modparam("acc", "leg_fields", "log: caller; callee")

The same is the case for acc_leg variable. The only difference is that this variable can be indexed using the leg number. No index means the current leg. You can also get the number of the last leg using acc_current_leg variable. New legs can be created with acc_new_leg function.

In the script, everything that concerns lookup function was moved into a route, in order to use it multiple times. For the initial call, we'll get the name of the caller from the From header. The name of the callee is in the R-URI:

      $acc_leg(caller) = $fU;
      $acc_leg(callee) = $rU;

In case our call to B as described upwards fails we'll get to failure route where we will fetch the next destination, as usual. For redirects, we check if the new destination is a local uri, meaning that we have to resolve the same way we did with the first uri, using lookup function. Now the call from B to C starts, so we'll create a new leg. We need to store the name of the caller before calling next_branches() function, because after this call we will lose it:

        $var(old_rU) = $rU;

        next_branches();

If the call is a redirect, we will create a new leg and populate acc_leg accordingly. The name of the calle will be in the URI populated by next_branches() function.

        /* local contact; lookup needed */
        if (uri == myself) {
                acc_new_leg();
                $acc_leg(caller) = $var(old_rU);
                $acc_leg(callee) = $rU;

                route(lookup);

                serialize_branches(1);
        }

For one redirect, we will have two account lines. One for the missed call from A to B

ACC: call missed: timestamp=1474899448;created=1474899444;setuptime=4;method=INVITE;from_tag=1766231375;to_tag=;call_id=604787970;code=408;reason=Request Timeout;caller_domain=10.0.0.135;callee_domain=10.0.0.135;caller=A;callee=B

and the CDR record, with both legs, A to B and B to c:

ACC: call ended: created=1474899444;call_start_time=1474899448;duration=5;ms_duration=4762;setuptime=4;method=INVITE;from_tag=1766231375;to_tag=2826210.0.0.1351;call_id=604787970;code=200;reason=OK;caller_domain=10.0.0.135;callee_domain=10.0.0.135;caller=A;callee=B;caller=B;callee=C

If using db engine two lines will be generated, one with the leg from A to B and one with the leg from B to C. The rest of the information will be the same.

As concers the script, all we need to do is to set acc_extra variable. In the current scenario we set the domains

        $acc_extra(caller_domain) = $rd;
        $acc_extra(callee_domain) = $td;

The CDR for the current call will contain the new extra values, as we set them

ACC: call ended: created=1474899444;call_start_time=1474899448;duration=5;ms_duration=4762;setuptime=4;method=INVITE;from_tag=1766231375;to_tag=2826210.0.0.1351;call_id=604787970;code=200;reason=OK;caller_domain=X.X.X.X;callee_domain=X.X.X.X

Extra values accounting

    There are cases when you may need to add some extra values to the default accounted information. Since version 2.3 this engine was modified in order to make it easier for the users to 

provision additional information in their account entries.

     Starting from the previous script, we try to add extra information about the caller's and callee's domains. First of all we need to define the additional data that will be added to our accounted information in the modparam section using the extra_fields parameter

   modparam("acc", "extra_fields", "log: caller_domain; callee_domain")

The following definition would also be valid

   modparam("acc", "extra_fields", "log: caller_domain->callee_domain; callee_domain->callee_domain")

The first part of the declaration is the backend for which the values are declared, in this case the log backend. The following are declarations in form of script-tag->account-tag. The script-tag is the tag used for referencing acc_extra variable, which will hold all our extra values. The scope of the variable depends on the accounting type used. If the cdr flag is used, the variable will be visible for the whole duration of the dialog, else it will be visible as long as the transaction will be visible. The account-tag is how the information will be identified when accounted, that is the tag identifier for log, column name for db or AVP name for aaa. I

Multi-leg accounting

Here, aside from the basic information that is present in every account record we can see the call_start_time, and the call duration both in seconds and milliseconds.

If do_accounting would not have been called again, in case of failure, only the first missed call would have been accounted. The flag resets each time a missed call is accounted. next_branches() function call will get the next destination for us. If we still have contacts to call to we arm the failure route again in order to be able to send the message to next destination.

First of all, in order to be able to use the CDR engine, dialog module needs to be loaded

loadmodule "dialog.so" modparam("dialog", "db_mode, 0)

The last do_accounting call from the default script was changed to

        # when routing via usrloc, log the missed calls also
        do_accounting("log","cdr|missed");

which, aside from the missed calls, enables logging the CDRs. Keep in mind that the CDR flag affects only the calls(dialogs). To enable serial forking the following lines were added below do_accounting call.

        serialize_branches(1);

@]

In the failure route the following lines were added: [@

       do_accounting("log","missed");

        next_branches();

The reply code and the reason may change depending on the scenario. If at least one of the contacts answered and the call is established, a CDR will be generated after the call ended:

ACC: call ended: created=1474639265;call_start_time=1474639281;duration=5;ms_duration=4250;setuptime=16;method=INVITE;from_tag=1515466979;to_tag=1284910.0.0.1351;call_id=1766189979;code=200;reason=OK

Here, aside from the basic information that is present in every account record we can see the call_start_time, the duration both in seconds and milliseconds.

CDR and serial forking accounting

In this scenario, the default script has be modified, in order to show you how all the missed calls can be accounted when it comes to serial forking. Let's take the case when there is a call for user X but X has multiple contacts, let's call them A, B and C. The order for serial forking should be A, B and C. That is first time we try to call A, if A does not respond B shall be tried and the last try should be made to C. Last, but not least, if the call is to happen(any of A,B or C will respond), CDR will also be accounted. This will happen only for the internally registered users using usrloc module.

The last do_accounting call from the default script was changed to

        # when routing via usrloc, log the missed calls also
        do_accounting("log","cdr|missed");

which, aside from the missed calls, enables logging the CDRs. Keep in mind that the CDR flag affects only the calls(dialogs). To enable serial forking the following lines were added below do_accounting call.

        serialize_branches(1);
        next_branches();

In the failure route the following lines were added:

       do_accounting("log","missed");

        next_branches();
        # if we've got any more branches arm the failure route
        if ($rc != 2) {
                t_on_failure("missed_call");
        }

        if (!t_relay()) {
                send_reply("500","Internal Error");
        };

If do_accounting would not have been called again, in case of failure, only the first missed call would have been accounted. The flag resets each time a missed call is accounted. next_branches() function call will get the next destination for us. If we still have got contacts to call to we arm the failure route again in order to be able to send the message to next destination.

A missed call account event will be generated for each destiantion that did not respond looking like this

ACC: call missed: timestamp=1474637733;method=INVITE;from_tag=1931529157;to_tag=;call_id=182969767;code=408;reason=Request Timeout

The reply code and the reason may change depending on the scenario. When the call is established we will receive a basic accounting line confirming this

ACC: transaction answered: timestamp=1474637744;method=INVITE;from_tag=1931529157;to_tag=1195810.0.0.1351;call_id=182969767;code=200;reason=OK

Next in the script we can see the following line

        # account only INVITEs
	if (is_method("INVITE")) {
		do_accounting("log");
	}

As you can see, this function call applies only to INVITE transactions where the request is also an initial request, sequential requests are handled above. Since no flag is specified, only successful transactions will be accounted. Accounted information will look more or less the same as the one for the BYE transaction:

ACC: transaction answered: timestamp=1474540997;method=INVITE;from_tag=U49E.iWKOkX1URnBlpKMD.0hM4rIM2U0;to_tag=1173610.0.0.1351;call_id=vonxx1.d4qh9nfPmFBpu46u7Vvq5c8re;code=200;reason=OK

The last do_accounting usage in the script is related only to calls to registered users

        # when routing via usrloc, log the missed calls also
        do_accounting("log","missed");

For them missed calls accounting is also enabled. Keep in mind that missed call accounting is related only to INVITE transactions, it will have no effect for other types.

CDR accounting with failover support

Next every section in the script where do_accounting function is used will be explained. First of all, we can see that, for every call the log backend is used, which will mean that all the accounted information will go wherever all the other logs will go, that is the LOCAL0 facility of the syslog service for this configuration. One can change this behaviour by modifying the log_facility parameter in the acc modparam section.

The first time we can see do_accounting function used is on line 127 where the following is used

        if (has_totag()) {
                # sequential requests within a dialog should
                # take the path determined by record-routing
                if (loose_route()) {

                        if (is_method("BYE")) {
                                # do accunting, even if the transaction fails
                                do_accounting("log","failed");
                        }
         ...
        }

This line will account all the BYE transactions, including the failed transactions(reply code >= 300). Here is an example of how the accounted lines should look line in your syslog

ACC: transaction answered: timestamp=1474540760;method=BYE;from_tag=2whdajbp4e-dzLdUwo8-coqaNKKh.oSp;to_tag=11562SIPpTag012;call_id=ezUcDyVPC9jgwtk35eamdhmIo31RSScI;code=400;reason=Reason

Not using the failed flag for do_accounting would have resulted in not having this account line, since the reply code is 400.

 do_accounting

By default OpenSIPS comes with a sample script called opensips.cfg which uses the accounting module. In the following lines every line that involves the module shall be explained.

First of all, the module is loaded using the modparam statement. All the parameters declared here have their default value, so they can be very easily removed.

Next let's explain every section in the script where do_accounting function is used.

opensips.cfg sample script

{@opensips.cfg@} sample script

opensips.cfg sample script

loadmodule "acc.so"
/* what special events should be accounted ? */
modparam("acc", "early_media", 0)
modparam("acc", "report_cancels", 0)
modparam("acc", "detect_direction", 0)

Extending the accounting engine

Examples

Intro

Starting from default opensips script examples will be given which will help have a better picture about how accounting works in OpenSIPS and how the parameter can be used in real case scenarios.

Accounting backends

When doing accounting, one can choose between a variety of engines to do accounting with or even combine them together:

• log: the accounting shall be logged wherever you choose to log it, via syslog, either in the same location as the OpenSIPS logs or in any other location you choose; backend
• db(database): use one of the many database backends currently implemented in OpenSIPS(mysql, postgres, sqlite etc.);
• aaa: account your data using an aaa protocol(currently only radius is available);
• evi: information shall be accounted using the event interface;

IMPORTANT: In order to uses these features, some settings need to be made. That is, if you will use the database engine, the default accounting table will have to be changed. Also for aaa accounting, if using AVPs that are not defined, they will have to be defined in the dictionary.

IMPORTANT: In order to uses these features, some settings need to be made. That is, if you will use the database engine, the default accounting table will have to be changed. Also for aaa accounting, if using AVPs that are not defined, they will have to be defined in the dictionary.

• missed calls: accounts a missed call; callee did not answer the call
• failed transaction: accounts a failed transaction(reply code >=300)

Extending accounting engine

There might be cases when extra information, other than what's already accounted, might be needed. For this we've got:

• extra_fields: you can define new fields for the accounting engine which shall be populated at the time when the accounting is being made; there is a special variable defined for this mechanism called acc_extra which can be populated with whatever you want; the acc_extra variable is persistent as concerns messages, transactions and dialogs, depending of the type of transaction used;
• leg_fields: almost the same as the extra data, but this time one can set multiple legs for a call, which will result in multiple accounting requests; this shall be useful when logically, there are multiple calls, that is A calls to B and B redirects the call to C, meaning that there are two legs for this call: A to B and B to C. It is the script writer's job to decide whether a new leg has been created using acc_new_leg script function. The variable used to define extra leg fields is acc_leg;

''IMPORTANT': In order to uses these features, some settings need to be made. That is, if you will use the database engine, the default accounting table will have to be changed. Also for aaa accounting, if using AVPs that are not defined, they will have to be defined in the dictionary.

Accounting concepts

Accounting scope

Depending on the type of the accounting, there are multiple possibilities as concerns the scope:

• message level accounting: this is mostly used when the reply is internally generated, OpenSIPS being the endpoint for a certain transaction; accounting is being made on the spot and this can be achieved using one of the following acc_log_request, acc_db_request, acc_aaa_request or acc_evi_request depending on the backend used;
• transaction level accounting: that is when OpenSIPS is a proxy forwarding requests and replies; this transaction shall be accounted only at the moment when the reply came.
• dialog level accounting: this type of accounting shall be used for accounting CDRs; you have to enable it when the initial INVITE have been received and the actual accounting shall be made when the dialog ends(that is when all the messages belonging to a dialog have been processed, including the replies for BYE messages);

Accounting events

OpenSIPS can account all the events happening during a transaction/dialog lifetime, that is:

• successful transactions/dialogs: transaction has ended without any issues;
• missed calls: a called t

This tutorial will describe the means through which accounting can be made in latest OpenSIPS versions, the types of accounting that can be made(dialogs, missed calls etc.), the level of the accounting(message level, transaction level, dialog level), the available backends(syslog, databases...) and some optional features(extra and leg accounting). Alongside the first half of the tutorial there will be a brief description about all these above mechanisms followed by practical examples which you can read in order to have a better picture about how everything works and what can be the best option for your needs. Most of the features presented in this tutorial are available only since version 2.2, when there's been a major rework affecting the accounting module. There are many great improvements since the previous version which will ultimately help you having an easier jobs understanding and using the module.

Accounting scope

(:toc-float Table of Content:)

Tutorial Scope

This tutorial will describe the means through which accounting can be made in latest OpenSIPS versions, the types of accounting that can be made(dialogs, missed calls etc.), the level of the accounting(message level, transaction level, dialog level), the available backends(syslog, databases...) and some optional features(extra and leg accounting). In the first part of the tutorial there will be a brief description about all these above mechanisms followed by practical examples which you can read in order to have a better picture about how everything works and what can be the best option for your current project.

Documentation -> Tutorials -> Advanced Accounting

This page has been visited 24612 times. (:toc-float Table of Content:)