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.
The transport analysis feature can retrieve the following types of data at periodic intervals.
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.
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.
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.
[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.
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).
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.
// 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; } |
Analysis data is not printed to the console in a release build. There are two ways to get analysis data in a release build.
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.
// 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); } |
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.
- 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.
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.
- 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.
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.
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.
An application can introduce separator lines in a graph at any time by calling a separator line insertion function in the TransportAnalyzer class.
// 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.
- 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.
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. |
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.
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.