5.9. Debug Support - Transport Analysis Feature

Description

The PiaTransport module includes a transport analysis feature for assessing communication performance. This section describes the transport analysis feature, provides code samples, and describes how to use the associated graphing tool.

Analysis Data

The transport analysis feature can retrieve the following types of data at periodic intervals.

  • The number and data size of packets sent and received.
  • The type of message protocol used to send and receive messages, the number of messages sent, and the size of the message data.
  • The round-trip time (RTT) for each station.
  • The packet loss rate for each station.

The PiaTransport module also contains a tool called PiaTransportAnalyzer (described below) that enables you to plot these data types against time. The resulting graphs can provide a nice visualization of communication performance.

Analysis Data Automatic Print Feature

Transport analysis is provided by the TransportAnalyzer class. An instance of this class is implicitly created and destroyed as a singleton by the PiaTransport class.

The TransportAnalyzer class has a feature to print analysis data automatically to the console. To use this feature, create an instance of the Transport class after setting the analysisInterval member of the Transport::Setting structure to a positive value.

Code 5-34. Feature for Automatically Printing TransportAnalyzer Measurement Data
nn::pia::transport::Transport::Setting setting;
 
// (Assignment of other members is omitted.)
 
setting.analysisInterval = 5; // Units in seconds.
nn::pia::transport::Transport::CreateInstance(setting);

If the settings are as shown above, data is printed on the console as shown below every five seconds.

Code 5-35. Printed Analysis Data
[Pia] [Analysis] ------ BEGIN(Pia Send, 45.696 sec. passed) ------
[Pia] [Analysis] ProtocolId, TotalNum, TotalSize, AverageSize, Protocol(port)
[Pia] [Analysis] 0xffffffff, 433, 242244, 559, Packet
[Pia] [Analysis] 0x20000000, 300, 186000, 620, Unreliable(0)
[Pia] [Analysis] 0x30000000, 558, 38272, 68, Reliable(0)
[Pia] [Analysis] ---------------------------- END ----------------------------
[Pia] [Analysis] ------ BEGIN(Pia Receive, 45.696 sec. passed) ------
[Pia] [Analysis] ProtocolId, TotalNum, TotalSize, AverageSize, Protocol(port)
[Pia] [Analysis] 0xffffffff, 407, 228064, 560, Packet
[Pia] [Analysis] 0x30000000, 548, 37832, 69, Reliable(0)
[Pia] [Analysis] 0x20000000, 281, 173656, 617, Unreliable(0)
[Pia] [Analysis] ---------------------------- END ----------------------------
[Pia] [Analysis] ------ BEGIN(Pia Connection info, 45.696 sec. passed) ------
[Pia] [Analysis] StationIndex, RTT, PacketLoss
[Pia] [Analysis] 0x01, 100, 9.62
[Pia] [Analysis] ---------------------------- END ----------------------------

The printed analysis data spans multiple lines, so it takes a relatively long time to complete the output. To avoid affecting the behavior of your application, set the time interval to at least several seconds.

Also, when configured to output large amounts of trace data, the analysis data can be mixed with the trace output. In such cases, the analysis data parsing tools described below cannot parse the data correctly, and errors occur. For this reason, avoid trace output as much as possible when outputting transport analysis data.

Getting Transport Analysis Data Explicitly

An application can obtain transport analysis data without using the automatic print function described previously. To stop using the automatic print function, set the analysisInterval member of the Setting structure to 0 (zero).

Code 5-36. Setting to Not Use the Automatic Print Feature
nn::pia::transport::Transport::Setting setting;

// (Assignment of other members is omitted.)

setting.analysisInterval = 0;
nn::pia::transport::Transport::CreateInstance(setting);

When this setting is configured, the application must explicitly instruct the TransportAnalyzer instance to update and retrieve the data.

Code 5-37. Explicitly Getting and Printing Analysis Data
// Use the transport analysis feature. Output the analysis data to the console at five-second intervals.
// Put this code in your main application loop, so that it can run each time through the loop.
nn::pia::transport::TransportAnalyzer* pAnalyzer = nn::pia::transport::TransportAnalyzer::GetInstance();
if(pAnalyzer)
{
    static int s_Counter = 0;
    const int PERIOD = 5 * FPS;
    if(s_Counter % PERIOD == 0)
    {
        nn::Result r = pAnalyzer->Update();
        PIA_SAMPLE_ASSERT(r.IsSuccess());
        nn::pia::transport::TransportAnalysisData data = pAnalyzer->GetTransportAnalysisData();
 
        // Print the obtained transport analysis data to the console.
        // It is usually adequate to set the detailed display to false, but to show protocol and
        // if other data that is used implicitly and internally in Pia, set it to true.
        data.Print(false);
    }
    ++s_Counter;
}

Getting Analysis Data in a Release Build

