acc_syslog 7
acc_syslog Transaction Accounting into the System Log

## Description

The `acc_syslog` SER module stores information about processed SIP transactions in the system log.

Unlike most other modules, `acc_syslog` is normally not used by calling one of its functions. Instead, it is invoked by setting a certain flag and then starting a transaction by calling a function from the tm module, usually t_relay.

There are two flags. Their names are determined by the module parameters log_flag and log_missed_flag respectively. The former is intended to be used for all transactions that are involved in a successfully established call, while the latter is to be used for transactions of a failed call attempt. If either of the flags is set, a line is written to the system log upon completion of the transaction. The difference between the two flags lies in the text that starts the entry. If the log_flag is set, the entry starts with the text `"ACC: transaction answered"`, while the log_missed_flag causes the entry to start with `"ACC: call missed"`.

Neither flag is set by default. In order to activate the writing of accounting entries, you have to explicitely choose flags by setting the module parameters.

Normally, you can use the same flag for both parameters since `acc_syslog`'s internal logic takes care of figuring out the right introduction. It only uses `"ACC: transaction answered"` if the transaction ended with a final response sent upstream with a 2xx status, ie., was successful. Likewise, the module starts entries with `"ACC: call missed"` if the final response sent upstream had a status of 300 or up.

Note that the `acc_syslog` module only writes accounting entries for individual transactions. A call usually consists at least of an INVITE and a BYE transaction for the start and end of a call. Searching the accounting records for the call and translating them into call detail records is not performed by the module.

## Functions

### `acc_syslog_log` ([status])

Allowed in request and failure processing.

The `acc_syslog_log()` function forces `acc_syslog` to write a syslog entry with information taken from the currently processed request. The entry will by prefixed with the phrase `"ACC: request accounted"`.

If the argument status is given, it contains the status code that should be stored in the field `sip_status`. If it is missing, the field will be set to `0`.

### `acc_syslog_missed` ([status])

Allowed in request and failure processing.

The `acc_syslog_log()` function forces `acc_syslog` to write a syslog entry with information taken from the currently processed request. The entry will by prefixed with the phrase `"ACC: call missed"`.

If the argument status is given, it contains the status code that should be stored in the field `sip_status`. If it is missing, the field will be set to `0`.

## Module Parameters

### attrs

string ""

The attrs parameter contains a comma separated list of those attributes whose values should be written in the accounting entry. See the description of the field `attrs` in the section Syslog Entries below for information on how these values are stored.

### early_media

boolean no

The early_media parameter determines, whether the arrival of a reponse 183 (Session Progress) should trigger writing of an accounting entry, too. If the parameter is set to `yes`, a 183 response will be treated as a successful response and an entry will be written if the log_flag is set.

### failed_transaction

boolean no

The failed_transactions parameter determines, whether transaction with a final response indicating a failure (ie., status codes of 300 and up) should be accounted too if the log_flag is set.

The value of the failed_transactions parameter has no influence on accounting if the log_missed_flag is set, in which case the transaction will be accounted for only if the final response indicates a failure.

### log_flag

flag name none

The log_flag parameter sets the name of the flag that decides whether information about a succeeeded transaction (ie., one with a final response from the 2xx group) is to be written to the system log.

By setting the early_media and failed_transactions to `yes` setting the log_flag also triggers writing for 183 provisional responses and failed transactions respectively.

### log_fmt

string "acdfgimnoprstuxDFIMPRSTUX"

The log_fmt parameter determines, which information is written to the system log. Its value is a string. The various fields described in the section Syslog Entries below are assigned a letter. If the letter for the field is included in the string, the field will be written.

The mapping between letters and fields is as follows:

`a`
  attr
`c`
  sip_callid
`d`
  to_tag
`f`
  sip_from
`g`
  flags
`i`
  in_ruri
`m`
  sip_method
`n`
  sip_cseq
`o`
  out_ruri
`p`
  src_ip
`r`
  from_tag
`t`
  sip_to
`u`
  digest_username
`x`
  request_timestamp
`D`
  to_did
`F`
  from_uri
`I`
  from_uid
`M`
  from_did
`P`
  src_port
`R`
  digest_realm
`S`
  sip_status
`T`
  to_uri
`U`
  to_uid
`X`
  response_timestamp

By default, all of the fields are active.

### log_level

int 2

The log_level parameter sets the log level that `acc_syslog` will use when writing to the syslog. Its value is an integer that correspondents to the priority values defined by syslog as follows:

`4`
  `debug`
`3`
  `info`
`2`
  `notice`
`1`
  `warning` (or `warn`)
`-1`
  `err` (or `error`)
`-2`
  `crit`
`-3`
  `alert`

