GET: All Packet Summary

The NetMaster GET: All Packet Summary API endpoint retrieves a list of all packets in a SmartTrace trace.
GET: All Packet Summary retrieves a list of all packets in a specific SmartTrace trace, within a specified region. The following reference article includes:
  • Uniform Resource Identifier (URI) Parameters
  • Query Parameters
  • Response Format
  • Interface Properties
  • Status Codes
  • Sample Requests and Responses

URI Parameters

The URI for GET: All Packet Summary is:
GET /api/v1/tcpip/{region}/smart/trace/{id}/packets
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

Query Parameters

Parameter
Data Type
Default
Description
index
Integer
0
Start position (zero-based row number) of the data to return
limit
Integer
0
Limit (maximum number of rows) on the data to return
sort
String
packetNumber:asc
The sort order of the definition data in the format:
(COL_NAME): (asc | desc)

Response Format

Returned tabular data for the summary packets in a SmartTrace trace appears in the following format:
packetNumber: Int32; connection: { localHost: string; localPort: Int32; remoteHost: string; remotePort: Int32; direction: 'SEND' | 'RECV'; } length: Int32; protocol: string; timing: { absolute: Long; delta: Long; }; 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
Sortable
Description
packetNumber
Integer
Yes
The packet number, in the form of an integer value from 1 to 99,999.
connection
n/a
n/a
Header for connection details.
localHost
String
Yes
The IP address of the z/OS stack for this IP address or connection.
localPort
Integer
Yes
The port number on the local host. This property applies only to TCP and UDP packets.
remoteHost
String
Yes
The IP address of the remote host that is connecting to this z/OS IP stack.
direction
String
Yes
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
No
The total number of bytes in the packet, including IP headers and data payload.
protocol
String
Yes
The IP protocol of the packet, as translated from the Internet Assigned Numbers Authority (IANA) number to the protocol name.
timing
n/a
n/a
Header for timing details.
absolute
Long
Yes
The UTC timestamp in microseconds indicating when the packet was received.
delta
Long
Yes
The time difference, in seconds, between a packet and the previous packet. If the time value is less than 0.000001 seconds (1 microsecond), its shows as "0".
summary
String
No
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
n/a
Header for Information about the first 16 bytes of the packet, following the removal of the IP header.
hex
String
No
The first 16 bytes of the packet in hexadecimal format.
ebcdic
String
No
The first 16 bytes of the packet, as rendered in EBCDIC format.
ascii
String
No
The first 16 bytes of the packet, as rendered in ASCII format.
stackInterface
String
No
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: All Packet Summary:
  • 200 OK
    - Packet summary information was returned.
  • 400 Bad Request
    - 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
    - Packet summary information could not be returned because the user does not have the appropriate authority to view packets.
  • 404 Not Found
    - Packet summary information could not be returned because a trace matching the URI parameters could not be located.
  • 500
    - Server error

Sample Requests and Responses

Sample Packet Summary Request:
The following request queries trace
TH000002DB
on NetMaster region
U22NDE55
:
GET /api/v1/tcpip/U22NDE55/smart/trace/
TH000002DB
/packets
Sample Packet Summary Response:
{ "apiVersion": "v1", "data": { "index": 0, "keys": [ "packetNumber" ], "rows": [ { "packetNumber": 1, "connection": { "localHost": "10.175.84.103", "localPort": 38881, "remoteHost": "10.37.7.105", "remotePort": 49188, "direction": "RECV" }, "length": 833, "protocol": "TCP", "timing": { "absolute": 1578602055399254, "delta": 1325 }, "summary": "TLS1.2: HSHK( SERVER_HELLO CERTIFICATE SERVER_HELLO_DONE )", "data": { "hex": "97E1C0249095153D8D89F61D50180FEF", "ebcdic": "p.{..n...i6.&...", "ascii": "...$...=....P..." }, "stackInterface": "OSD020I" }, { "packetNumber": 2, "connection": { "localHost": "10.175.84.103", "localPort": 38881, "remoteHost": "10.37.7.105", "remotePort": 49188, "direction": "SEND" }, "length": 833, "protocol": "TCP", "timing": { "absolute": 1578602055399254, "delta": 1325 }, "summary": "TLS1.2: HSHK( SERVER_HELLO CERTIFICATE SERVER_HELLO_DONE )", "data": { "hex": "97E1C0249095153D8D89F61D50180FEF", "ebcdic": "p.{..n...i6.&...", "ascii": "...$...=....P..." }, "stackInterface": "OSD020I" } ], "totalRows": 2 }, "swaggerVersion": "2", "time": 1564754568891