Trace endpoint

Filter traces

A GET to /api/open/traces/all request allows you to get traces matching a condition. You can specify a filter query in the query parameter, which is a standard N2OS query condition, applied to the trace_requests data source. You have to specify the operation parameter defining the requested operation. So far the only allowed value for the operation parameter is download.

Requirements and Restrictions

  1. The authenticated user must be in a group having admin role permission.
  2. As a result you will get a file containing the trace or the traces filtered according to the specified condition.
  3. If the trace is still in progress or it is not found, a 422 error with a proper reason string will be returned.
Figure 1. Example of traces/all request

Example of traces/all request

BPF filter

A GET to /api/open/traces/bpf-filter request allows you to select traces using a Berkeley Packet Filter (BPF) filter. This call returns a job_id, while the actual disk search is performed asynchronously. The search will return a list of the first packet capture (pcap) traces that match the filter. The maximum number of pcap traces is 50 by default and can be configured with the open_api bpf_filter traces_limit setting. There can’t be more than a limited number of concurrent BPF trace searches at a time. This number is 2 by default and can be configured with the open_api bpf_filter max_concurrent_searches setting.

Requirements and Restrictions

  1. The authenticated user must be in a group having admin role permission.
Figure 2. Example of a BPF filter request

Example of a BPF filter request

A GET to /api/open/traces/bpf-filter-status request allows you to get the status of a job in charge of looking for traces given a BPF filter.

Requirements and Restrictions

  1. The authenticated user must be in a group having admin role permission.
  2. You need to specify the id of the job returned by the traces/bpf_filter application programming interface (API) in the id parameter.
  3. The result will contain the status of the job, which can have one of the following values: SUCCESS, PENDING or FAIL.
  4. In case of FAIL status, the error field will report the error reason.
Figure 3. Example of traces/bpf-filter-status request

Example of traces/bpf-filter-status request