Note that the log_level must be at less or equal than the core parameter debug or no entries will be written at all.

### log_missed_flag

flag name none

The log_missed_flag parameter sets the name of the flag that decides whether information about a failed transaction (ie., one with a final response of status 300 or up) is to be written to the system log.

### report_ack

boolean no

The report_ack parameter determines, whether a separate accounting entry should be written for the ACK following a 200 OK response. If activated, such entries will be written with the starting text `"ACC: request acknowledged"`.

Usually, having the entry for the first transaction is enough and no additional entry is necessary. There is, however, a chance that the ACK does not reach its destination and the call does in fact not start. If you need to know about those cases, you can enable the report_ack parameter and check that there is an ACK for every INVITE.

### report_cancels

boolean no

The report_cancels parameter determines, whether accounting entries should be made for CANCEL transactions.

You can recognize a canceled transaction by its status 487 in the `sip_status` field. Because of this, there is usually no need for the extra entries the CANCEL transaction itself may create.

## Syslog Entries

All accounting entries that are written to the system log consist of a single line. It is started with any of the prefixes mentioned above, followed by a colon and a comma-separated list of accounting fields. Each field has a name, followed by an equals sign followed by the fields value.

Which entries will be written is determined by the module parameter log_fmt. By default, it prints all available fields.

The following lists and explains all the accounting fields.

### `attrs`

The `attrs` field will contain the attribute and their values that have been selected for storing with the accounting entry.

The field will contain a comma separated list of entries. Each entry will start with the name of the attribute, followed by a colon, followed by its value enclosed in double quotation marks. Which attributes will be in the list is controlled by the attrs module parameter.

### `digest_username`

The `digest_username` field will contain the username used in authenticating the request. If no authentication was done or the authentication failed, the field will be `NULL`.

### `digest_realm`

The `digest_realm` field will contain the realm used in authenticating the request. If no authentication was done or it failed, the field will be `NULL`.

### `flags`

The `flags` field will contain the combined numerical value of the flags that where set for the transaction when the entry was written. The value is determined by treating the flags as a bit field with the flag's number as the number of the corresponding bit.

### `from_did`

The `from_did` field will contain the domain ID determined for the callee's domain and stored in the `$fd.did` attribute or `NULL` if the attribute was not set.

### `from_tag`

The `from_tag` field will contain the value of the tag parameter of the From header field of the request.

### `from_uid`

The `from_uid` field will contain the user ID determined for the callee and stored in the `$fu.uid` attribute or `NULL` if the attribute was not set.

### `from_uri`

The `from_uri` field will contain the URI of the From header field of the request.

### `in_ruri`

The `in_ruri` field will contain the Request-URI the request arrived with.

### `out_ruri`

The `out_ruri` field will contain the Request-URI of the winning branch, ie., of that relayed request which caused the final response that was sent upstram.

### `request_timestamp`

The `request_timestamp` field will contain the date and time when the request was received, ie., when the transaction started.

### `response_timestamp`

The `response_timestamp` field will contain the date and time when the response was sent upstream, ie. when the transaction ended.

### `server_id`

The `server_id` field will contain the server ID of the SER instance that processed the transaction. This is useful in a cluster of several SER machines. By giving each machine its own server_id you can later determine, which server the accounting entry originated from.

### `sip_callid`

The `sip_callid` field will contain the content of the Call-ID header field of the request.

### `sip_cseq`

The `sip_cseq` field will contain the sequence number contained in the CSeq header field of the request. The method in that header field (which should be identical to the method of the request) can be found in the sip_method field.

### `sip_from`

The `sip_from` field will contain the content of the From header field of the request.

### `sip_method`

The `sip_method` field will contain the method of the request.

### `sip_status`

The `sip_status` field will contain the status code of the final response or, if early_media is set, 183 response transmitted upstream for the transaction.

### `sip_to`

The `sip_to` field will contain the content of the To header field of the request.

### `src_ip`

The `src_ip` field will contain the source IP address of the received request.

### `src_port`

The `src_port` field will contain the source port of the received request.

### `to_did`

The `to_did` field will contain the domain ID determined for the caller's domain and stored in the `$td.did` attribute or `NULL` if the attribute was not set.

### `to_tag`

The `to_tag` field will contain the value of the tag parameter of the response sent upstream or `NULL` if the response was missing this parameter.

### `to_uid`

The `to_uid` field will contain the user ID determined for the caller and stored in the `$tu.uid` attribute or `NULL` if the attribute was not set.

### `to_uri`

The `to_uri` field will contain the URI of the To header field of the request.

## See Also

- ser
- ser.cfg
- acc_db
- acc_radius
- tm
- syslogd