GET: All Trace Details
A reference to the GET: All Trace Details endpoint in the SmartTrace API
GET: All Trace Details retrieves information about a single SmartTrace trace in 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: All Trace Details is:
GET /api/v1/tcpip/{region}/smart/trace/{id}/
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 |
Response Format
Returned tabular data for the SmartTrace instance detail appears in the following format:
{ "apiVersion": "v1", "data": { "id": "WWFCPCOPY-341-5-TCPIP11-0-0", "key": { "definitionName": "WWFCPCOPY", "generation": 341, "sequence": 5, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 0 }, "info": { "type": "STANDARD", "state": "RUNNING", "status": "MAIN", "packetCount": 250, "totalPacketCount": 178592 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": null, "expire": null } }, "swaggerVersion": "2", "time": 1564754568891 }
Interface Properties
The following table describes the properties in the returned SmartTrace instance rows:
Trace ID information
Property Name | Data Type | Description |
ID | String | A NetMaster-generated identifier for the trace. The ID of the trace is of a hyphenated string of six key properties (see the following rows) in hyphenated format:
key.definitionName-key.generation-key.sequence-key.stackName-key.tcpCreatorSequence-key.snapshotSequence For example: WWFCPCOPY-341-5-TCPIP11-0-0 |
definitionName | String | The name of the SmartTrace definition |
generation | Integer | The generation number of the SmartTrace definition |
sequence | Integer | The sequence of the SmartTrace definition
For example, if two trace instances are associated with the same trace definition, the first trace is 1 in the sequence, and the second trace is 2. |
stackName | String | The TCP/IP stack on which the SmartTrace is running |
tcpCreatorSequence | Integer | A unique identifier for TCP-creator type SmartTrace trace instances
The value for separate trace instances is incremented. |
snapshotSequence | Integer | A unique identifier for SmartTrace snapshots
Because multiple snapshots can be captured for the same trace instance, the value is incremented for each snapshot captured. |
TraceInfo
Property Name | Data Type | Description |
type | String | The type of trace
|
state | String | The current state of the trace
There are four possible values:
|
status | String | The current status of the trace
Status applies only to traces that are in a state of RUNNING. If a trace is not running, the status is NONE. There are four possible values:
|
packetCount | Integer | The number of packets currently stored in the trace buffer |
totalPacketCount | Integer | The total number of packets traced |
TraceChecks:
Property Name | Data Type | Description |
didEncounterStopCondition | Boolean
True or False | Indicates whether the trace encountered a STOP condition |
hasSeenIPv6Packets | Boolean
True or False | Indicates whether at least one IPv6 packet was detected in the trace |
isCreatorAtLimit | Boolean
True or False | Indicates whether the creator has reached its limit |
isTcpConversation | Boolean
True or False | Indicates whether the trace is part of a TCP conversation |
isUdpConversation | Boolean
True or False | Indicates whether the trace is part of a UDP conversation |
TraceSummaryIpInfo:
Property Name | Data Type | Description |
localAddress | Integer | The local IP address |
localPort | Integer | The local IP port |
remoteAddress | Integer | The remote IP address |
remotePort | Integer | The remote IP port |
tcpServerLocation | String | Location of the TCP/IP server
There are three possible values:
|
Timestamps:
Property Name | Data Type | Description |
start | Integer | The start time of the trace in milliseconds, displayed in Universal Time Coordinated (UTC) time. |
end | Integer | The end time of the trace in milliseconds, displayed in UTC time
If the trace is still running, this field displays null . |
expire | Integer | The expiration time in milliseconds, displayed in UTC time When the trace expires, it is cleared from memory. Traces that are not saved before the expire time are, in effect, permanently deleted.
If the trace is still running, this field displays null . |
Additional Properties:
Property Name | Data Type | Description |
totalRows | Integer | The total number of rows of available data |
swaggerVersion | Integer | The Swagger version |
time | Integer | The time in milliseconds, displayed in UTC time, when the response was generated |
Status Codes
The following status codes can appear in the response to GET: All Trace Details:
- 200 OK- A matching trace was found.
- 400 Bad Request- Trace details 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- A trace could not be found because the user does not have the appropriate authority to view traces.
- 404 Not Found- A trace matching the URI parameters could not be located.
- 500Server error
Sample Requests and Responses
Sample: Single Trace Request
The following request queries trace
WWFCPCOPY-341-5-TCPIP11-0-0
on NetMaster region U22NDE55
:
GET /api/v1/tcpip/U22NDE55/smart/trace/WWFCPCOPY
-341-5-TCPIP11-0-0
Sample: Response for a Single Trace Request
{ "apiVersion": "v1", "data": { "id": "WWFCPCOPY-341-5-TCPIP11-0-0", "key": { "definitionName": "WWFCPCOPY", "generation": 341, "sequence": 5, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 0 }, "info": { "type": "STANDARD", "state": "RUNNING", "status": "MAIN", "packetCount": 250, "totalPacketCount": 178592 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": null, "expire": null } }, "swaggerVersion": "2", "time": 1564754568891 }