Session Log Annotation Markup Language (SLAML)

DRAFT 20 August 2007

Editor:

Andrew Wahbe, Genesys

About the VoiceXML Forum:

Founded in 1999, the VoiceXML Forum is an industry organization whose mission is to promote and to accelerate the worldwide adoption of VoiceXML-based applications. To this end, the Forum serves as an educational and technical resource, a certification authority and a contributor and liaison to international standards bodies, such as the World Wide Web Consortium (W3C) IETF, ANSI and ISO. The VoiceXML Forum is organized as a program of the IEEE Industry Standards and Technology Organization (IEEE-ISTO). Membership in the Forum is open to any interested company. For more information, please visit the Website at www.voicexml.org.

Disclaimers:

This document is subject to change without notice and may be updated, replaced or made obsolete by other documents at any time. The VoiceXML Forum disclaims any and all warranties, whether express or implied, including (without limitation) any implied warranties of merchantability or fitness for a particular purpose.

The descriptions contained herein do not imply the granting of licenses to make, use, sell, license or otherwise transfer any technology required to implement systems or components conforming to this specification. The VoiceXML Forum, and its member companies, makes no representation on technology described in this specification regarding existing or future patent rights, copyrights, trademarks, trade secrets or other proprietary rights.

By submitting information to the VoiceXML Forum, and its member companies, including but not limited to technical information, you agree that the submitted information does not contain any confidential or proprietary information, and that the VoiceXML Forum may use the submitted information without any restrictions or limitations.

Table of Contents

Introduction
General Model
SLAML Documents
Structural Elements
Log Records
1. Log Record Structure
2. Parallel and Sequential Execution
Annotative Attributes
Conformance
Appendix A: SLAML Schema
Appendix B: SLAML MIME Type
Appendix C: Basic HTTP Interface for SLAML Document Retrieval
Appendix D: Session Log Construction Algorithm
Appendix E: Changes
Appendix F: Acknowledgments
Appendix G: References

Introduction

This document presents a format for annotating XML-based data logs so that information from multiple, concurrent processes can be aggregated and correlated. Logs are represented using XML formats and namespaces associated with the type of server that generated the log. For example, an application server may use one set of tags to log information, and a database server might use another. The Session Log Annotation Markup Language (SLAML) provides a common framework that can be used by these logging formats including attributes for identifying a log's source entity (i.e. the server that produced it) and timestamping logs. It also provides structural rules that all logging formats can follow so that data can be organized in a consistent fashion.

Tracing through logs generated by the interactions of distributed processes is often problematic since it is difficult to identify the logs on one machine that correspond to a request placed by another machine. This problem is often due to the fact that clock synchronization is either missing or not accurate to the level required to make an association between logs. Under load, this task becomes impossible without some sort of mechanism to identify the logs associated with a specific request. SLAML, therefore, provides a common framework for correlating the sending and receipt of messages between processes or entities in a distributed system. It also provides mechanisms for dealing with parallelism within a single entity.

A SLAML document may contain logging information from a single process or server; however, SLAML allows information from multiple sources to be aggregated into a single document. Typically, an aggregate document would contain all of the information associated with a single, system-wide session. A document could, however, contain information related to multiple sessions. Each SLAML document includes a manifest of the sessions described by the document and can capture the association between logs and a session.

General Model

Entities

SLAML can be used to organize and annotate the logs produced by a system of one or more entities. An entity is a thread of control in the system that performs some processing and records logging information about that processing. These entities may be operating system processes, or individual threads within the same physical process. An entity could also be a subsystem involving multiple processes. What is important in such a case is that a composite entity produces a single set of logs and that all timestamps in those logs are based on the same clock.

Logs

Entities record information about the processing they perform and group the information into logs. Each log contains information from a single entity; however, a single entity can store information in multiple logs. Each log is uniquely identified by a tag. Typically, information in a log is semantically related in some way. For example, a log may contain information associated with a specific session.

Log Records and Log Record Formats

The XML contents of a log are referred to as log records. Log records are represented with elements outside of the SLAML namespace. It is expected that each type of entity that produces SLAML logs will define an XML log record format and namespace for its log records. SLAML defines attributes that are used to annotate logs in a consistent way across log record formats. A log record format is typically defined using a schema, DTD or other mechanism. SLAML itself is agnostic to the specific mechanism used.

Messages, and Interactions

Entities are able to interact with each other using some form of communication or stimulus. We will use the term message to refer to this stimulus. In addition to communicating with each other, entities can send and receive messages from sources that are external to the system. Individual messages are components of higher level interactions that fit within the constraints defined by some protocol. For example, many protocols organize messages into request-response pairs wherein the request message solicits the recipient to send another response message back to the request sender. These request-response pairs are modeled as interactions by SLAML. In the event that a message stands alone and has no such related messages, it is considered to be an interaction consisting of just one message.

SLAML provides mechanisms to annotate an entity's logs to indicate when a message is sent or received. Identifiers are assigned to specific messages so that logs representing the sending and receipt of a message can be associated. These identifiers are called message identifiers. Similarly, the interactions that comprise sets of messages are also given unique identifiers called interaction identifiers. This allows the messages to be grouped by their associated interaction and correlates the logs associated with one entity's execution of an interaction with the corresponding logs from another entity. If an entity chooses to log information at a level of detail that omits the individual messages that compose an interaction, the interactions and their identifiers can still be used to correlate the logs of the participants.

The recording of interactions implicitly creates an association between logs in the system. We say that two log records A and B are associated if participation in an interaction was recorded in log record A and participation in that same interaction was recorded in log record B. This association is also symmetric and transitive.

