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:
|
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/1Sample 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