The HIS log is structured as a flat line based file. Each event starts on a new line and can span multiple lines based on the event type and content. Here’s an example event:

An event has two major sections separated by <space> - <space>. The preamble section contains meta-data about the event including timestamp and level. The content section contains the actual event information. Let’s break down the example event into its sections.

Preamble Section

The preamble section can be further divided into 4 data points: timestamp, level, source, and context.

Timestamp

Each event starts with a timestamp that records the time the event occurred at millisecond granularity. The timestamp format can be written as yyyy-MM-dd_hh:mm:ss.SSS Z in regex notation. This format is used to allow canonical comparison and sorting with values remaining in chronological order when in ascending order. The hour portion is written using the 24 hour clock (military time). The timezone of the event is the last portion and uses the standard 3 letter designation.

Level

Events can be one of 4 severities:

• ERROR

• WARN

• INFO

• DEBUG

The level always occupies 5 characters in the event with WARN and INFO being left aligned and having an extra <space> as padding. When setting log level, you chose the level to write which always includes the levels above that level. For instance setting the log level to INFO includes WARN and ERROR. Setting the level to ERROR will only generate ERROR level messages.

Source

The event source represents the internal component or object type that generated the event. The example event was generated by a PureCloudConversation object. This field does not contain <space>s to assist in parsing the event.

Context

The context field provides further details about the event source. Ownership information is provided in “dot” notation with each item owning the items that come after a '.'. The example event context provides the entire object hierarchy for the conversation:

• PureCloud-rajat1 - The agent session id

• 88102 - The channel group id

• 88102 - The channel id

• OM145908759400000001 - The interaction id

• c3fbc3cd-20c3-408a-b035-1a7d05322d91 - The conversation id

The context field helps filter the log contents. For example you could see all the logs related to a particular agent session by searching for ‘PureCloud-rajat1’ since all logs, even those for child objects, will have a context field that starts with that value.

Content Section

The content section is a free-form area that contains details about the event. Although there is no standard structure to the content section, there are similarities between related events. The remainder of this document will have examples of important and common events.

Examples

System Startup

When HIS starts up, it lists the types of telephony platforms the build supports. In the example, this is covered by the first 8 lines. Next it initializes the processor management component (line 9) and retrieves its configuration from Config Server (line 10). If you see these events, it means that HIS was restarted. Depending on the configuration provided by Config Server you will see one or more events:

The json included in the event describes the processor configuration including its type "interactionProcessorType":"com.openmethods.ep.config.model.interactionprocessor.avaya", in this case Avaya. For each of these configurations, HIS will create a new processor component and initialize it. The initialization process can have minor differences depending on the platform type but they all follow a similar pattern.

All processors regardless of type will start with a Starting plugin… event (line 2). Lines 3 & 4 are specific to the Avaya platform and indicate that the plugin is attempting to connect to AES. Line 5 is an example of the Avaya third-party library log events. For the most part these events can be ignored unless a very detailed review is needed to identify a product issue.

Once a processor has successfully completed its initialization the above event will be generated. In the case of failure, a Plugin failed to start event is generated instead with further events that indicate the reason for failure.

Work Engine

HIS at its core is the middle-man between the agent’s media bar and the telephony platform. Requests and events can come from either side at any time. To ensure things are processed in the right order, HIS has a built in work engine component. New events or requests are added to a pair of work queues dedicated to the agent’s session; one for the media bar end and one for the telephony platform side. These queues produce debug log events as they process tasks:

The first three lines are the work engine inspecting the media bar queue for tasks (line 1), dispatching the task to a worker thread (line 2), and then returning back to the thread pool. The remaining log entries are produced by the worker thread as it processes the task. Line 5 has important information related to task timing. The Age: value is the number of milliseconds the task has been waiting in queue. In the example, the task was picked up as soon as it was queued resulting in the 0 value. Lines 6 & 8 are log events generated by the task while being executed. Line 6 is also an example of a multiline event with Line 7 being the continuation of the event that starts on Line 6. Line 9 again provides additional timing information about how many milliseconds it took to complete the task. The last 3 lines are the worker thread cleaning up after the task and returning to the thread pool.

Agent Login

An agent login is probably the most complicated process handled by HIS and generates a large set of events.

When an agent logs into the media bar, the media bar first contacts all available HIS servers to get information about their current status and load. The status property indicates the general state of the processor. The acceptingClients property determines if the processor is currently accepting new clients. The clientCount property is the total number of clients that have bound to the service. The media bar uses this information to select the HIS that is accepting clients and has the lowest load (connected clients).

Once an HIS instance is selected, the media bar binds to the processor and workflow components. Binding to a component allows a client to access that component’s API and receive events produced by it.

The media bar retrieves information from the processor component about its capabilities (lines 1-13). It then initiates a new agent session with the processor using the “prepareSession” command (line 14). The processor starts the process of logging the agent into the telephony platform.

As the session is created, a new processor session resource and workflow session resource are created and need to be bound to just like the processor and workflow services.

Workflow Events

As the session or interaction state changes, the workflow component keeps track using several state machines. An event is raised by the processor session and sent to the workflow engine (line 1). The workflow engine looks to see if there is a transition for the event and if there is changes the state machine (line 3). The state changes are listed in lines 3 & 4. When the state changes, the set of buttons or capabilities that are enabled and disable are updated and set to the client (lines 6-8).

Errors

Errors are almost always multi-line events. The first line contains information about the error and what was trying to be done when the error occurred. The remaining lines are a Java stack trace that provides technical details about the error and should be included in any bug report.