Classes

Entities are grouped into sets called classes. Every entity in a class accepts the same set of messages. SLAML does not depend on any formal definition of these messages. It only requires that entities be grouped in this way. Whenever an entity sends a message or request to another, the the associated logging information annotated with the class of the recipient. This is useful information as it provides insight into the role of the message recipient. For example, a request could be associated with the "Web Server" class. More important, however, is the fact that SLAML assumes that in any system, a mechanism for retrieving logs is defined for each class of entity. Thus, associating a message with a class describes how to acquire the logs associated with the handling of that message.

Issue: How do we prevent class collision? Should classes be represented by URIs?

Sessions

SLAML can be used to annotate the logs of a system that organizes its processing based on sessions. Informally, a session is some subset of processing that is related in some way, for example, a session may reflect the processing associated with a specific user. A system may at anytime be executing one or more sessions. In SLAML, a session is formally defined by the stimulus, or more specifically, the message or request that initiated some set of processing. We call this message or request the session start.

The session start creates an association between a session and logs produced by a system. We say that a log record A is associated with a session if A received the session start for S or if A is associated with the log record that received the session start for S. We say that a log is associated with session S if that log record contains a log that is associated with S.

The Session Manifest

Every SLAML document contains a session manifest listing of all of the sessions that are started in logs contained in the document. Each session listing provides a name for the session may contain a description of the session that is recorded using an XML schema and namespace associated with the entity that received the session start. The session listing also contains the interaction identifier of the session start message (or request), the class of the entity that received the session start, and the tag of the log that captures the receipt of the session start. The address of the session start message may be optionally recorded. The format and meaning of the address depends on the class; for IP-based protocols it would most likely be a string in the <host>:<port> format, for example "example.com:1234".

Log Aggregation

SLAML is designed to allow entities to individually produce logs that describe their processing. This, however, requires some additional processing to to fetch and aggregate all of the logs associated with a system-wide session. It is assumed that for each entity class, there will be some well known mechanism (e.g. an http-based interface, a web service, or some other interface) for retrieving logs produced by the entities in that class. It is also assumed that there is a well known mechanism for retrieving the session manifest listing for a session based on some domain-specific query parameters. For example, the query could be based on some session id, customer id, or for telephony-based systems, the caller's phone number.
SLAML provides mechanisms for annotating log records so that all of the logs that are associated with a session can be aggregated into a single SLAML document. The sending of a message (or request) is always annotated with the class of the recipient entity. SLAML also requires that the tag of the log that captures the receipt of the message is recorded along with the class, and allows the address of the message or request to be optionally recorded. As stated above, this information is also recorded for the session start message of each session in the session manifest.

SLAML requires that the class, tag, and the optional address recorded for a sent message (or request) are sufficient information to fetch the log associated with the receipt of the message. The tag and address (if known) are used as parameters to the log fetching mechanism defined by the class. Using this mechanism, beginning with the session start, all of the logs associated with a session can be retrieved. These logs can then be combined in a single SLAML document.

Supplemental Log Annotations

SLAML allows a log processor to annotate a log with additional information. This allows comments on a log to be recorded by the by a human being who is assessing the information it contains. For example, in a support engineer can use this mechanism to indicate where a problem occurred and to provide other supplemental information. Automated processes could also add these annotations, if some log processing yeilds information that should be added to a SLAML document. As with the logs themselves, these annotations can be in any XML format. SLAML only provides a container for the annotations and a way to indicate the point in the logs to which an annotation applies.

SLAML Documents

SLAML documents are mixed namespace documents as SLAML does not define the specific XML elements for the log records used to capture processing information. SLAML provides structural elements that are used to organize these log records as well as annotative attributes that are used to provide annotation to the elements that compose a log record.

The SLAML Namespace

All elements and attributes defined by SLAML are part of the SLAML namespace. This namespace is defined as: http://voicexml.org/2006/slaml. By convention, this document uses the namespace prefix "sl:" for the SLAML namespace. Note that this choice of namespace prefix is arbitrary and is not semantically significant.

SLAML Namespace Prefixes

A SLAML attribute is prefixed with the SLAML namespace identifier if the attribute can be used as an in-line annotation on elements in another namespace. The SLAML annotative attributes in are in this category. By convention, a SLAML attribute is not prefixed if the attribute only appears on a SLAML element. All SLAML elements are prefixed.

SLAML Structural Elements

The following elements are defined by SLAML:

SLAML Root Element: This is the root <sl:slaml> element of every SLAML document; it simply acts as a container for log information generated by one or more entities in a system. It can also contain supplemental log annotations generated by human beings or automated log processors.
Log Element: The <sl:log> element contains log information from a single entity. All logs are direct children of the SLAML root element and have a unique tag that is used to reference the log in the SLAML manifest and other logs. The XML elements contained by a log are called log records and represent processing done by the entity. The processing captured by these log records are logically grouped in some way. For example, all of the processing captured by a <sl:log> element could be related to a single user or session.
Manifest Element: The <sl:manifest> element contains a listing of session elements. The manifest is a direct child of the SLAML root element.
Session Element: The <sl:session> element contains information about a specific session. The session element identifies the message or request that initiated the session and provides a start point for log aggregation.
Annotation Element: The <sl:annotation> annotation element contains annotative information related to some log record.

SLAML Annotative Attributes

The following types of annotative attributes are defined by SLAML:

