Details

Feature Script Name

ExternalSessionTracking

Applicable Contexts

SIP service

Call-Type

All

Session Plan

All

Execution Point

Most SipAccess, SipMidSession, Subscription, and EndSession system post-scripts

Network Operator Config

None

Subscriber Config

None

POJO or SBB

POJO

Feature FSMs

None

Feature Parameters

None

SAS Support

No

Prerequisite features

None

Feature Statistics

ExternalSessionTracking statistics are tracked by the sentinel.sip SBB and can be found under the following parameter set:
SLEE-Usage → sentinel.sip service ID → sentinel.sip SBB ID → feature.ExternalSessionTracking

Name Type Description 
Started

Counter

Incremented when the feature is triggered.

 
FailedToStart

Counter

Incremented when the feature fails to start.

 
FailedDuringExecution

Counter

Incremented when the feature fails while executing.

 
IssuedWarning

Counter

Incremented when the feature issues a warning.

 
TimedOut

Counter

Incremented when the feature times out during execution.

 
RequestedStore

Counter

Incremented when the feature attempts to store a record in the session ownership facility.

 
StoreSuccess

Counter

Incremented when the Session Ownership Facility successfully stores a full record.

 
StorePartialFailure

Counter

Incremented when the Session Ownership Facility fails to store some parts of a record.

 
StoreFailure

Counter

Incremented when the Session Ownership Facility fails to store any parts of a record.

 
RequestedDelete

Counter

Incremented when the feature attempts to remove a record from the session ownership facility.

 
DeleteSuccess

Counter

Incremented when the Session Ownership Facility successfully deletes a full record.

 
DeletePartialFailure

Counter

Incremented when the Session Ownership Facility fails to delete some parts of a record.

 
DeleteFailure

Counter

Incremented when the Session Ownership Facility fails to delete any part a record.

 
StartedSessionOwnershipActivity

Counter

Incremented when the feature starts a new session ownership activity.

 
EndedSessionOwnershipActivity

Counter

Incremented when the feature ends its session ownership activity.

 
FoundNewDialogIdThatRequiresTracking

Counter

Incremented when the feature detects that a new leg needs to be tracked, or that an existing tracked leg’s dialog ID has changed.

 
FoundDialogIdRequiringUpdate

Counter

Incremented when the feature detects that a leg has new information that needs to be tracked on its session ownership record.

 
FoundDialogIdDueForRefresh

Counter

Incremented when the feature detects that a leg’s session ownership record is approaching its TTL expiration, and needs to be refreshed.

 
ChangedOwnershipOfLeg

Counter

Incremented when the feature changes the owner of a session (SIP Dialog) from one node to a different node.

 
ChangedOwnershipOfCharging

Counter

Incremented when the feature changes the owner of a Charging Instance (Ro Dialog) from one node to a different node.

 
SuccessfulQueryTime

Sample

Samples the time taken for a success response to be received from the session ownership facility for any given request.

 
PartiallyFailedQueryTime

Sample

Samples the time taken for a partial failure response to be received from the session ownership facility for any given request.

 
FailedQueryTime

Sample

Samples the time taken for a failure response to be received from the session ownership facility for any given request.

Behaviour

This feature monitors all legs in a session, regularly checking if any of the legs require a session ownership record, and if so, what information should be stored in that record. The feature maintains its own list of which legs currently have records in the session ownership facility, and when those records were last updated.

The exact behaviour of the feature differs based on how it is invoked:

  • If the feature is invoked at the SipEndSession feature execution point, it will execute End Session Clean-Up behaviour.

  • If it is invoked at any other feature execution point, it will execute Leg Tracking behaviour, followed by Charging Instance Tracking behaviour.

  • If the feature is invoked with a SessionOwnershipWriteResultEvent via the Session Ownership Event Handler, it will execute Result Processing behaviour.

Session Ownership Records for protocol dialogs

Session ownership records are used to track information about specific sessions across multiple Rhino nodes. Their main purpose it to indicate which node is currently responsible for processing a session, but they can also be used for other information that Sentinel features might need to keep track of across nodes. They are stored the in Rhino Session Ownership Facility.

Sentinel SIP has the capability to maintain zero or one session ownership records for a SIP leg, and zero or one session ownership records for an Ro Dialog. Session ownership records are not maintained for all legs at all times, instead individual legs can be flagged for tracking in the session ownership facility. When that flag is seen by this feature, it will create a session ownership record for the leg. The flag can be set by the Sentinel SIP service when session replication is triggered, or by user features that need a leg to be tracked for their own purposes.

If the Sentinel Session has an Ro dialog, and at least one SIP leg is tracked, then the Ro session is tracked.

All protocol dialog session ownership records created, or updated by this feature are linked to the Sentinel Session’s Convergence Name Session Ownership Record. This ensures that after a fail-over, any simultaneous signalling will resolve to a single node.

Fields on a SIP Dialog Session Ownership Record

Certain fields on the Sentinel SIP Leg API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the Leg API, and data stored on a session ownership record.

Session Ownership Record Field Corresponding Leg API Getter Corresponding Leg API Setter Notes

PrimaryKey

 
getDialogID().toTrackingKey()
 
N/A

The primary key cannot be modified and is always based on the SIP Dialog ID associated with the leg.

OwnerURI

 
getOwner()
 
setOwner()

While the owner can be modified by other features, it should generally be left to this feature to set it.

AdditionalKeys

 
getAdditionalTrackingKeys()
 
setAdditionalTrackingKeys()

-

Attributes

 
getAdditionalTrackedAttributes()
 
setAdditionalTrackedAttributes()

-

