GET: All Traces List
The NetMaster GET: All Traces List API endpoint retrieves a list of all active SmartTraces in a specified region.
The GET: All Traces List retrieves a list of all active SmartTrace traces in a specified region. Active traces can be in three possible states:
Running
, Ended
, or Snapshot
.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 Traces List is:
GET /api/v1/tcpip/{region}/smart/trace
Parameters:
Use the
Region
parameter to identify the NetMaster region from which you are requesting data.Use the following optional URI parameters to filter the returned data and define how that data is sorted and displayed:
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 | id:asc | The sort order of the trace instance data in the format:
(COL_NAME): (asc | desc) |
definitionName | SimpleArrayFilter | n/a | The name of the SmartTrace definition or definitions. The results include only traces from the listed SmartTrace definitions. Entries are in the format:
definitionName=eq:def1 | def2 | def3 Multiple definitions are pipe-separated. Sample entry: GET /api/v1/tcpip/U22NDE55/smart/trace?definitionName=eq:WWFCPCOPY | WWFCQCOPY |
Response Format
Returned tabular data for the summary list of SmartTrace trace instances appears in the following format:
{ "apiVersion": "v1", "data": { "index": 0, "keys": ["id"], "rows": [ { "id": "CWTCPCOPY-341-5-TCPIP11-0-0", "key": { "definitionName": "CWTCPCOPY", "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 } }, { "id": "CWTCPCOPY-341-5-TCPIP11-0-1", "key": { "definitionName": "CWTCPCOPY", "generation": 341, "sequence": 5, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 1 }, "info": { "type": "STANDARD", "state": "SNAPSHOT", "status": "STOPPED", "packetCount": 250, "totalPacketCount": 1305286 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": 1631820603000, "expire": 1631822402000 } } ], "totalRows": 2 }, "swaggerVersion": "2", "time": 1564754568891 }
Interface Properties
The following table describes the properties in the returned SmartTrace trace instance rows and sections:
TraceSummaryID and TraceSummaryKey:
Property Name | Data Type | Sortable | Description |
ID | String | Yes | 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 | Yes | The name of the SmartTrace definition |
generation | Integer | Yes | The generation number of the SmartTrace definition |
sequence | Integer | Yes | 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 | Yes | The TCP/IP stack on which the SmartTrace is running |
tcpCreatorSequence | Integer | Yes | A unique identifier for TCP-creator type SmartTrace trace instances
The value for separate trace instances is incremented. |
snapshotSequence | Integer | Yes | 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 | Sortable | Description |
type | String | Yes | The type of trace
|
state | String | Yes | The current state of the trace
There are four possible values:
|
status | String | Yes | 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 | Yes | The number of packets currently stored in the trace buffer |
totalPacketCount | Integer | Yes | The total number of packets traced |
TraceSummaryChecks:
Property Name | Data Type | Sortable | Description |
didEncounterStopCondition | Boolean
True or False | Yes | Indicates whether the trace encountered a STOP condition |
hasSeenIPv6Packets | Boolean
True or False | Yes | Indicates whether at least one IPv6 packet was detected in the trace |
isCreatorAtLimit | Boolean
True or False | Yes | Indicates whether the creator has reached its limit |
isTcpConversation | Boolean
True or False | Yes | Indicates whether the trace is part of a TCP conversation |
isUdpConversation | Boolean
True or False | Yes | Indicates whether the trace is part of a UDP conversation |
TraceSummaryIpInfo:
Property Name | Data Type | Sortable | Description |
localAddress | Integer | Yes | The local IP address |
localPort | Integer | Yes | The local IP port |
remoteAddress | Integer | Yes | The remote IP address |
remotePort | Integer | Yes | The remote IP port |
tcpServerLocation | String | Yes | Location of the TCP/IP server. There are three possible values:
|
Timestamps:
Property Name | Data Type | Sortable | Description |
start | Integer | Yes | The start time of the trace in milliseconds, displayed in
Universal Time Coordinated (UTC) time |
end | Integer | Yes | The end time of the trace in milliseconds, displayed in UTC time
If the trace is still running, this field displays null . |
expire | Integer | Yes | 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 | Sortable | Description |
totalRows | Integer | Yes | The total number of rows of available data |
swaggerVersion | Integer | Yes | The Swagger version |
time | Integer | Yes | 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 the GET: All Traces List:
- 200 OK- A list of traces was returned back to the client.
- 400 Bad Request- A list of traces could not be returned due to an invalid format for the 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 list of traces could not be found because the user does not have the appropriate authority to view traces.
- 500- Server error
Sample Requests and Responses
Sample 1: Unfiltered Trace Request
The following request queries all SmartTrace trace instances for the NetMaster region:
GET /api/v1/tcpip/U11NDE81/smart/trace
Sample 1: Unfiltered Trace Response
{ "apiVersion": "v1", "data": { "index": 0, "keys": ["id"], "rows": [ { "id": "TH000002DA", "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 } }, { "id": "TH000002DB", "key": { "definitionName": "TSTTRACE", "generation": 341, "sequence": 5, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 1 }, "info": { "type": "STANDARD", "state": "SNAPSHOT", "status": "STOPPED", "packetCount": 250, "totalPacketCount": 1305286 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": 1631820603000, "expire": 1631822402000 } }, { "id": "TH000002DC", "key": { "definitionName": "TSTTRACE", "generation": 342, "sequence": 1, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 1 }, "info": { "type": "STANDARD", "state": "SNAPSHOT", "status": "STOPPED", "packetCount": 250, "totalPacketCount": 1305286 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": 1631820603000, "expire": 1631822402000 } } ], "totalRows": 3 }, "swaggerVersion": "2", "time": 1564754568891 }
Sample 2: Filtered Trace Request:
The following request queries all trace requests for a specific NetMaster region and a single SmartTrace definition, WWFCPCOPY
:
GET /api/v1/tcpip/U22NDE55/smart/trace?definitionName=eq:WWFCPCOPY
Sample 2: Filtered Trace Response:
:
{ "apiVersion": "v1", "data": { "index": 0, "keys": ["id"], "rows": [ { "id": "TH000002DA", "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 } }, { "id": "TH000002DB", "key": { "definitionName": "WWFCPCOPY", "generation": 341, "sequence": 5, "stackName": "TCPIP11", "tcpCreatorSequence": 0, "snapshotSequence": 1 }, "info": { "type": "STANDARD", "state": "SNAPSHOT", "status": "STOPPED", "packetCount": 250, "totalPacketCount": 1305286 }, "checks": { "didEncounterStopCondition": false, "hasSeenIPv6Packets": false, "isCreatorAtLimit": null, "isTcpConversation": false, "isUdpConversation": false }, "ipInfo": null, "timestamps": { "start": 1631817818000, "end": 1631820603000, "expire": 1631822402000 } } ], "totalRows": 2 }, "swaggerVersion": "2", "time": 1564754568891 }