Timing and Ordering Attributes: These attributes are used to timestamp log information and indicate the relative ordering of events. Elements that represent an atomic event use the sl:time attribute to indicate their timestamp. Elements that represent a period of processing use the sl:start and sl:end to indicate the time at which the processing started and ended. The sl:mode attribute is used to indicate if the execution represented by the elements within a period occurred sequentially, in document order.
Interaction Attributes: These attributes are used to indicate the points in execution where entities participate in interactions. The values of these attributes are interaction identifiers that uniquely identify the interaction. The sl:interaction, and sl:handle-interaction, used to represent that an element documents the participation of an entity in an interaction. The sl:interaction attribute is used by the entity that initiated the interaction; other participants in the interaction use the sl:handle-interaction attribute.
Messaging Attributes: The sl:send-msg and sl:recv-msg attributes are used to represent the sending and receiving of a message. The values of these attributes are message identifiers that uniquely identify a message.
Classification Attributes: The sl:class attribute is used to classify the logs by the type of entity that produced them. It is also used to classify messages and requests by the type of recipient entity.
Addressing Attributes: The sl:target attribute is used to indicate the target address of a message or request that was sent. The sl:source attribute is used to indicate the source address of a message or request that was received.
Log Correlation Attributes: The sl:log-tag attribute is used annotate a message or request with the tag of the log that captures the receipt and handling of that message or request.
Log Identification Attributes: The sl:trace-id attribute is used as an identifier for a specific log record element. This allows it to be referenced by supplemental log annotations contained in an annotation element.

Log Record Element Types

Log records are composed of elements from outside of the SLAML namespace; however, these elements possess SLAML annotative attributes. The attributes categorize an element as a certain type such as a period or event. Every log record element must abide by the specific rules associated with its type. Note, however, that elements can belong to multiple types. For example, all interaction elements are also period or event elements. This typing allows generic processors to correlate, aggregate and navigate the SLAML documents produced by a system without having knowledge of the specific data formats used by the constituent entities.

Period: A period element represents some period of processing that is performed by an entity. Any element that has the SLAML sl:start and sl:end attributes identify it as a period. These attributes are timestamps of when the period started and ended.
Event: An event element represents an atomic operation performed by an entity. An event element is any element that has a SLAML sl:time attribute; this is the timestamp of when the operation was performed.
Message Send: A message send element represents the sending of a message. An event or period element that has a SLAML sl:send-msg attribute is a message send. This attribute contains the message identifier for the associated message. A message is always associated with a specific interaction or interaction handler. This is the
Message Receipt: A message receipt element represents the receipt of a message. An event or period element that has a SLAML sl:recv-msg attribute is a message receipt. This attribute contains the interaction identifier for the associated message. These elements may also possess a sl:source attribute containing the address of the sender.
Interaction: An interaction element represents the initiation of, and time spent executing an interaction. A period element that has a SLAML sl:interaction attribute is an interaction. An interaction may also be an event; however, this is usually reserved for the case when an interaction consists of a single message. The sl:interaction attribute contains the interaction identifier for the interaction. An interaction element is only logged by the entity that initiated the interaction; other participants in an interaction must log an interaction handler element. Interaction elements must have a sl:log-tag attribute and a sl:class attribute. A sl:target attribute containing the address of the recipient may optionally be present as well. The sl:class, sl:log-tag, and sl:target attributes can be used together to fetch the logs produced by other entities that describe the handling of the interaction. The sending of a request (together with the receipt of the response) can also be represented using a request handler element.
Interaction Handler: An interaction handler element represents the participation in an interaction by an entity. A period element that has a SLAML sl:handle-interactionattribute is an interaction handler. An interaction handler may also be an event; however, this is usually reserved for the case when an interaction consists of single message. An interaction handler is only logged by an entity if it did not initiate the interaction; an interaction element is logged by the initiator. The sl:handle-interaction attribute contains the interaction identifier for the associated request. Interaction handler elements may also possess a sl:source attribute containing the address of the initiating party.
Data: Data elements possess no SLAML annotative attributes. These elements are used to characterize or provide information related to their parent element.

Structural Elements

The Root Element: `sl:slaml`

Element	`sl:slaml`
Description	This element is the root element of a SLAML document. It can contain log records from one or more entities as well as a manifest of sessions. The `sl:slaml` element should declare the SLAML namespace that it, and all other elements and attributes defined by this specification, belong to.
Attributes	Required: `version`: the version of the Session Log Annotation Language used by the document. Documents using this specification must specify a value of "1.0".
Children	The `sl:slaml` element may contain at most one `sl:manifest` element and may contain multiple `sl:log` and `sl:annotation` elements. A `sl:slaml` element must contain at least one child `sl:log` or `sl:manifest` element.
Parent	None

For example,

<sl:slaml xmlns:sl="http://voicexml.org/2006/slaml" version="1.0">
 ...
</sl:slaml>

The Log Element: `sl:log`

Element	`sl:log`
Description	Contains logging information produced by an entity.
Attributes	Required: `entity`: a unique identifier for the entity that produced this log. `tag`: a label used to identify this log. `sl:class`: contains the class identifier of the entity that produced this log.
Children	The sl:log element contains log records. These elements are from another namespace and contain logging information.
Parent	The `sl:log` element can only appear as a child of the `sl:slaml` element.

The log element groups a set of log records that were produced by an entity in the system. A SLAML document contains one or more log elements that describe system processing. A document may contain multiple log elements produced by the same system entity.

Each log record must have an entity-class attribute to identify the class or type of entity that produced the log. Each log record has an entity-id attribute that contains the unique identifier of entity that produced the log record. These attributes are purely informational -- they not needed to identify or reference the log record. These attributes are optional.

