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