Contents

1   Event-Based Monitoring Interface Overview

This document describes the format of the Event-Based Monitoring (EBM) output produced by the Service Aware Policy Controller (SAPC).

The supported EBM output is as follows:

• Binary stream in real time to an external system over Transmission Control Protocol (TCP)

To help in the post processing of the output information generated by the EBM function, this document includes the following information:

• The binary stream
• The XML file that defines the format of the binary stream
• The schema file that defines the structure of the XML file
• The relationships between the binary stream, the schema file, and the XML file
• Information on using the schema file to interpret the XML file, and using the XML file to interpret the binary stream

Note:  

This document does not contain the events generated by the SAPC, their cause codes, or the event parameters.

1.1   Typographic Conventions

Typographic conventions can be found in the following document:

• Typographic Conventions

2   Description

The contents of the EBM output can be used for Business Intelligence. The EBM output can be streamed in real time to an external system over TCP. An XML file available on the SAPC describes the binary format of the generated streamed output.

3   Output Format Elements

The EBM output is composed of a binary stream that is formatted as defined in the XML file and the schema file.

The relationships between the schema file, XML file, and binary stream are shown in Figure 1.

4   XML File

The XML file, sapc_ebm.xml, defines the data format of the binary stream, and is used to decode the binary stream. The structure of the XML file is shown in Figure 2.

The XML file contains a detailed description of each element of the binary stream. The following sections describe the individual parts of the XML file.

4.1   General

The general part of the XML file contains general information about the XML file. The structure of the general part is shown in Figure 3.

The following example shows how general information is presented in the actual XML file.

<general>
    <docno>14/155 19-CSH 109 215/7</docno>
    <revision>PA1</revision>
    <date>2018-02-08</date>
    <author>BDGSLFDG Almudena Mozas</author>
    <ffv>2</ffv>
    <fiv>10</fiv>
</general>

4.2   Parameter Types

The parametertypes part of the XML file defines parameters that are used as simple entities in the binary stream. Parameters compose the structures defined in the structuretypes part.

Parameters defined in the parametertypes part and structures defined in the structuretypes part are used to construct events and records. For more information on events and records, see Section 4.4 and Section 4.5.

The structure of the parametertypes part in the XML file is shown in Figure 4.

The XML file details the individual parameters in a readable format. Table 1 shows the elements used to describe the parameters.

Some parameters have an optional flag set to TRUE in the XML file, indicating that these parameters are optional. The most significant bit of these parameters determines their presence in the event stream. If it is set to 0, the parameter is present in the event stream. If it is set to 1, the parameter is not present in the event stream.

The following example shows how the parameter type is described in the actual XML file.

<parametertype>
    <name>QOS_PROFILE_ID</name>
    <type>UINT</type>
    <description>Provides the ID of the QoS Profile.</description>
    <numberofbits>16</numberofbits>
    <range>
      <low>0</low>
      <high>65535</high>
    <range/>
 </parametertype>

In the case of parameters with type STRING, DNSNAME, BYTEARRAY, the actual parameter value is always a multiple of 8-bit words. This is achieved by adding a 0 bit padding as needed between lengthbits XML tag value and the start of the actual parameter value.

The following example shows a 0 bit padding to an optional BYTEARRAY parameter.

Parameters with type STRING are encoded as UTF-8.

4.3   Structure Types

The structuretypes part of the XML file defines structures that are used as complex entities in the binary stream.

Some structures can appear several times in the same event, which is referred to as repeated parameter sets. The seqmaxlen octet specifies the number of times the structure is repeated for the specific event. In the XML file, these structures have the seqmaxlen flag set to the maximum number of times the structure can be repeated for the event.

The structure of the structuretypes part in the XML file is shown in Figure 6.

The following example shows how PDN structure type is described in the actual XML file.

<structuretype>
    <name>PDN_INFO</name>
    <elements>
        <param type="BEARER ID" optional="true" >DEFAULT_BEARER_ID</param>
        <param type="APN" optional="true" >APN</param>
        <struct type="IPADDRESS_STRUCT">ALLOCATED_UE_ADDRESS</struct>
        <param type="RULE SPACE" optional="true">RULE_SPACE</param>
    </elements>
</structuretype>

4.4   Events

The events part of the XML file defines the events that are monitored in the binary stream.

Events consist of parameters, defined in the parametertypes part of the XML file, and structures, defined in the structuretype part of the XML file.

The structure of the events in the XML file is shown in Figure 7.

The following example shows how the reported usage event is described in the actual XML file.

<event>
    <name>REPORTED_USAGE</name>
    <id>7</id>
    <triggerdescription></triggerdescription>
    <comment>Provides usage information</comment> 
    <elements>
        <struct type="HEADER">HEADER</struct>
        <param type="CAUSE_PROTOCOL">CAUSE_PROTOCOL</param>
        <param type="CAUSE_CODE">CAUSE_CODE</param>
        <struct type="PDN_INFO">PDN_INFO</struct>
        <struct type="UE_INFO">UE_INFO</struct>
        <param type="SESSION_ID">SESSION_ID</param> 
        <struct seqmaxlen="50" type="REPORTING_GROUP_USAGE_INFO">REPORTING_GROUP_USAGE_INFO</struct>
    </elements>
</event>

4.5   Records