The Manifest Element: `sl:manifest`

Element	`sl:manifest`
Description	Contains a list of sessions.
Attributes	None
Children	The `sl:manifest` element contains `sl:session` elements.
Parent	The `sl:manifest` element can only appear as a child of the root `sl:slaml` element.

If a SLAML document contains a log that has a message receipt or handler or a request receipt or handler that initiated a session (i.e. a session start message or request), then the manifest must contain a session element for that session. The manifest may contain a session element even though the log containing the session start message or request is not in the document. A document containing only a manifest of sessions may represent the result of a query for sessions matching some specific criteria. Such a document could be provided to a log aggregator produce a document containing all of the logs associated with the matching sessions.

The Session Element: `sl:session`

Element	`sl:session`
Description	This element describes a session. A session is defined by a message or request received by an entity that initiated some processing.
Attributes	Required: `name`: a label for the session. No two sessions with the same `sl:class` have the same `name`. `origin`: the interaction identifier of the message or request that marks the origin of a session. This is the stimulus that initiated the session. No two sessions with the same `sl:class` have the same `origin`. `sl:class`: the class of the entity that received the session start message or request. `sl:log-tag`: this contains the tag of the log containing Optional: `sl:target`: the address of the session start message or request.
Children	The `sl:session` element may contain markup that describes the session. These elements are not from the SLAML namespace.
Parent	The `sl:session` element can only appear as a child of the `sl:manifest` element.

