Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Starting and Stopping a Flow Path Trace

 

Use the DLE application flow path trace APIs as follows to:

  • Start a trace of an application flow path, with or without encapsulation (VXLAN tunnel), by providing the corresponding request parameters.

  • Subsequently stop an active trace for the specified trace ID.

POST /api/v1/traces

Use this DLE API request to create a trace of a non-overlay or overlay (tunnel) flow data collection.

Request Format:

  • POST method.

  • Content-Type:Application/JSON for the request body.

Request Parameters:

  • tunnel: (Boolean) Specify tunnel=false for non-overlay flow trace creation, or tunnel=true for overlay (tunnel) flow data collection. Default is false if this parameter is not specified.

Request Body (JSON format):

Response Data:

  • If the collection was successfully created:

    • Unique trace ID of the created flow or tunnel trace.

    • Corresponding URI for retrieving trace data for that trace ID.

TraceConfig Transfer Object

Table 1 describes the TraceConfig transfer object that provides the parameters when instructing DLE to create a flow data trace collection (see POST /api/v1/traces). The TunnelConfig Transfer Object contains the same elements with additional tunnel identification elements for creating a tunnel trace collection.

Table 1: TraceConfig Transfer Object

Element Name

Data Type

source

(String) Source IPv4 address of the flow path emulation you want to start tracing.

Required parameter.

destination

(String) Destination IPv4 address of the flow being traced.

Required parameter.

destinationPort

(Numeric) Application destination port for the flow.

Required parameter.

sourcePort

(Numeric) Application source port for the flow.

Required parameter.

startTime

(Numeric) Scheduled time to start the trace (epoch time in ms), if a future time is specified. If not specified (default behavior), or the specified time is in the past, DLE starts the trace immediately upon receipt of the request.

endTime

(Numeric) Scheduled time to end the trace (epoch time in ms). If not specified, the default value is 0, which indicates the trace should run until it is manually stopped (see PUT /api/v1/traces/{traceId}).

protocol

(String) Protocol type for the flow to be traced (“udp” or “tcp”).

Required parameter.

hops

(Numeric) Number of network hops on the flow path for which to collect data. Data is gathered across all hops until the destination (<=255) if this parameter is not specified.

retries

(Numeric) Number of tries to attempt in case of a timeout on a given hop. If this parameter is not specified, only a single attempt is made to gather data for the hop.

collectionFreq

(Numeric) Sampling frequency in seconds for collecting network data. Default value if not specified is 1 second.

timeouts

(Numeric) Time to wait in ms for the device at any hop in the traced flow path to respond. Delayed responses that fall outside this timeout value are ignored.

checksum

(Boolean) Enable (“true”) or disable (“false”) checksum computation. Default value is “true” or enabled.

collectBandwidthIngress

(Boolean) If specified as “true”, trace flow bandwidth at each hop ingress. Default value is “false” or disabled.

mirrorType

(String) Install mirroring of the indicated type for this flow. Supported mirror type values: “ERSPAN”. Default if not specified is no mirror installation.

mirrorDirection

(String) Mirror direction. Supported values: “ingress”.

mirrorAnalyzer

(String) Mirror analyzer IP address. No default value. If mirrorType is specified, this parameter must also be specified.

TunnelConfig Transfer Object

The TunnelConfig transfer object contains the same elements as the TraceConfig Transfer Object with the additional elements described in Table 2. The data in this object provides the tunnel details when instructing DLE to create an encapsulated flow data trace collection (see POST /api/v1/traces).

Table 2: TunnelConfig Transfer Object

Element Name

Description

All elements from TraceConfig Transfer Object, plus the elements in this table.

encapsulation

(String) Encapsulation type for tracing a tunnel flow. Supported values: “VXLAN”.

Note: For tunnel flow traces, DLE and CA assume VXLAN encapsulation by default, so this parameter is optional.

sourceVTEP

(String) VTEP source IPv4 address.

Required parameter.

destinationVTEP

(String) VTEP destination IPv4 address.

Required parameter.

vnid

(Numeric) VXLAN network identifier.

Required parameter.

sourceVTEPPort

(String) Source VTEP port number (represented as a string in this data object, rather than a numeric value).

destinationVTEPPort

(String) Destination VTEP port number (represented as a string in this data object, rather than a numeric value).

mcastGroupAddress

(String) Overlay network multicast group address.

Required parameter.

Trace Creation Data Learning Engine API Example

The following is a DLE API example for creating a trace data collection. See POST /api/v1/traces for more details.

Request:

http://192.168.55.102:8282/api/v1/traces

  • POST method

  • Content-Type set to Application/JSON

Request body:

PUT /api/v1/traces/{traceId}

Use this DLE API request to stop a DLE trace data collection for the specified trace ID.

Request Format:

  • PUT method.

Request Parameters:

  • None

Response Data:

  • HttpResponse status indicating success or failure reason.