Analysis data is not printed to the console in a release build. There are two ways to get analysis data in a release build.

  1. Have the application explicitly get an instance of the transport::TransportAnalysisData structure and access the member variables, as demonstrated above.
  2. Register a callback function defined by the application and get an analysis data string.

The method for registering a print callback function is as follows.

Prepare a callback function that can print to the console and use the transport::TransportAnalyzer::RegisterPrintCallback() function to register the callback. This registration allows the analysis data string to be passed to the callback and the data to be printed to the console.

Code 5-38. Registering a Callback Function
// Prepare an application-defined callback function.
// A string containing the analysis data is passed to pStr.
void appDefinePrintCallback(const char* pStr)
{
    printFunction(pStr);
    printFunction("\n");
}
 

void registerCallback()
{
    // Register the application-defined callback function for printing the analysis data.
    nn::pia::transport::TransportAnalyzer* pAnalyzer = nn::pia::transport::TransportAnalyzer::GetInstance();
    PIA_SAMPLE_ASSERT(PIA_IS_VALID_POINTER(pAnalyzer));
    pAnalyzer->RegisterPrintCallback(appDefinePrintCallback);
}

Graphing the Analysis Data Logs 

The Excel file in the following directory can be used as a tool for graphing logs of periodically output analysis data.

$CTRPIA_ROOT/tools/TransportAnalyzer/PiaTransportAnalyzer.xlsm

To generate a graph of the analysis data, open PiaTransportAnalyzer.xlsm, click the Start Analyzing button on the first worksheet, and then select the appropriate log file.

Reference:

- PiaTransportAnalyzer was created in Microsoft Excel 2010.

- Macros are embedded in this Excel file. The graphing feature does not work if you have disabled macros in your Microsoft Excel security settings. Make sure that you enable macros in your Excel security settings before trying to use this tool.

The Graphs

Communication Traffic Graph

This graph shows the total number of packets sent and received in addition to the message traffic for each communication protocol over the target time period. The legend on the right side of the graph contains entries for the packet (all packets data), in addition to the names and port numbers for each communication protocol. The title of the graph indicates whether this data is for data sent or data received. The vertical traffic num axis indicates the total number of packets or the number of messages for each protocol. The vertical traffic volume axis indicates the size of the data sent and received.
On the assumption that logs are output periodically, the amount of data sent and received per second is calculated and graphed using the elapsed time from the output timestamps.

Reference:

- The number of messages for each protocol may sometimes be higher than the total number of packets. Pia bundles several messages into each packet sent.

- When the log print interval is too long, values are averaged out, and any features of the communications state could be hidden.

Station RTT Graph

This graph shows the round-trip time (RTT) measured for each station over the target time period. The legend on the right side of the graph contains a hexadecimal StationId entry for each station in the session. A station shows an RTT of 0 during periods of time when the station was not connected or accurate RTT data could not be obtained.

Station Packet Loss Rate Graph

This graph shows the packet loss rate calculated for each station over the target time period. The legend on the right side of the graph contains a hexadecimal StationId entry for each station in the session.

Inserting Separator Lines

An application can introduce separator lines in a graph at any time by calling a separator line insertion function in the TransportAnalyzer class.

Code 5-39. Calling the Separator Line Insertion Function
// Output logs for inserting a line in a graph.
// The following code can be called by the application at any time (such as at a scene change).
nn::pia::transport::TransportAnalyzer* pAnalyzer = nn::pia::transport::TransportAnalyzer::GetInstance();
if(pAnalyzer)
{
    // Insert SceneChange as the separator line name.
    pAnalyzer->SetMarker("SceneChange");
}

A separator line explanation is added below the data legend, to the right of the graph.
In each graph example in the previous section, several separator lines with the names JoinEvent and LeaveEvent were inserted.

Note:

- Do not use whitespace characters (such as a space, tab, or return) in the separator line name.

- If multiple separator lines are inserted in a short period of time, regardless of whether the names are the same, the separator lines may overlap each other when the graph is generated.

Configuring Graph Settings

You can customize the graphs generated by the PiaTransportAnalyzer tool by configuring the settings in Graph Settings on the first worksheet.

Graph Settings
Height The height of the graphs. You can specify S, M, or L.
Width The width of the graphs. You can specify S, M, L, LL, or XL.
Thickness The thickness of graph lines and the size of markers. You can specify S, M, or L.
Scale The type of scale to use for the vertical axis on the graphs.
Normal: Normal scale.  Logarithm: Logarithmic scale.
Reference:

Scale: Data points with a value of 0 on the y-axis cannot be plotted on a logarithmic graph. If your data contains such entries, the graphs are scattergrams rather than line graphs.

Outputting Graphs as Images

To output the graphs as image files, click the Export Images As PNG / GIF / JPEG button on the sheet where the graphs are generated.
The images are output to the same directory where PiaTransportAnalyzer is located.