The SAS facility provides Resource Adaptor and service developers an interface for integrating with the Metaswitch Service Assurance Server, an end-to-end tracing system. SAS provides an integrated end-to-end view of calls passing through an operator’s network. It combines traces from all network elements with reporting capability into a complete trace of the call that can be examined at multiple levels of detail to determine how the call was processed.

The principal interface for reporting data to SAS is the Trail. Trails are created by the SAS facility, either explicitly, when an RA calls startTrail() or implicitly, when an RA or service calls getOrCreateTrail() with an activity reference. Trails typically last the lifetime of an activity but may be shared by multiple activities, e.g. a database lookup in call setup will use the trail of the SIP dialog or transaction.

SAS trails are composed of two data message types that are reported by the network element, Events and Markers. Each event and marker in a trail is reported asynchronously to the SAS server. SAS events are functional events that affect the processing of a call, e.g. a network message or a decision made by a service and the data that was used. SAS markers are informational data about a trail, typically used for search or correlation between trails. Both events and markers can contain parameters to provide information for display, search or correlation.

Bundles and Mini-bundles

A bundle file is a YAML document mapping event names to human readable descriptions. SAS requires event decoding bundle files to display the events received. Correlation and storage do not require the bundle file, it is only used at display time.

Rhino extends the SAS bundle model to use composable mini-bundles that are assembled at runtime into a bundle to export for loading into SAS. Each network element may only use one bundle when reporting to a SAS instance so Rhino builds this bundle from all the mini-bundles found in components deployed to a namespace. Developers of resource adaptors and services that use the SAS facility must write mini-bundle files to describe the events their components report.

Mini-bundles contain a set of named event descriptions and enumerated values used to construct a SAS bundle. These are combined with system-identifying information configured in Rhino to produce the bundle SAS will use to decode messages. Each mini-bundle file starts with a version, followed by a set of events and, optionally, enums listing values that can be expanded from integer "static" parameters in event messages. A component may report events from multiple mini-bundles. Events have symbolic names to support use by multiple components. They must be packaged in a deployment jar that is installed into Rhino with the component that reports the events. This may be the same jar as the component or another that the component depends on.

After deployment the system operator exports the merged bundle and installs it into the SAS UI. At this time the component bundles are combined with the configured Resource ID and written with numeric IDs to form a bundle file SAS can load. If multiple versions of a mini-bundle are deployed, only the latest version will be used. For more information on how Rhino combines mini-bundles see SAS Bundle Generation and SAS Bundle Mappings in the Rhino Administration and Deployment Guide

Note It is not safe to alter the meaning or order of event or enum values between versions of a bundle. This includes removing old events, a bundle may only grow larger.

Rhino comes with an Ant task for creating enum classes from bundle files generate-bundle-enums. Java enums are created for the SAS events and enums in the bundle file provided. The bundle files must be named for the package the enums will be created in.

Each event in a bundle must have a summary and a level. It may optionally contain details and call-flow data. Call flow descriptions must contain data, protocol and direction, other attributes are optional but should be provided where available. All text attributes of events can contain parameterised text using the Liquid templating language. For full details of the event structure contact your Metaswitch representative.

For an example of a mini-bundle file, see Service Assurance Server (SAS) Tracing in the HTTP resource adaptor guide.

Invoking Trail Accessor

On event delivery to a service, the invoking Trail is made available through the Invoking Trail Accessor. Calling getInvokingTrail() will return the SAS trail attached to the ACI on which the event was fired. On subsequent downcalls into RAs that result in a new SLEE activity being created via SleeEndpoint.startSuspended, the invoking trail (if one exists) will automatically be attached to the new activity. This behaviour means that a SAS trail will automatically be passed along through any number of downcalls into RAs and asynchronous events as long as the service always attaches to the ACI for the new activity.

In most cases, this behaviour is desired and saves one from having to add code that explicitly gets a trail from the invoking ACI and attaches it a new ACI. If necessary, however, one can call setInvokingTrail(Trail) or remove() to manually set or clear the invoking trail before calling into a RA.

Trail Association and Colocation

SAS Trails that form part of the same call can be associated by calling associate(Trail). If the Rhino SAS facility is configured with multiple SAS servers, different trails may not be using the same server.

Associating trails that are using the same SAS server is more efficient, as a trail association message can be sent to the one server informing it that the trails form part of the same trail group. If the trails being associated are using different servers, then a generic correlation marker gets sent to each SAS server with the UUID of the one trail. The SAS reporting then needs to perform some additional work to correlate the trails.

To ensure related trails are colocated on the same SAS server, SLEE components can call startColocatedTrail(Trail) or startAndAssociateTrail(Trail, Scope). These methods will create a new SAS trail using the same server as the given trail and, in the second case, will automatically send a trail association message to the server.

Entry point to the SAS event reporting facility.