Issue: Are all messages between entities(even those that didn't initiate sessions) contained in the manifest somehow?

The Annotation Element: `sl:annotation`

Element	`sl:annotation`
Description	This element contains XML annotations for a specific point in the logging.
Attributes	Required: `trace-ref`: this attribute's value must be identical to the value of the `sl:trace-id` attribute of some log record element in the document. This is the log record element to which the annotation pertains.
Children	The `sl:annotation` element must contain markup that annotates the log record element referenced by the `trace-ref` attribute. These elements are not from the SLAML namespace.
Parent	The `sl:annotation` element can only appear as a child of the `sl:slaml` element.

For example:

<sl:slaml xmlns:sl="http://voicexml.org/2006/slaml" version="1.0">
 <sl:log tag="log-tag-1" 
 sl:class="AppServer" 
 entity="Server-1" 
 xmlns="http://example.com/AppServer/log-format">
 <my-record sl:start="12345" sl:end="12370">
 <event1 sl:time="12349"/>
 <event2 sl:time="12352"/>
 <event3 sl:time="12358" sl:trace-id="unique-trace-id"/>
 <event4 sl:time="12362"/>
 </my-record>
 </sl:log>

 <sl:annotation sl:trace-ref="unique-trace-id"
 xmlns="http://example.com/annotation-format">
 <debug-comment>This is where the problem occured</debug-comment>
 </sl:annotation>
</sl:slaml>

Log Records

A log record describes some processing done by a system entity. Each log record is represented as an XML sub-tree with a single root element. This processing is typically associated with a specific transaction or request handled by the entity. Log records are composed of elements and attributes from namespaces other than the SLAML namespace. The XML log record format used to represent an entity's processing is typically unique to the class of entity that performed the processing. There is no strict requirement, however, that there be a one to one mapping between entity classes and log record namespaces.

Log Record Structure

There are three main types of elements in a log record: events, periods, and data elements. Event elements represent an atomic event that occurred at a specific point in time during the processing performed by a system entity. The receipt of a system message is an example of an event. A decision that is reached during processing is often logged as an event, though the processing required to reach the decision lasted for a period of time rather than being atomic. Event elements are annotated with a SLAML sl:time attribute that indicates their timestamp.

Many of the events processed by an entity represent transitions between states or periods of execution. For example, the completion of a task such as the initialization of a resource may be a period of execution. An entity may log events or execute other "sub-tasks" over the duration of a period. These events and sub-tasks may represent steps in the task completed during the period. It is natural fit for log records to take advantage of the hierarchical nature of XML to represent this break down of processing into tasks, sub-tasks, and events as nested elements. Thus, an element that represents a period of execution often contains sub-elements that represent other sub-periods and events. These sub-periods and events represent the processing associated with the period of execution. A period element is annotated with a SLAML sl:start and a sl:end attribute that indicates the timestamps of start and end of the period.

Finally, XML elements that do not represent events or periods simply represent structured data associated with the event or period within which they are nested. Data elements have no SLAML timing annotations.

Period, event and data elements must observe the following nesting rules:

A period element may contain other period elements, event elements and data elements.
Event elements and data elements may only contain data elements.

This ensures that events have no child events or periods, and thus remain "atomic", and that data elements remain nested within the event or period to which they pertain.

Parallel and Sequential Execution

Typically, the events and sub-periods that occur within a period are executed sequentially; the elements appear in the order executed and their periods of execution do not overlap. However, an entity may at times do "many things at once," and it would therefore be convenient to represent execution as two distinct periods that occur at the same time. This does not necessarily imply that the entity contains multiple threads of control; this is simply a mechanism to semantically organize events and data when the operations performed by an entity can be thought of as two concurrent tasks.

For example, consider the events executed during a single period in the following example.

<period sl:start="12345" sl:end="12360">
 <start_a sl:time="12345"/>
 <start_b sl:time="12346"/>
 <event_related_to_a sl:time="12349"/>
 <event_related_to_b sl:time="12350"/>
 <event_related_to_a sl:time="12350"/>
 <stop_a sl:time="12355"/>
 <stop_b sl:time="12359"/>
</period>

The events within a sequential period appear in the order they were executed. Two of the events have the same timestamp; however, the order in which they were executed is explicit because of their document order. Unfortunately, this representation does not explicitly capture the relationship between the events and their associated tasks. This can only be inferred from the names of the events.

This execution can instead be represented so that there is an element that represents each task, and events are nested within their associated task element. This is done in the following example.

<period sl:start="12345" sl:end="12360" sl:mode="parallel">
 <task_a sl:start="12345" sl:end="12355">
 <event_related_to_a sl:time="12349"/>
 <event_related_to_a sl:time="12350"/>
 </task_a>
 <task_b sl:start="12346" sl:end="12359">
 <event_related_to_b sl:time="12350"/>
 </task_b>
</period>

Here, the timestamps of the two task elements overlap and are therefore concurrent. This is done at the expense of the total ordering of the events in the parent period -- the execution order of the two events with the same timestamp is now lost. This trade-off is something that must be kept in mind when designing an entity's logging format.

A SLAML log element may contain multiple log records (i.e. it may have multiple direct children). The document order of the log records within a log element has no implications on the order of execution. The log records are treated as if they were contained within a parallel period.

Annotative Attributes

Timing and Ordering Attributes: `sl:time`, `sl:start`, `sl:end`, and `sl:mode`

Attribute	`sl:time`
Description	Attribute indicating the absolute time at which an event occurred. The value is expressed as an integer counting number of milliseconds since January 1, 1970 00:00:00.000 GMT.
Applies To	An element is an event element if and only if it has an `sl:time` attribute.

Attribute	`sl:start`, `sl:end`
Description	Attributes indicating the absolute start and end time of a period. The values are expressed as integers counting number of milliseconds since January 1, 1970 00:00:00.000 GMT.
Applies To	An element is a period element if and only if it both a `sl:start` attribute and a `sl:end` attribute.

Attribute	`sl:mode`
Description	Attribute indicating if the elements within a period are executed sequentially or in parallel. There are only two valid values for this attribute: "sequential" and "parallel". The default value is "sequential" -- periods without this attribute are assumed to be sequential.
Applies To	Only period elements may possess this attribute.

The sl:time attribute is used to indicate the time at which events occurred. The sl:start and sl:end attributes are used to indicate the time bounds of periods of execution. All timestamps are represented as integers counting the number of milliseconds since midnight, January 1, 1970 GMT. Note that clock synchronization between system entities is not assumed. The timestamps of logs produced by two distinct entities has no implications on the order of execution of the associated events.

Events may not have sl:start, sl:end, or sl:mode attributes. Periods may not have a sl:time attribute. Data elements contain no timing or ordering attributes.. An period may have a sl:start attribute and an sl:end attribute with the same value; however, the sl:end value may never be less than the sl:start value.

Event elements and period elements must have timestamps that fall within the bounds of their parent period (if one exists). More formally, a period element may not have a child element with sl:time, sl:start or sl:end attribute values that are greater than its own sl:end attribute value or less than its own sl:start attribute value.

The sl:time and sl:start values of the direct children of a period must be monotonically increasing. Specifically, the value of the sl:time attribute of an event in a period must be less than or equal to the sl:time or sl:start attributes of all sibling elements that appear after it in document order. This must also hold for the value of the sl:start attribute of a period that falls within another period.

While parallel periods make no assertions about the relative ordering of their children, the order of execution of the direct children of a sequential period is their document order. Thus, sequential periods have the additional restriction that the timestamps of their direct children do not overlap. Specifically, if a period is a direct child of a sequential period, its sl:end attribute must be less than or equal to the sl:time or sl:start attribute of all sibling elements that appear after it in document order.

The following example demonstrates how the start and end attributes are used.

<some-event-element sl:time="1234567890"/>
<a-period-element sl:start="1234567891" sl:end="1234567895"/>
<my-data-element>This is a data element</my-data-element>

Interaction Attributes

Classification Attributes: `sl:class`

Attribute	`sl:class`
Description	Attribute identifying a type of entity. This could be used to indicate the type of entity that produced a log or the type of entity to which a message or request is addressed.
Applies To	All `sl:log` and `sl:session` elements must have a `sl:class` attribute. Log record elements that represent the sending of a message or request, specifically, any element that has a `sl:send-message`, `sl:send-request`, or `sl:request` attribute, must also have an `sl:class` attribute.

Elements that represent requests or messages to another entity must possess a sl:class attribute. This identifies the type of entity to which the request or message was addressed. For example, a query to a database might have a class of "SQL Database". Log elements also have an sl:class attribute to identify the type of entity that produced the log.

It is assumed that some well known mechanism exists for fetching the logs associated with that class. Thus, the class specified for a request or message identifies a resource that can be used to acquire the logs that represent the processing and handling of that request or message. The target, if specified, is typically part of that interaction, say as a parameter to the log query.

Addressing Attributes: `sl:target` and `sl:source`

Attribute	`sl:target`
Description	Attribute identifying the address of the entity to which a message or request was addressed. The format of the address depends on the class of the recipient entity. This attribute is always optional.
Applies To	A `sl:session` elements may have a `sl:target` attribute. Log record elements that represent the sending of a message or request, specifically, any element that has a `sl:send-msg`, `sl:send-request`, or `sl:request` attribute, may also have an `sl:target` attribute.

The sl:target attribute identifies the address to which a request or message was targeted. The address does not necessarily correspond to the name of a system entity. If some sort of load balancing scheme was used, the address could be virtual and would not identify a specific server or entity. The sl:target is also optional as some types of interactions may not require an explicit address.

As stated above, the sl:class attribute identifies a resource from which logs for a message or request can be fetched. If present, the sl:target attribute is passed with the sl:log-tag as a parameter in a query for a log.

Attribute	`sl:source`
Description	Attribute identifying the address of the entity that sent a message or request was addressed. The format of the address depends on the class of the sender entity. This attribute is always optional.
Applies To	Log record elements that represent the receipt of a message or request, specifically, any element that has a `sl:recv-msg`, `sl:recv-request`, `sl:handle-msg` or `sl:handle-request` attribute, may also have an `sl:source` attribute.

The sl:source attribute identifies the address of the entity that sent a request or message. The address does not necessarily correspond to the name of a system entity. The sl:source is also optional as in some types of interactions the address of the sender may not be known.

Log Correlation Attributes: `sl:log-tag`

Attribute	`sl:log-tag`
Description	Attribute identifying the tag value of the log that records the receipt a message or request. The format of the tag depends on the class of the recipient entity.
Applies To	A `sl:session` elements must have a `sl:log-tag` attribute. Log record elements that represent the sending of a message or request, specifically, any element that has a `sl:send-message`, `sl:send-request`, or `sl:request` attribute, must also have a `sl:log-tag` attribute.

Elements that represent requests or messages must posses a sl:log-tag attribute that, along with the sl:class and sl:target attributes, identifies the specific log that contains the log record(s) representing the receipt and handling of that request or message. As stated above, the sl:class attribute identifies a resource from which logs can be fetched. The sl:log-tag (along with the sl:target, if present) is passed as a parameter in a query for a log.

The sl:log-tag value is not unique to a request or message -- multiple request and/or message sends with the same sl:class can share the same sl:log-tag value. In this case, the log records related to the handling of those requests or messages would be found within the same log. Request and/or message sends with different sl:class values can also share the same sl:log-tag value. However, in this case, the log records related to the handling of those requests or messages would be found in logs from distinct entities.

Interaction Identifier Attributes

Every interaction between two entities is assigned an identifier that is used by both parties to mark where the interaction takes place in their respective logs. This document does not define a format for the identifiers or a mechanism with which they can be generated. They are simply required to be unique across all interactions of the same class. Additionally, this document does not define the party that is responsible for assigning an identifier to an interaction. For example, in a request-response scenario, the identifier could be assigned by the client and passed to the server as part of the request; or the identifier could be assigned by the server and passed to the client as part of the response. Regardless of which party assigned the identifier, the class of an interaction is defined to be the class of the recipient entity.

The interaction identifier is specified as an attribute of any the element that represents process interaction. The attribute name depends on the party that initiated the interaction. For example, consider a two-way interaction where a client entity sends a request to a server entity and waits for a response. The interaction element logged by the client will have a sl:interaction attribute that contains the unique identifier for the interaction and the corresponding element logged by the server will have a sl:handle-interaction containing the same interaction identifier.

While it is perhaps uncommon for an entity to send messages or requests to itself, interactions that are initated and handled by the same entity are not forbidden. Processing done by multiple threads or subsystems within the same entity may be more conveniently represented using multiple log records linked by interactions than by a single log record.

Attribute	`sl:interaction`
Description	Attribute containing the identifier of an interaction between entities. An element with this attribute is logged by the entity that initiated an interaction and represents the time spent performing that interaction. These elements are referred to as interaction elements.
Applies To	An element with a `sl:interaction` attribute should typically be a period element (i.e. it also has `sl:start` and a `sl:end` attributes); however, an event element (i.e. it must also have a `sl:time` attribute) if the interaction can be represented by an atomic event (e.g. the sending of a message).

Attribute	`sl:handle-interaction`
Description	Attribute containing the identifier of an interaction between entities. An element with this attribute is logged by an entity that did not initiate the associated interaction and represents the time spent performing that interaction. These elements are referred to as interaction handler elements.
Applies To	An element with a `sl:interaction` attribute should typically be a period element (i.e. it also has `sl:start` and a `sl:end` attributes); however, an event element (i.e. it must also have a `sl:time` attribute) if the interaction can be represented by an atomic event (e.g. the sending of a message).

Message IdentifierAttributes

Message identifier attributes are used to identify the individual messages that compose an interaction. The entities involved in an interaction may log these messages in order to provide finer grained corrlation between the system events involved in an interaction.

Attribute	`sl:send-msg`
Description	Attribute containing the interaction identifier of a message. The event element with this attribute represents the sending of the message.
Applies To	An element with a `sl:send-msg` attribute must be an event (i.e. it must also have a `sl:time` attribute). These elements are referred to as message send elements.

Attribute	`sl:recv-msg`
Description	Attribute containing the interaction identifier of a message. The event element with this attribute represents the receipt of the message.
Applies To	An element with a `sl:recv-msg` attribute must be an event (i.e. it must also have a `sl:time` attribute). These elements are referred to as message receipt elements.

ISSUE: Do we need a way to represent multicast? i.e. a send with multiple receipts?

The following example contains two interactions between an "application server" (class = AppServer) and a "database server" (class = DBServer). The first interaction does not log the individual messages that compose it. Tthe request and response messages that make up the second interaction are logged.

<sl:slaml xmlns:sl="http://voicexml.org/2006/slaml" version="1.0">
 <sl:manifest>
 <sl:session name="A-Session" origin="the-start-id" 
 sl:class="AppServer" sl:log-tag="log-tag-1"/>
 </sl:manifest>

 <sl:log tag="log-tag-1" 
 sl:class="AppServer" 
 entity="Server-1" 
 xmlns="http://example.com/AppServer/log-format">
 <my-record sl:start="12345" sl:end="12370" sl:recv-msg="the-start-id">
 <an-interaction sl:interaction="unique-interaction-id" 
 sl:log-tag="log-tag-2" sl:class="DBServer"
 sl:start="12345" sl:end="12355">
 <event1 sl:time="12349"/>
 <event2 sl:time="12352"/>
 </an-interaction>
 <event3 sl:time="12358"/>
 <another-interaction sl:interaction="another-interaction-id" 
	sl:class="DBServer" sl:log-tag="log-tag2"
	sl:start="12360" sl:end="12365">
 <send-request sl:send-msg="a-msg-id" sl:time="12360"/>
 <event4 sl:time="12362"/>
 <recv-response sl:recv-msg="another-msg-id" sl:time="12364"/>
 </another-interaction>
 </my-record>
 </sl:log>

 <sl:log tag="log-tag-2"
 entity="DBServer2"
 sl:class="DBServer"
 xmlns="http://example.com/DBServer/log-format">
 <a-handler sl:interaction-handler="unique-interaction-id"
 sl:start="12346" sl:end="12353">
 <service-task sl:start="12347" sl:end="12352/>
 </a-request-handler>
 <another-handler sl:interaction-handler="another-interaction-id" 
 sl:start="12361" sl:end="12368">
 <recv-request sl:recv-msg="a-msg-id" sl:time="12362"/>
 <DB-event1 sl:time="12364"/>
 <DB-event2 sl:time="12365"/>
 <send-response sl:send-response="another-msg-id" sl:time="12367"/>
 </another-request-handler>
 </sl:log>
</sl:slaml>

Log Identification Attributes

The sl:trace-id attribute allows a log record element to be referenced by a supplemental annotation contained within a sl:annotation element. A log

Attribute	`sl:trace-id`
Description	Attribute containing the trace identifier of a log record. This identifier is unique within a SLAML document and is used to reference an element in supplemental annotations applied to the log.
Applies To	Any log record element can have a `sl:trace-id` attribute.

Conformance

Conforming SLAML Documents

A document is a Conforming SLAML Document if it meets both the following conditions:

It is a well-formed XML document [XML] conforming to Namespaces in XML [XMLNS].
It adheres to the specification described in this document (SLAML Specification) including the constraints expressed in the Schema (see Appendix A) and having an XML Prolog and root element as specified in Section TBD.

The SLAML specification and these conformance criteria provide no designated size limits on any aspect of SLAML documents. There are no maximum values on the number of elements, the amount of character data, or the number of characters in attribute values.

Conforming SLAML Producer

Need to define what a conforming SLAML Producer is.

Conforming SLAML Processor

Need to define what a conforming SLAML Processor is.

Appendix A: SLAML Schema

This section is normative.
This section defines the formal syntax for a SLAML document using two normative XML schemas.

The first schema is a base schema defining the formal syntax for the global SLAML annotative attributes. Any log record format that is to be contained by a SLAML document should use this schema as part of its own formal syntax definition. This schema can be found at URI TBD.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sl="http://voicexml.org/2006/slaml" 
           targetNamespace="http://voicexml.org/2006/slaml" elementFormDefault="qualified" 
           attributeFormDefault="qualified">
	<xs:simpleType name="modeType">
		<xs:restriction base="xs:string">
			<xs:enumeration value="sequential"/>
			<xs:enumeration value="parallel"/>
		</xs:restriction>
	</xs:simpleType>
	<xs:attributeGroup name="event">
		<xs:annotation>
			<xs:documentation>This is the set of attributes used by event elements.</xs:documentation>
		</xs:annotation>
		<xs:attribute ref="sl:time" use="required"/>
	</xs:attributeGroup>
	<xs:attributeGroup name="period-parallel">
		<xs:annotation>
			<xs:documentation>This should be used by parallel period elements.</xs:documentation>
		</xs:annotation>
		<xs:attribute ref="sl:start" use="required"/>
		<xs:attribute ref="sl:end" use="required"/>
		<xs:attribute ref="sl:mode" use="required" fixed="parallel"/>
	</xs:attributeGroup>
	<xs:attributeGroup name="period-sequential">
		<xs:annotation>
			<xs:documentation>This should be used by sequential period elements.</xs:documentation>
		</xs:annotation>
		<xs:attribute ref="sl:start" use="required"/>
		<xs:attribute ref="sl:end" use="required"/>
		<xs:attribute ref="sl:mode" use="optional" fixed="sequential"/>
	</xs:attributeGroup>
	<xs:attributeGroup name="interaction">
		<xs:annotation>
			<xs:documentation>This is the set of attributes used by interaction.</xs:documentation>
		</xs:annotation>
		<xs:attribute ref="sl:interaction" use="required"/>
		<xs:attribute ref="sl:log-tag" use="required"/>
		<xs:attribute ref="sl:class" use="required"/>
		<xs:attribute ref="sl:target" use="optional"/>
	</xs:attributeGroup>
	<xs:attributeGroup name="interaction-handler">
		<xs:annotation>
			<xs:documentation>This is the set of attributes used by an interaction handler.</xs:documentation>
		</xs:annotation>
		<xs:attribute ref="sl:handle-interaction" use="required"/>
		<xs:attribute ref="sl:source" use="optional"/>
	</xs:attributeGroup>
	<xs:attribute name="class" type="xs:string">
		<xs:annotation>
			<xs:documentation>This is the class of the entity that procuced a log.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="source" type="xs:string">
		<xs:annotation>
			<xs:documentation>This is the source address of an interaction or a message.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="target" type="xs:string">
		<xs:annotation>
			<xs:documentation>This is the target address of an interaction or a message.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="log-tag" type="xs:string">
		<xs:annotation>
			<xs:documentation>
				This is the tag that identifies a log produced by a system entity.
			</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="mode" type="sl:modeType" default="sequential">
		<xs:annotation>
			<xs:documentation>This is the mode of a period. It may be parallel or sequential.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="time" type="xs:positiveInteger">
		<xs:annotation>
			<xs:documentation>This represents the time an event took place.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="start" type="xs:positiveInteger">
		<xs:annotation>
			<xs:documentation>This represents the start time of a period of execution.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="end" type="xs:positiveInteger">
		<xs:annotation>
			<xs:documentation>This represents the end time of a period of execution.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="interaction" type="xs:string">
		<xs:annotation>
			<xs:documentation>
				This is the id of an interaction with another entity. The element with this 
				attribute represents the initiation of the interaction.
			</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="handle-interaction" type="xs:string">
		<xs:annotation>
			<xs:documentation>
				This is the id of an interaction with another entity. The element 
				with this attribute represents the handling of the interaction. The 
				other party initiated the interaction.
			</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="send-msg" type="xs:string">
		<xs:annotation>
			<xs:documentation>This is the id of a message sent.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="recv-msg" type="xs:string">
		<xs:annotation>
			<xs:documentation>This is the id of a message received.</xs:documentation>
		</xs:annotation>
	</xs:attribute>
	<xs:attribute name="trace-id">
		<xs:annotation>
			<xs:documentation>
				This is identifier is used to reference the element 
				that an annotation pertains to.
			</xs:documentation>
		</xs:annotation>
	</xs:attribute>
</xs:schema>

The second schema defines the formal syntax for the SLAML container document itself. This schema can be found at URI TBD.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sl="http://voicexml.org/2006/slaml" 
            targetNamespace="http://voicexml.org/2006/slaml" elementFormDefault="qualified" 
            attributeFormDefault="unqualified" version="1.0">
	<xs:include schemaLocation="slaml-base.xsd"/>
	<xs:element name="slaml">
		<xs:annotation>
			<xs:documentation>This is the root element of a SLAML document. </xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="sl:manifest" minOccurs="0"/>
				<xs:element ref="sl:log" minOccurs="0" maxOccurs="unbounded"/>
			</xs:sequence>
			<xs:attribute name="version" type="xs:string" use="required" fixed="1.0"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="manifest">
		<xs:annotation>
			<xs:documentation>
				This contains a list of sessions that are captured by the document.
			</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence>
				<xs:element ref="sl:session" minOccurs="0"/>
			</xs:sequence>
		</xs:complexType>
	</xs:element>
	<xs:element name="session">
		<xs:annotation>
			<xs:documentation>This represents a session that is captured by the document.</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:attribute name="name" type="xs:string" use="required"/>
			<xs:attribute name="origin" type="xs:string" use="required"/>
			<xs:attribute ref="sl:class" use="required"/>
			<xs:attribute ref="sl:log-tag" use="required"/>
			<xs:attribute ref="sl:target" use="optional"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="log">
		<xs:annotation>
			<xs:documentation>This contains a log produced by a system entity.</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:sequence>
				<xs:any namespace="##other" maxOccurs="unbounded"/>
			</xs:sequence>
			<xs:attribute ref="sl:class" use="required"/>
			<xs:attribute name="tag" type="xs:string" use="required"/>
			<xs:attribute name="entity" type="xs:string" use="optional"/>
		</xs:complexType>
	</xs:element>
	<xs:element name="annotation">
		<xs:annotation>
			<xs:documentation>
				This contains supplemental annotations produced by a log processor.
			</xs:documentation>
		</xs:annotation>
		<xs:complexType>
			<xs:attribute name="trace-ref" type="xs:string" use="required"/>
		</xs:complexType>
	</xs:element>
</xs:schema>

Appendix B: SLAML MIME Type

A MIME Type should be allocated for SLAML documents.

Appendix C: Basic HTTP Interface for SLAML Document Retrieval

This will describe a basic HTTP-based interface for retrieving SLAML logs based on a class and log-tag. Essentially every class and log-tag combination evaluates to a specific HTTP URI that can be used to fetch SLAML logs. The class maps to an HTTP URI prefix (i.e. a URI with no query string) and the log-tag is used as a query string parameter. For example, if the class "foo" maps to the URI prefix "http://example.com/fetchlogs", then "http://example.com/fetchlogs?log-tag=bar" would be used to fetch all logs with the log-tag "bar" for class "foo". A log aggregator would be configured with the mapping for a specific system.

Appendix D: Session Log Construction Algorithm

This will provide pseudo-code for the algorithm that takes a SLAML document with nothing but a manifest of sessions and yields a full system log by iteratively fetching the logs associated with the session.

Appendix E: Changes

Appendix F: Acknowledgments

Appendix G: References

XML: Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, and Eve Maler, Francois Yergeau, editors. Extensible Markup Language (XML) 1.0 (Third Edition). World Wide Web Consortium, 2004.
XMLNS: Andrew Layman, Richard Tobin, Tim Bray, Dave Hollander, editors, Namespaces in XML 1.1, World Wide Web Consortium, 2004.

Copyright © 2000 - 2007 VoiceXML Forum. All rights reserved.
The VoiceXML Forum is a program of the
IEEE Industry Standards and Technology Organization (IEEE-ISTO)
For inquiries contact voicexml-admin@voicexml.org