KPI Logging

Added as part of the LumenVox version 15.0 release was a new feature to log Key Performance Indicators (KPIs) that allows system administrators to periodically log out a number of important metrics that describe the performance of LumenVox services.

This mechanism is controlled by the Manager service, which generates these logged events when enabled. 

Several related settings are located in the manager.conf settings file, or using the Dashboard configuration page for the Manager service. These various settings are also described below.

KPI_INTERVAL

To enable KPI Logging, the KPI_INTERVAL setting must be set to a non-zero value. This is the number of minutes between logging intervals, and can be set to an integer between 0 (KPI logging disabled) and 1440 (minutes , or 1 day)

When this interval is non-zero, KPI logging is enabled, and a new record of these indicators will be recorded at the specified interval. For example, if KPI_INTERVAL is set to a value of 60, a new set of KPI values will be logged every 60 minutes.

After KPI values have been reported to a log file, these values are reset so that only the values relating to the KPI Interval are recorded.

KPI_ROOT_FOLDER

KPI logging is stored in the folder specified by this setting. In addition, this folder should be regarded as the root folder for these files, since they are located in sub-folders below this root folder according to date and time.

If no KPI_ROOT_FOLDER is specified (the default), then the LVLOGS folder will be used as the root for these sub-folders and files.

You should ensure that the manager service or daemon has write access to whichever KPI root folder you select

KPI_NODE_ID

This is an optional setting that can be used to identify KPI records generated by a specific server.

By default this KPI_NODE_ID setting is not specified, and will use "LumenVox" as it's Node ID within the log files.

Whether using the default value or one that is specified in the configuration settings, this string will be used as the prefix for log files that are generated, and will also be included within the log files, in the NodeID field (see below). By using this NodeID, it allows KPI data from multiple LumenVox machines to be pooled on a central machine without confusing which machine the KPI records belong to.

KPI_LOG_MAX_AGE

The KPI_LOG_MAX_AGE setting is used by the manager service's housekeeping routine to delete KPI files older than the specified number of days.

This setting can be configured as a number of days between 0 and 90. A value of 0 will disable KPI file cleanup. For example, a value of 30 (the default) will clean up any KPI files that are older than 30 days, which can be helpful to prevent filling the disk with unwanted log files.

When enabled, any .csv (Comma Separated Variables) or .hdr (Header) files located beneath the KPI_ROOT_FOLDER will be deleted after their last modified date exceeds the specified number of days.

KPI_LONG_TIME_FORMAT

Within the KPI metrics that are recorded, the STARTTIME and ENDTIME time values describing the start and end of the KPI_INTERVAL period are logged.

The KPI_LONG_TIME_FORMAT setting allows users to specify a long format or a shorter numeric format, according to individual needs.

Users have the option of selecting from the following two options for this setting:

• 0 = short format (e.g. 201608211322)
• 1 = long format  (e.g. 08/21/2016 13:22:18)

The default setting for this is the long format, which is consistent with other date/time strings used in other LumenVox logs, however selecting the 0 option will generate these timestamp values in a shorter numeric format, which may be easier to manipulate in some log parsing tool

KPI_HEADER_IN_CSV

When KPI logs are generated, these are created in sub-folders below the KPI_ROOT_FOLDER as described above. In order to assist in reading these logs, a header is generated either within the .CSV (Comma Separated Variable) KPI file, or in a separate .HDR (Header) file.

The default option (1) for the KPI_HEADER_IN_CSV setting is to have the header be saved in the first line of .CSV KPI log files. However the two selections are shown here:

• Disabled (0) = a separate .hdr file for the header will be produced.
• Enabled (1) = KPI header will be the first line of generated KPI .csv files.

Often, having the header at the first line within the .CSV file may make reading the values easier if the values are imported into a spreadsheet or database application.

The header contains a list of column headers that describe each field of the KPI log. These field values are described in the table below.

Note that all values relate to the current KPI interval only. At the end of each KPI interval, these values are all reset. This allows KPI values to be tracked and associated with their specific KPI interval, however long that might be.

If the separate header file option is selected, there will be one header file per KPI root folder (as described below) and it will have the .hdr file extension.

KPI Data File Locations

As mentioned above, when enabled, KPI log files are stored in sub-folders below the KPI_ROOT_FOLDER (or LVLOGS if none specified) according to the current date and time. By way of example, if KPI logging is enabled, and the end of a KPI interval happened at 18:20:17 on August 25th 2016, the generated .csv (and optionally the corresponding .hdr) file(s) would be located below the KPI_ROOT_FOLDER, in the "18" sub-folder (associated with the current hour) as shown here:

The KPI file generated for this interval would be named LumenVox_08-25-2016_18-20-17.csv. If the separate header files option was selected, a matching header file would be created named LumenVox_08-25-2016_18-20-17.hdr

Note that if a different NodeID was specified, the prefix of both filenames would be whatever the NodeID is, instead of LumenVox.

Sample Data Files

Below you will find links to download sample KPI log files. These contain some values corresponding to ASR, TTS and MRCP session use within a given KPI interval.