Users of this facility create a Trail, then use that to create and report events The Trail interface provides two ways to create then report Events and Markers:

  1. create a message, add parameters, then report the message

  2. convenience methods that create a Marker or Event, with various combinations of parameters, then report it, in one call.

The SAS Facility supports communication with a federation of SAS servers. As such, trails created with startTrail() are distributed between servers by simple round-robin. When starting a new trail that will be associated with an existing one, use startColocatedTrail(Trail) or startAndAssociateTrail(Trail, Scope) to start a new trail on the same server as the given trail.

Tip Since Rhino 2.6.0

The primary interface for creating and reporting markers and events. A trail is a sequence of related events and markers representing the processing sequence for a dialog or transaction.

Tip Since Rhino 2.6.0

Provides access to the InvokingTrail. The InvokingTrail is the SAS trail attached to the activity owning the current event, at the time the event is delivered.

Tip Since Rhino 2.6.0

Superinterface of EventMessage and MarkerMessage with functionality common to both.

A Message sent to SAS may contain parameters to be used when decoding the message on the SAS server for display or correlation.

Variable-length parameters

Thread-safety

There are some critical thread-safety issues to consider for parameters added to messages.

Parameters are not copied or marshalled into the message until report() is called, and then only if SAS tracing is enabled.

This means two things:

  1. Parameters must not be modified until the report() method is called.

  2. Large or complex objects can be passed to this method, and if tracing is disabled or the event is discarded and not reported, it will have negligible memory or CPU cost

The threadSafeParam(byte[]) method allows callers to add a parameter that will not be copied, even after report() is called. This should be used for parameters which the caller plans to modify and has therefore defensively copied or marshalled into a new byte array.

Object parameter handling

Parameters passed to varParam(Object) and the multi-parameter equivalents will be handled differently depending on their type:

  • null — Encoded as zero length byte array.

  • byte[] — copied directly into the message

  • java.nio.ByteBuffer — Warning: Unsupported. Will be coerced to zero length byte array. Use threadSafeParam(byte[]) instead.

  • java.lang.String — encoded as UTF-8 and copied into the message

  • implements EncodeableParameter — call EncodeableParameter#encode(ByteBuffer) copy bytes written to stream into the message

  • implements MarshalableParameter — call MarshalableParameter#marshal() and copy the returned byte[] into the message

  • any other type — call Object#toString() and proceed as for java.lang.String

The varParam method should not be used for parameters that implement EnumParameter). It will still add the parameter but will log an error message. staticParam(EnumParameter) should be used for enum parameters.

As noted above, this marshalling/copying happens when the report() method is called, not when the parameters are added to the message. There are exceptions to this. These conversions happen when the parameter is added:

  1. null parameter to empty byte array

  2. ByteBuffer to empty byte array

  3. EnumParameter to its integer value

Tip Since Rhino 2.6.0

Methods to set message fields specific to Events.

An EventMessage is a message to SAS describing a network event or processing step within a network service. EventMessages have an ID used to look up a description from a bundle deployed to the SAS server and contain parameters holding information about the state of the system that led to the event being reported.

Tip Since Rhino 2.6.0

Methods to set message fields specific to Markers.

A MarkerMessage is a message sent to SAS to provide context about a trail. The marker may be used for correlating multiple trails into a trace or branch. It may also be used for searching for a trace in the SAS UI.

Some markers have special meaning to the SAS server, the START, END and FLUSH markers indicate when a trail is started, when one is ended, and when no more data is expected in the next few seconds.

Tip Since Rhino 2.6.0

Ant task to generate Java enums from mini-bundle files. Contains an implicit fileset parameter that identifies the set of SAS bundle files to create Java enums for.

Task attributes are:

dir: The base directory to search for bundle files destDir: The output base directory where enum classes will be created eventsClassName: Optional. The classname for the generated events enum

See Fileset for attributes to control the selection of files parsed by the task

Generate enums from a bundle file com/opencloud/slee/services/example/sas/sas-bundle.yaml found in ${resources}/sas-bundles.

The output classes will be created in ${src}, including com.opencloud.slee.services.example.sas.SasEvent and any enums representing SAS enums in the bundle.

<generate-bundle-enums destDir="${src}" dir="${resources}/sas-bundles" includes="com/opencloud/slee/services/example/sas/sas-bundle.yaml"/>
Generate enums from a bundle file at the path sas/com.opencloud.test.rhino.sas.bundle.ra.yaml relative to ${resources}.

The output classes will be created in ${src}, including com.opencloud.test.rhino.sas.bundle.ra.RaSasEvent and any enums representing SAS enums in the bundle.

<oc:generate-bundle-enums destDir="${src}"
                              dir="${resources}"
                              eventsClassname="RaSasEvent">
   <include file="sas/com.opencloud.test.rhino.sas.bundle.ra.yaml"/>
</oc:generate-bundle-enums>
Previous page Next page