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
  • STANDARD (any single connection trace)
  • TCP_CONV (multiple connection trace)
state
String
Yes
The current state of the trace
There are four possible values:
  • ENDED
  • PENDDEL
  • RUNNING
  • SNAPSHOT
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:
  • NONE
  • INITIAL
  • MAIN
  • STOPPED
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:
  • LOCAL
  • REMOTE
  • UNKNOWN
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 }