Skip to main content

Manage Sensor Configuration

The Sensor comes pre-configured with appropriate defaults to capture API Traffic (HTTP) from your applications.

The Sensor can be customized via a

Loading...
. Examples of customization include, a) granular filtering of API traffic being captured, b) enabling debugging, c) performance tuning, etc.


Configuration File Format​

The YAML configuration file (shown below) has six major sections: 1) Factory Settings, 2) Default Application Name, 3) Satellite Settings, 4) Process Filters, 5) IP Filters, & 6) URL Filters.

Sensors running on Kubernetes have an additional section called Kubernetes Pod Filters.

##############################################################################################
# eBPF Sensor Configuration Settings (YAML Format)
# Copyright: Levo Inc, 2022
##############################################################################################

# --------------------------------------------------------------------------------------------
# Factory Settings: DO NOT MODIFY
# --------------------------------------------------------------------------------------------

# --------------------------------------------------------------------------------------------

# --------------------------------------------------------------------------------------------
# Default Application Name:
# --------------------------------------------------------------------------------------------
# Auto discovered API endpoints and their OpenAPI specifications are show in the API Catalog
# grouped under this application name. The application name helps segregate and group API
# endpoints from different environments. The environment is used to specify the environment
# that the sensor is installed in (e.g. staging, prod, dev).
#
# In Kubernetes and other container orchestration systems, where meta data about applications
# (that have been deployed) is readily available, auto discovered API endpoints are attributed
# to the appropriate services automatically. The default application will be used as a fallback,
# if the service name meta data in unavailable.
#
default-service-name: my-api-application
env: staging
# --------------------------------------------------------------------------------------------


# --------------------------------------------------------------------------------------------
# Satellite Settings:
# --------------------------------------------------------------------------------------------

# Levo Organization ID. This must be specified when the collector is hosted by Levo.
# organization-id: ""

# Use HTTP/2 (gRPC) for communication with the collector. If this is disabled, HTTP/1.1 will be used.
collector-grpc-transport: true

# host:port for the collector service receiving the Sensor's API traces and metrics.
collector-endpoint: https://collector.levo.ai

# --------------------------------------------------------------------------------------------


# --------------------------------------------------------------------------------------------
# API Trace Export Rate Limiting:
# --------------------------------------------------------------------------------------------
# By default, the sensor rate-limits the overall number of request-response traces it exports
# to the satellite.  It also rate-limits traces on a per-endpoint basis.  Rate limiting can
# be disabled or adjusted, but doing so may affect the performance of downstream Levo
# services.

# enable-export-rate-limiting: true
# max-total-exported-requests-per-second: 200
# max-per-endpoint-exported-requests-per-second: 20

# --------------------------------------------------------------------------------------------

# --------------------------------------------------------------------------------------------
# Metrics Settings:
# --------------------------------------------------------------------------------------------
# Uncomment and modify to enable the printing of sensor metrics alongside other sensor logging
# messages.

# export-metrics-to-log: true
enable-metrics: true

# --------------------------------------------------------------------------------------------
# Process Filters: process command names/IDs to monitor & capture API traffic.
# --------------------------------------------------------------------------------------------
## Restrict API traffic capture to specific processes identified by their command names below
monitored-commands:
#  - <process command name. Example: nginx>
#  - <process command name. Example: python3>

## Restrict API traffic capture to specific processes identified by their PIDs below
monitored-pids:
- <pid. Example: 123>
- <pid. Example: 45>
# --------------------------------------------------------------------------------------------


# --------------------------------------------------------------------------------------------
# IP Filters: IP/Port/Network address based granular filtering of API traffic.
# --------------------------------------------------------------------------------------------
ip-filter-list:
  default-policy: <accept|drop> # Specifies default behavior which can be overridden by 'entries' below
  entries: # Specific 'entries' can override the default policy
    - policy: <accept|drop>
      <host-ports|peer-ports|host-network|peer-network>: <appropriate value>
# --------------------------------------------------------------------------------------------


# --------------------------------------------------------------------------------------------
# URL Filters: API parameter based granular filtering of API traffic.
# --------------------------------------------------------------------------------------------
url-filter:
  # 'default-url-action' specifies the default behavior which can be overridden by 'rules' below.
  # This is a mandatory attribute that needs to be specified in order to use URL filters.
  default-url-action: <trace|ignore>
  #
  # YAML array of one or more rules. Order of rules matters during evaluation
  rules:
    # 'action' is mandatory. At least one of 'methods', or 'request-uri', or 'host'
    # MUST be specified for each rule entry
    - action: <trace|ignore>
      #
      # YAML array list of one or more (API operations) methods: GET, POST, PUT, DELETE
      # Example: [GET], or [GET, POST, PUT, DELETE]
      methods: <[GET, POST, PUT, DELETE]>
      #
      # URI of the API endpoint. Can be a (Perl format) regex pattern. Example: /foo/bar, or /bar/*
      request-uri: <URI>
      #
      # Hostname of the API endpoint and optionally the port. Example: levo.ai:8888, or levo.ai
      host: <hostname[:port]>
      #
