GET: Single Packet Summary (active/ended trace)

Use the NetMaster GET: Single Packet Summary API endpoint to retrieve summary information about a single packet in an active or ended SmartTrace trace.
GET: Single Packet Summary retrieves summary information for a single packet in a SmartTrace trace within a specified region. This reference article includes:
  • Uniform Resource Identifier (URI) Parameters
  • Response Format
  • Interface Properties
  • Status Codes
  • Sample Requests and Responses

URI Parameters

The URI for GET: Single Packet Summary is:
GET /api/v1/tcpip/{region}/smart/trace/{id}/packets/{packetnumber}
Parameter
Description
region
The NetMaster region.
id
The ID of the trace. The trace ID consists of a hyphenated string of key properties in the following format:
key.definitionName-key.generation-key.sequence-key.stackName-key.tcpCreatorSequence-key.snapshotSequence
packetnumber
The number of the packet for which you want to see summary information.

Response Format

Returned tabular data for a single packet summary of an active or ended SmartTrace trace appears in the following format:
packetNumber: Int32; connection: { localAddress: string; localPort: Int32; remoteAddress: string; remotePort: Int32; direction: 'SEND' | 'RECV'; } length: Int32; protocol: string; timing: { absolute: Long; delta: Long; }; totalPackets: Int32; summary: string; data: { hex: string; ebcdic: string; ascii: string; } stackInterface: string;

Interface Properties

The following table describes the properties of the summarized SmartTrace packets:
Property Name
Data Type
Description
packetNumber
Integer
The packet number, in the form of an integer value that is greater than or equal to 1.
connection
n/a
Header for connection details.
localAddress
String
The IP address of the z/OS stack for this IP address or connection (the local host).
localPort
Integer
The port number on the local host. This property applies only to TCP and UDP packets.
remoteAddress
String
The IP address of the remote host that is connecting to this z/OS IP stack.
remotePort
Integer
The port number on the remote host.
direction
String
The travel direction of the packet:
  • SEND
    indicates that the packet is traveling from the local host to the remote host.
  • RECV
    indicates that the packet is traveling from the remote host to the local host.
length
Integer
The total number of bytes in the packet, including IP headers and data payload.
protocol
String
The IP protocol of the packet, as translated from the Internet Assigned Numbers Authority (IANA) number to the protocol name.
timing
n/a
Header for timing details.
absolute
Long
The UTC timestamp in microseconds indicating when the packet was received.
delta
Long
The time difference, in milliseconds, between a packet and the previous packet. If the time value is less than 1 milliscecond, its shows as "0".
summary
String
A summary of packet information. When possible, packet information is decoded. Decoding takes place for many IP protocols, EE/UDP and TCP applications, FTP, TELNET, HTTP and DRDA, and SMC.
data
n/a
Header for Information about the first 16 bytes of the packet, following the removal of the IP header.
hex
String
The first 16 bytes of the packet in hexadecimal format.
ebcdic
String
The first 16 bytes of the packet, as rendered in EBCDIC format.
ascii
String
The first 16 bytes of the packet, as rendered in ASCII format.
stackInterface
String
The z/OS stack interface on which the packet was received or sent.
totalPackets
Integer
The total number of packets being summarized. Since this is a single-packet summmary, the value is always 1.

Status Codes

The following status codes can appear in the response to GET: Single Packet Summary.
  • 200 OK
    - Single packet summary information was returned.
  • 400 Bad Request
    - Single packet summary information could not be returned due to an invalid format for the URI query parameters.
  • 401 Unauthorized
    - The user is not authenticated to the application. They must provide either a valid login token or valid credentials before continuing.
  • 403 Forbidden
    - Single packet summary information could not be returned because the user does not have the appropriate authority to view packets.
  • 404 Not Found
    - Single packet summary information could not be returned because a trace matching the URI parameters could not be located.
  • 500
    - Server error

Sample Request and Response

Sample Packet Summary Request:
The following request queries packet number
6
, from trace
WWFCPCOPY-341-5-TCPIP11-0-0
on NetMaster region
U22NDE55
:
GET /api/v1/tcpip/U22NDE55/smart/trace/
WWFCPCOPY-341-5-TCPIP11-0-0
/packets/6
Sample Packet Summary Response:
{ "data": { "packetNumber": 6, "connection": { "localAddress": "10.x.x.x", "localPort": 63158, "remoteAddress": "10.y.y.y", "remotePort": 40006, "direction": "RECV" }, "length": 52, "protocol": "TCP", "timing": { "absolute": 1666978684671, "delta": 0 }, "summary": "Ack Psh Win=4095 Seq=4225965973 Ack=1598973467 TimeStamp", "data": { "hex": "97E1C0249095153D8D89F61D50180FEF", "ebcdic": "p.{..n...i6.&...", "ascii": "...$...=....P..." }, "stackInterface": "LOOPBACK", "totalPackets": 1 }, "apiVersion": "v1", "swaggerVersion": "2.0", "time": 1666981647790 }