Message Tracing
- Nick Judson
Message tracing lets you visualize and report on the path a message has taken, from origin to destination. You can view the amount of time a message took to process as well as the latency as it moves through the Connexion and Integrator workflows. It also includes the ability to track messages through branch operations, across the remote agent-Connexion boundary, and secure-sender boundaries*.
Message tracing works across Remote Agent and Connexion instances. However, the trace view can only display where the message has been up to the point at which you are viewing it. For example, if your message passes through 3 Connexion systems (1, 2, 3), you will only get a complete view if you run the message trace from the final Connexion system (3). If you run the message trace on the intermediate system (2), you will not see any trace information from the final Connexion instance.
Message tracing works by embedding a trace history in each message that passes through Connexion (or Remote Agent). Each device that interacts with the message can optionally include some trace information. Each native Connexion device adds trace information. Information on how to include trace information in your custom devices is given below.
Message tracing information is displayed in a new queue window ‘Message Source Trace’. Like Processing History, this information relates to the currently selected message within the queue. The Source column is either a Uri or a Group/Tab/Channel name. Uris are displayed for trace information external to the current Connexion system. For example, network source Uris (http://, mllp://), file Uris (file://somepath), database Uris (db://…), etc. When the message trace contains pointers to channels within the current Connexion system, it will display the channel as a hyperlink (click to navigate to that channel).
The Stamp column contains the date the message trace information was inserted, and the Delay column contains the elapsed time from the previous stamp. The Delay from Origin column contains the running time span from the message origin (giving you the ability to see how long it took for the message to pass from ingestion to final destination).
A simple trace reading from a database:
Once a trace contains information from more than a single channel, a visualization option is shown. For example, if we branch a message to 10 other channels (the branch sample on the Connexion nuget server), we can navigate to a target channel and view both a tabular representation and a visual one:
In the above example, a message was received via mllp by the Branch channel. The message was then branched to 10 other channels (O1 through O10). When viewing a message in the O1 channel, we can see the message trace shows the incoming Uri, the receiving channel (Branch), our channel (O1) and finally the target mllp outbound system (127.0.0.1:12000). We can see that time the message queued within each channel and the total time it took from receiving the message to send to the final destination (1m 6s).
The copy icon in the Message Source Trace title bar can be used to copy and paste this information into a text editor or Excel.
Note the additional grey bar containing the hyperlink ‘Full Trace’. Use this hyperlink to create a visual representation for this message which includes all trace information available within the current Connexion System. This view will inspect this message within other channels so you can see other channels which also contain this message.
Remember, message tracing only shows information upstream to the currently selected queue. To view a message trace that spans multiple Connexion systems, run the trace from the final Connexion instance.
Clicking the ‘Full Trace’ hyperlink produces the following interactive trace:
In this diagram, we can see the origin of the message (the network), the message passing through the Branch channel to each target channel (O1 through O10), and each of those channels sending the message over the network to a target. The diagram is interactive, allowing you to zoom and pan. The channel in orange is the currently selected channel within the Connexion UI.
Note the 'P' in the green circle overlayed on the queue icon. This signifies the message is in a processed state within that queue. Other queues may contain that message in a queued, errored, or other state, and the circle text and color changes to signify this.
The Message Trace UI has the following toolbar:
From left-to-right, these buttons are:
Export diagram to image file.
Pop out/in from the main Connexion window. This is useful when viewing large diagrams which require screen space.
Diagram style (some of these are experimental and not particularly useful in most cases).
Line style
Zoom-to-fit
Toggle the display of trace textual information underneath each channel (this is useful on large diagrams which require screen space).
Close diagram (and return to the typical channel view).
Sample trace within a single Connexion system:
Accessing and Setting Trace Information
Trace information can be inspected and appended to in your custom devices (or the custom code device) and is accessible on the IMessageContext object.
// * Warning: Contrived example
using System;
using System.Threading;
using Connexion.Core;
using System.Threading.Tasks;
namespace Connexion.Device
{
public partial class CustomDevice : BaseCustomDevice
{
public override async Task ProcessMessageAsync(IMessageContext context, CancellationToken token)
{
// the trace information is exposed via the context.MessageExtension property
foreach(var trace in context.MessageExtension.GetMessageTrace())
{
// the trace object has a Uri property and Utc property
Console.WriteLine($"Uri: {trace.Uri}, Utc Stamp {trace.Utc}");
}
// add your own trace information
if(Uri.TryCreate("cxn://mydevice/operation", UriKind.RelativeOrAbsolute, out var uri))
context.MessageExtension.AddTrace(uri);
// if you are sending to an external resource, use the following overload to signify
// an outbound external endpoint
if(Uri.TryCreate("myservice://ingestionPath/", UriKind.RelativeOrAbsolute, out var uriOutbound))
context.MessageExtension.AddTrace(uriOutbound, TraceInfoFlag.Out);
}
}
}