The dialog ID of a leg is used as the primary key for the session ownership record. This means that if the dialog ID changes (e.g. when the dialog is confirmed by the remote party) a new record is created and the old one is deleted.

There are a few other SIP Leg API calls that relate to Session Ownership Records: - setTrackingEnabled() and isTrackingEnabled() are used set and read the flag that determines whether a session ownership record will be created for a leg. - setWaitForTrackingResultEnabled() and `isWaitForTrackingResultEnabled() are used to set and read a flag that affects how this feature manages asynchronous queries to the session ownership facility (see below). - getLastTrackingDataChangeTime() provides the timestamp of the last time that a call to any of: setTrackingEnabled(), setOwner(), setAdditionalTrackingKeys(), or setAdditionalTrackedAttributes() on the Leg API actually resulted in a meaningful change in the leg’s tracked state.

Fields on a Ro Dialog Session Ownership Record

Certain fields on the Sentinel SIP ChargingInstance API are used to populate associated fields on a session ownership record. The following table outlines the relationship between data stored using the ChargingInstance API, and data stored on a session ownership record.

Session Ownership Record Field Corresponding ChargingInstance API Getter Corresponding CharingInstance API Setter Notes

PrimaryKey

 
getTrackingKey()
 
N/A

The primary key cannot be modified and always includes the Ro session identifer.

OwnerURI

 
getOwner()
 
setOwner()

While the owner can be modified by other features, it should generally be left to this feature to set it.

Leg Tracking

When the feature is invoked to do standard tracking behaviour, it will get the set of current legs from the leg manager and iterate over it. For each leg in the set, the feature will go through the following steps:

  1. Check if the leg is flagged for tracking.

    • If it is not it will skip the remaining steps and move on to the next leg.

    • If it is flagged for tracking, the feature will move on to the next step.

  2. Check if there is already a session ownership record stored under the leg’s Dialog ID.

    • If not, the feature will create a new record and write it into the session ownership facility. The remaining steps will then be skipped and the feature will move on to the next leg.

    • If so, it will move on to the next step.

  3. Check if the owner node in the record matches the node currently executing the feature.

    • If not, a fail-over has occurred and the feature will take ownership of the leg (using Leg.setOwner()), and write an updated record into the session ownership facility (indicating that the owning node is the currently executing node). Then skip the remaining steps and move on to the next leg.

  4. Check when the tracked data on the leg was last modified against the last time that the session ownership record was updated.

    • If the leg’s tracked data has been modified since the last time the session ownership record was updated, then the feature will create and write an updated record into the session ownership facility. It will then skip the remaining step and move on to the next leg.

  5. Check whether the record’s TTL could expire before the feature is next invoked.

    • If so, then the existing record will be rewritten into the session ownership facility with a refreshed TTL.

    • Otherwise the feature will move on to the next leg.

After processing all of the legs, the feature will look for any records it has stored under Dialog IDs that no longer correspond to any leg that has tracking enabled. If it finds any such records, it will delete them from the facility.

All store and delete requests sent to the session ownership facility are executed asynchronously. The value of isWaitForTrackingResultEnabled() on the Leg API will affect the feature’s behaviour while it waits for the result for requests relating to that leg’s session ownership record. If any leg that has an outstanding store request to session ownership facility returns true for that API call, the feature will enter a featureWaiting state while it has nothing to do. This will prevent the session plan advancing to the next feature while the session ownership request is in progress. This is useful if further down the session plan, there is a feature that requires the session ownership record to be in place. If all legs with outstanding requests return false, then the feature will enter the featureHasFinished state while it waits, and session processing will continue in the mean time. The feature will not normally enter the featureWaiting state for delete requests.

This means that the feature can block further SIP signalling progress until a write has either succeeded, failed or timed out on a per-leg basis. There are several application specific use-cases where the database state (behind the session ownership facility) must be visible before further SIP signalling proceeds.

Charging Instance Tracking

When the feature is invoked to do standard tracking behaviour, it first checks if any SIP legs are tracked and if so it checks if a Charging instance exists and is not in the Final state. This essentially means that if Diameter Ro charging is in-use, and Session Replication is enabled, then the Ro session is tracked.

The feature goes through the following steps to determine if the Charging Instance (Ro Session) should be tracked:

  1. Check if there is already a session ownership record stored under the Ro Dialog’s tracking key (this is a value that includes the Ro session identifier)

    • If not, the feature will create a new record and write it into the session ownership facility, and further steps are skipped

  2. Check if the owning node in the record matches the node currently executing the feature.

    • If not, a fail-over has occurred, and the feature writes an updated record indicating that the owning node is the currently executing node. Further steps are skipped.

  3. Check when the tracked data on the Charging Instance was last modified against the last time that the session ownership record was updated. If an update is needed the feature updates the record in the session ownership facility and skips the remaining steps.

  4. Check whether the record’s TTL could expire before the feature is next invoked. If so the existing record is rewritten into the session ownership facility with a refreshed TTL.

All store and delete requests sent to the session ownership facility are executed asynchronously. The feature does not enter a waiting state for a Charging Instance’s session tracking write response (success, failure or timeout).

Result Processing

When a result is received from the session ownership facility, the feature simply records statistics and logs messages based on whether the result is successful, partially successful, or unsuccessful. After processing the result, the feature will decide to enter a featureWaiting or featureHasFinished state based on the same criteria used in Leg Tracking behaviour.

End Session Clean-Up

When the feature is triggered at session end, it create delete requests for all remaining session ownership records associated with the session. While under normal circumstances, the feature would not enter the featureWaiting state for delete requests, during end session behaviour the feature will keep going into the featureWaiting state until ALL outstanding requests are answered. This prevents to session from ending until all records have been handled.

Previous page Next page
Sentinel Express Version 4.1