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:
|
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
/packetsSample 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