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 Data Collection

 

Use the Cloud Analytics Engine CA API flow data resource to start or stop generating application flow path analytics data.

GET start/flow Resource

Use the GET start/flow CA API to instruct CA to generate probes and start collecting information from the network about a flow. You can also use this API to modify the specified data collection parameters for a flow that is already active. This is an asynchronous API.

Request Parameters:

  • Table 1 describes the GET start/flow request parameters, which include the 5-tuple identifying the application flow, and optional parameters specifying what to collect from the available flow data options.

Table 1: GET start/flow Resource Request Parameters

Flow Resource Parameters

Description

dst

(String) Destination IPv4 address for the flow of interest.

Required parameter.

src

(String) Source IPv4 address of the flow of interest.

Required parameter.

proto

(String) Protocol type: “tcp” or “udp”.

Optional parameter. Default is “udp”.

sport

(Numeric) Source port corresponding to the protocol type for the flow.

Optional parameter. Default value is 33434.

dport

(Numeric) Destination port corresponding to the protocol type for the flow.

Optional parameter. Default value is 33434.

sfreq

(Numeric) Sampling frequency for collecting network data (in seconds).

Optional parameter. Default value is 1 second.

nhops

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

Optional parameter. Default value is 255.

ntry

(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.

Optional parameter. Default value is 1 (no retries).

timeout

(Numeric) Timeout (in ms) to wait for the device at a given hop to respond. If the device does not respond within the timeout, any delayed response is ignored by CA.

Optional parameter. Default value is 30000 ms (30 seconds).

chksum

(Boolean) Enable (“true”) or disable (“false”) checksum computation.

Optional parameter. Default value is “true” or enabled.

bw_ingress

(Boolean) If specified as “true”, measure flow bandwidth at each hop ingress.

Optional parameter. Default value is “false”, or do not include bandwidth measurements.

mirror_type

(String) Install mirroring of the indicated type for this flow. Supported mirror type values: “ERSPAN”.

Optional parameter. Default if not specified is no mirror installation.

mirror_dir

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

Optional parameter with no default value. If mirror_type is specified, this parameter must also be specified.

mirror_analyzer

(String) Mirror analyzer IP address.

Optional parameter with no default value. If mirror_type is specified, this parameter must also be specified.

Return Codes:

  • EOK—Request was serviced.

  • EAGAIN—Exceeding pending updates for the same flow. This might happen when the same flow is modified, or there is a previous stop request pending on this flow.

  • EFAIL—Invalid parameters were provided.

  • E_UNAUTHORIZED—Flow was initiated by a different client and cannot be started or modified by the originator of this request.

Response Data:

  • None

See Compute Agent Flow Data Resource Usage Example for a simple example of a request to start a flow with required parameters specifying the 5-tuple that identifies the flow, the same parameters used subsequently to get collected data from that flow, and the same parameters used again to stop the flow.

You can also see these GET data/flow examples that show GET start/flow requests to start a flow with different data collection options, and the response data that is returned:

GET stop/flow Resource

Use the GET stop/flow CA API to instruct CA to stop collecting information from the network about a flow. This is an asynchronous API.

Request Parameters:

  • The GET stop/flow request parameters are the following 5-tuple, which identifies the flow that is active between two endpoints (source and destination):

    • src: (String) Source IPv4 address.

    • dst: (String) Destination IPv4 address.

    • proto: (String, Optional) Protocol type: “tcp” or “udp”. Default is “udp”.

    • sport: (Numeric, Optional) Source port corresponding to the protocol type for the flow. Default value is 33434.

    • dport: (Numeric, Optional) Destination port corresponding to the protocol type for the flow. Default value is 33434.

Return Codes:

  • EOK—A stop signal has been initiated to the flow thread.

  • EFAIL—Invalid parameters were provided.

  • E_UNAUTHORIZED—Flow was initiated by a different client and cannot be stopped by the originator of this request.

  • E_AoF—No such flow.

Response Data:

  • None

See Compute Agent Flow Data Resource Usage Example for a simple example of a request to stop a flow data collection, using the same parameters as the GET start/flow request that started the flow.

Compute Agent Flow Data Resource Usage Example

The following is a simple example of using the flow data resource with the required parameters that specify the flow identifier 5-tuple (src, dst, sport, dport, proto). This example shows the sequence of CA API web requests to the CA server at IP address 10.94.201.11 and port 8080 to start a flow data collection, retrieve collected data from that flow, and stop the flow data collection. All requests use the GET method.

  • Start a flow data collection (GET start/flow):

    http://10.94.201.11:8080/start/flow?dport=9000&src=10.1.1.1&dst=10.1.7.1&sport=4567&proto=tcp

  • Request collected data for the flow (GET data/flow):

    http://10.94.201.11:8080/data/flow?dport=9000&src=10.1.1.1&dst=10.1.7.1&sport=4567&proto=tcp

  • Stop flow data collection (GET stop/flow):

    http://10.94.201.11:8080/stop/flow?dport=9000&src=10.1.1.1&dst=10.1.7.1&sport=4567&proto=tcp