# --------------------------------------------------------------------------------------------

# --------------------------------------------------------------------------------------------
# Kubernetes Pod Filters: Kubernetes pod properties based granular filtering of API traffic.
# --------------------------------------------------------------------------------------------
# Pod Filters enable granular capture of API traffic based on Kubernetes Pod attributes.
# Rules should ideally be in decreasing order of specificity.
# The first rule to match a pod's properties will be used.
#
# --------------------------------------------------------------------------------------------
#
k8s-pod-filter-list:
  default-policy: <trace|ignore>
  rules:
    - policy: <trace|ignore>
      namespace: <name or regex pattern>
      # Optional owner reference of the Pod
      owner-reference:
        kind: <Node|Deployment>
        name: <name or regex pattern>
# --------------------------------------------------------------------------------------------

Factory Settings​

These settings control logging, debugging, and performance tuning functions. DO NOT modify these settings, unless specifically asked by Levo Support.

HTTP/HTTPS Proxy​

You may configure an HTTP/HTTPS proxy for requests made by the Sensor to the Satellite, e.g.

http-proxy: "http://your-proxy:8080" # Proxy used for HTTP requests
https-proxy: "http://your-proxy:8080" # Proxy used for HTTPS requests

Default Application Name​

Auto discovered API endpoints and their OpenAPI specifications are show in the API Catalog, grouped under an application name. The application name helps segregate and group API endpoints from different environments, similar to how file folders work in an operating system.


Satellite Settings​

These are settings related to the Satellite, such as the Satellite's listen port, etc.


API Trace Export Rate Limiting​

The sensor allows rate limiting the overall number of traces it exports to the satellite (max-total-exported-requests-per-second).

Rate limiting may also be done on a per-endpoint basis (max-per-endpoint-exported-requests-per-second).

Rate limiting is optional and may be toggled with the enable-export-rate-limiting setting.

The default values for these settings are listed below.

enable-export-rate-limiting: true
max-total-exported-requests-per-second: 200
max-per-endpoint-exported-requests-per-second: 20

Process & IP Filters​

These settings allow granular control over what API traffic is captured by the Sensor. Please see detailed section on API Traffic Capture Filters.


URL Filters​

These settings allow granular control over what API traffic is captured by the Sensor, based on API parameter filters. Please see detailed section on API Traffic Capture Filters.


Kubernetes Pod Filters​

These settings allow granular control over what API traffic is captured by the Sensor, based on Kubernetes meta data (e.g. namespace name, deployment name, etc).

Please see detailed section on API Traffic Capture Filters.


Applying Configuration Settings​

Running on Kubernetes​

Configuration is specified via a Helm Values file.

  • Modify the default
    Loading...
    file to suit your requirements.
  • Save the configuration values file to your current working directory.
  • Note down the Satellite's host:port address information.
  • Apply the new configuration by executing the below command from the directory where you saved the config-values.yml.
# Replace 'hostname|IP' & 'port' with the values you noted down from the Satellite install
# If Sensor is installed on same cluster as Satellite, use 'levoai-collector.levoai:4317'
#
# Specify the 'Application Name' chosen earlier in the config-values.yml file.
#
helm upgrade levoai-sensor levoai/levoai-ebpf-sensor \
  --install \
  --namespace levoai \
  --create-namespace \
  --set sensor.otel.grpcEndpoint=<hostname|IP:port> \
  --values config-values.yml

You may also specify specific configuration values using helm --set. For example,

helm upgrade levoai-sensor levoai/levoai-ebpf-sensor \
  --install \
  --namespace levoai \
  --create-namespace \
  --set sensor.config.default-service-name="my-test-app-k8s-c101" \
  --set "sensor.config.monitored-commands={python3,java}"

Please check the Sensor logs to ensure that the specified configuration values do not have any syntax errors, and the Sensor is running with the applied configuration.

Running via Docker​

  • Modify the default
    Loading...
    to suit your requirements.
  • Save the configuration file to your current working directory.
  • Shutdown/Uninstall the Sensor if running.
  • Note down the Satellite's host:port address information.
  • Reinstall the Sensor by executing the below command from the directory where you saved config.yml. config.yml is mounted into the Sensor container as read only.
# Replace 'hostname|IP' & 'port' with the values you noted down from the Satellite install
sudo docker run --restart unless-stopped \
  -v /sys/kernel/debug:/sys/kernel/debug -v /proc:/host/proc \
  -v $PWD/config.yml:/etc/levo/sensor/config.yaml:ro \
  --privileged --detach \
  levoai/ebpf_sensor:latest \
  --host-proc-path /host/proc \
  --collector-endpoint <hostname|IP:port> \
  --default-service-name <'Application Name' chosen earlier>

Please check the Sensor logs to ensure the configuration file does not have any syntax errors, and the Sensor is running with the applied configuration.

Running on Linux Host​

Make your modifications to /etc/levo/sensor/config.yaml and save the file. Restart the sensor for the settings to take effect.

Please check the Sensor logs to ensure the configuration file does not have any syntax errors, and the Sensor is running with the applied configuration.