The records part of the XML file defines the events that are created in the binary stream.

Records consist of parameters, defined in the parametertypes part of the XML file, and structures, defined in the structuretype part of the XML file.

The structure of the records in the XML file is shown in Figure 8.

The following example shows how the header record is described in the actual XML file.

<record>
    <name>HEADER_RECORD</name>
    <type>0</type>
    <elements>
        <param type="RECORD_LENGTH">RECORD_LENGTH</param>
        <param type="RECORD_TYPE">RECORD_TYPE</param>
        <param type="FILE_FORMAT_VERSION">FILE_FORMAT_VERSION</param>
        <param type="FILE_INFORMATION_VERSION">FILE_INFORMATION_VERSION</param>
        <param type="TIME_YEAR">TIME_YEAR</param>
        <param type="TIME_MONTH">TIME_MONTH</param>
        <param type="TIME_DAY">TIME_DAY</param>
        <param type="BYTE_HOUR">BYTE_HOUR</param>
        <param type="BYTE_MINUTE">BYTE_MINUTE</param>
        <param type="BYTE_SECOND">BYTE_SECOND</param>
    </elements>
</record>

5   XML File Schema

The Event_Format_description.xsd schema file defines the syntax of the XML file, and is used to validate the XML file structure.

6   Binary Stream Output Format

The following subsections detail the structure of the binary stream.

6.1   Logical Format

The format of the EBM streamed data is shown in Figure 9.

The binary stream is composed of a series of records, which are broken up into shorter segments. Each segment consists of:

• A stream header record
• Conditional stream error records
• A sequence of event records

For descriptions of the stream header record, the stream error record, and the event record, see Section 6.4.

6.2   Data Format

The EBM records generated by the SAPC are encoded in an Ericsson proprietary bit-packed binary format. The following notations are used in the descriptions:

6.3   Record Padding

The length of each record is always a multiple of 32-bit (4 byte) words. If the last 32-bit word of a record is less than 32 bits long, record padding is performed. Record padding sets all unused bits in the last 32-bit word of the record to 0.

Figure 10 shows an example of record padding.

6.4   Record Descriptions

The following subsections describe the individual records that are included in the binary stream.

6.4.1   Stream Header Record

The stream header record is displayed in the stream to provide administrative information about the streamed data. The date and time indicate when the stream was started or restarted in UTC time.

Table 2 shows the contents of a stream header record.

(1)  The FFV is incremented if there is a change in the file format.

(2)  The FIV is incremented if there is a change in the file information.

(3)  The 60 second value indicates a leap second.

(4)  The UTC sign with the UTC hour and minute offset indicate the time difference between the local time and the UTC time. The value 0 stands for the sign +, and the value 1 stands for the sign -.

(5)  The cause of header indicates the reason why the Stream Header Record was sent. Values: 0 = Stream enabled. 1 = Stream restart after communication failure. 2 = Stream restart after reconfiguration. 3 = Local time is changed. 4 = Other reason.

(6)  ASCII characters with variable length.

6.4.2   Stream Error Record

The stream error record is only included if an error occurs which might have resulted in some event records being discarded. It contains information about the reason for the error, the number of discarded events, and the time of the error situation recovery.

Table 3 shows the contents of a stream error record.

(1)  The 60 second value indicates a leap second.

(2)  Values: 0 = Other. 1 = Communication error. No TCP connections available to the EBM server. 2 = Congestion. The SAPC generates more EBM events than the number of EBM events that it can send to the EBM server. The SAPC sends the number of dropped events in a Stream Error Record when new events can be sent.

Figure 11 shows an example of Stream Error Record due to congestion.

6.4.3   Event Record

Event records follow stream header records or stream error records in segments.

Event records contain event data, including event identity and event result.

Table 4 shows the contents of an event record.

(1)  Record length requires 2 bytes, even though 1 byte would be sufficient. The maximum size of EBM record is 65535 bytes. If the event record maximum size is surpassed, the SAPC drops the event record.

(2)  The bit-packed part of the event records is composed of a sequence of variable length fields. The length of the bit-packed part can be a multiple of 32-bit (4 byte) words. The Most Significant Bit (MSB) is displayed first in each field. If the last 32-bit (4 byte) word of a record is not exactly 32 bits (4 byte) long, padding is performed. Padding is setting all unused bits in the last 32-bit (4 byte) word of the record to 0.

Each event record contains a bit-packed part. Its content is included in Table 5.

(1)  Event-specific field in bit-packed event records.

(2)  Value 60 indicates a leap second.

(3)  Duration provides timing information with millisecond granularity for the signaling procedure. The duration value is calculated from the time when the signaling procedure starts and the time when the signaling procedure ends. The signaling procedure starts when the first request is received or sent. The signaling procedure ends when the first accept or reject response is sent or received. If the duration of the event exceeds 16777215 ms, the value of the DURATION parameter starts counting from 0 again.

The common part of event records is followed by event-specific parameters. These event-specific parameters are defined in the XML file.

For further information on the XML file, see Section 5.

7   Directory Structure

The schema file Event_Format_description.xsd, the sapc_ebm.xml and the ebm_cause_codes.xml files can be copied from the SAPC to an external post processing system using SFTP protocol. The files are stored in the EBM directory on the SAPC, using the following path: /storage/no-backup/ebm.