GET: Single Packet Summary (saved trace)

The NetMaster GET: Single Packet Summary API endpoint retrieves summary information about a single packet in a saved SmartTrace trace.
GET: Single Packet Summary (saved trace) retrieves summary information for a single packet in a saved SmartTrace trace within a specified region. The following 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/saved/{id}/packets/{packetnumber}
Parameter
Description
region
The NetMaster region.
id
The ID of the trace. Enter the trace ID for a saved trace in the format
tracename-n
, where "n" is the number of a saved trace for a specific trace definition.
packetnumber
The number of the packet for which you want to see summary information.

Response Format

The tabular data returned for a single packet summary of a saved 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.
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.
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".
totalPackets
Integer
The total number of packets in the trace that contains the packet being summarized.
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.

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
1
, from saved trace
ATRACE-1
on NetMaster region
U22NDE55
:
GET /api/v1/tcpip/U22NDE55/smart/saved/
ATRACE-1
/packets/1
Sample Packet Summary Response:
{ "apiVersion": "v1", "data": { "index": 0, "keys": [ "packetNumber" ], "rows": [ { "packetNumber": 1, "connection": { "localAddress": "10.xxx.xx.103", "localPort": 38881, "remoteAddress": "10.xx.x.105", "remotePort": 49188, "direction": "RECV" }, "length": 833, "protocol": "TCP", "timing": { "absolute": 1578602055399254, "delta": 1325 }, "totalPackets": 1000 "summary": "TLS1.2: HSHK( SERVER_HELLO CERTIFICATE SERVER_HELLO_DONE )", "data": { "hex": "97E1C0249095153D8D89F61D50180FEF", "ebcdic": "p.{..n...i6.&...", "ascii": "...$...=....P..." }, "stackInterface": "OSD020I" }, }, "swaggerVersion": "2", "time": 1564754568891