Install Sensor
i. Prerequisites
- Compatibility script (from step 1) indicates the Linux host (that you want to instrument) is compatible.
- Satellite has been successfully installed.
- You have noted down the Satellite's
hostname:port
orip-address:port
information. - The Satellite is reachable (via HTTP/s) from the location where you are going to install the Sensor.
ii. Pick an 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.
Pick a descriptive name which will be used in the subsequent step below. For example: my-test-app
.
iii. Follow instructions for your platform
Follow instructions for your specific platform/method below:
- Install on Kubernetes
- Install on Linux host via Docker
- Install on Debian based Linux Distributions via
apt
- Install on RPM based Linux Distributions via
yum
Install on Kubernetes
Prerequisites
- Kubernetes version >= v1.18.0
- Helm v3 installed and working.
- The Kubernetes cluster API endpoint should be reachable from the machine you are running Helm.
kubectl
access to the cluster, withcluster-admin
permissions.
1. Install levoai Helm repo
helm repo add levoai https://charts.levo.ai && helm repo update
2. Create levoai
namespace & install Sensor
# 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 below the 'Application Name' chosen earlier.
#
helm upgrade levoai-sensor levoai/levoai-ebpf-sensor \
--install \
--namespace levoai \
--create-namespace \
--set sensor.config.default-service-name=<'Application Name' chosen earlier> \
--set sensor.config.collector-traces-endpoint=<hostname|IP:port>
3. Verify connectivity with Satellite
i. Check Sensor health
Check the health of the Sensor by executing the following:
kubectl -n levoai get pods | grep levoai-sensor
If the Sensor is healthy, you should see output similar to below.
levoai-sensor-747fb4aaa9-gv8g9 1/1 Running 0 1m8s
ii. Check connectivity
Execute the following command to check for connectivity health:
# Please specify the actual pod name for levoai-sensor below
kubectl -n levoai logs <levoai-sensor pod name> | grep "Initial connection with Collector"
If connectivity is healthy, you should see output similar to below.
2022/06/13 21:15:40 729071 INFO [ebpf_sensor.cpp->main:120] Initial connection with Collector was successful.
Please contact support@levo.ai
if you notice health/connectivity related errors.
Please proceed to the next step, if there are no errors.
Install on Linux host via Docker
Prerequisites
- Docker Engine version
18.03.0
and above - Admin (or
sudo
) privileges on the Docker host
1. Install Sensor
If you are installing the Satellite and Sensor on the same Linux host, please do NOT use
localhost
as the hostname below. Use the Linux host'sIP address
, ordomain name
instead. This is required as the Sensor runs inside a Docker container, andlocalhost
resolves to the Sensor container's IP address, instead of the Linux host.
# Replace 'hostname|IP' & 'port' with the values you noted down from the Satellite install
#
# Specify below the 'Application Name' chosen earlier. Do not quote the 'Application Name'
#
sudo docker run --restart unless-stopped \
-v /sys/kernel/debug:/sys/kernel/debug -v /proc:/host/proc \
--privileged --detach levoai/ebpf_sensor:latest \
--host-proc-path /host/proc/ \
--collector-traces-endpoint <hostname|IP:port> \
--default-service-name <'Application Name' chosen earlier>
2. Verify connectivity with Satellite
Execute the following command to check for connectivity health:
# Please specify the actual container name for levoai-sensor below
docker logs <levoai-sensor container name> | grep "Initial connection with Collector"
If connectivity is healthy, you should see output similar to below.
2022/06/13 21:15:40 729071 INFO [ebpf_sensor.cpp->main:120] Initial connection with Collector was successful.
Please proceed to the next step, if there are no errors.
Install on Debian based Linux via apt
1. Install curl
and gnupg
sudo apt install gnupg
sudo apt install curl
2. Configure Linux host to access Levo apt repo
curl -fsSL https://us-apt.pkg.dev/doc/repo-signing-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/us-apt-repo-signing-key.gpg
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/us-apt-repo-signing-key.gpg] \
https://us-apt.pkg.dev/projects/levoai apt-levo main" \
| sudo tee -a /etc/apt/sources.list.d/artifact-registry.list > /dev/null
sudo apt update
3. Download/install Sensor artifacts
sudo apt install levo-ebpf-sensor
4. Start the Sensor
Please take a look at the Running the Sensor as a Systemd Service section for further instructions.
Install on RPM based Linux Distributions via yum
1. Configure the package manager
Configure yum
to access Levo's RPM packages using the following command:
sudo tee -a /etc/yum.repos.d/levo.repo << EOF
[levo]
name=Levo.ai
baseurl=https://us-yum.pkg.dev/projects/levoai/yum-levo
enabled=1
repo_gpgcheck=0
gpgcheck=0
EOF
2. Install the eBPF Sensor
Install the eBPF Sensor from Levo's RPM repository.
Update the list of available packages:
sudo yum makecache
Install the package in your repository.
sudo yum install levo-ebpf-sensor
Enter y
when prompted.
3. Start the Sensor
Please take a look at the Running the Sensor as a Systemd Service section for further instructions.
Running the Sensor as a Systemd Service
1. Configure Satellite Address
The Satellite address is configured in /etc/levo/sensor/config.yaml
. The default address for Satellite is https://collector.levo.ai
.
Edit /etc/levo/sensor/config.yaml
, and set collector-traces-endpoint
(under Satellite Settings) to the address noted from the Satellite install.
...
# --------------------------------------------------------------------------------------------
# Satellite Settings:
# --------------------------------------------------------------------------------------------
# host:port for the collector service receiving the sensor's API traces.
collector-traces-endpoint: <set to host:port value noted from the Satellite install>
# --------------------------------------------------------------------------------------------
...
Note: If you change the Satellite address later, you have to restart the Sensor, since it's not a hot property.
If you want to use the default (Levo-hosted) collector address, you must also specify your organization ID in the configuration.
2. Configure Application Name
The Application Name
is configured in /etc/levo/sensor/config.yaml
.
Edit /etc/levo/sensor/config.yaml
, and set default-service-name
to the Application Name
chosen earlier.
# --------------------------------------------------------------------------------------------
# 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.
# --------------------------------------------------------------------------------------------
#
default-service-name: <'Application Name' chosen earlier>
# --------------------------------------------------------------------------------------------
Note: If you change the Application Name
later, you have to restart the Sensor, since it's not a hot property.
3. Start the Sensor
sudo systemctl start levo-ebpf-sensor
4. Verify connectivity with Satellite
sudo journalctl -u levo-ebpf-sensor.service -b -f
# If 'journalctl' isn't tailing logs, use syslog:
sudo cat /var/log/syslog | grep 'levo-ebpf-sensor'
Connection Success
If connectivity is healthy, you should see output similar to below.
2022/06/13 21:15:40 729071 INFO [ebpf_sensor.cpp->main:120] Initial connection with Collector was successful.
Connection Failures
If the Sensor is unable to connect with the Satellite, you will notice log entries similar to the one below. Please contact support@levo.ai
for assistance.
Initial connection with Collector failed. However, the sensor will keep attempting to send future traces.
[OTLP TRACE GRPC Exporter] Export() failed: failed to connect to all addresses
Please proceed to the next step, if there are no errors.
5. Sensor's resource limits
By default, sensor is restricted to use up to 50% of CPU and 2GB memory.
If you ever need to change these limits, you need to modify CPUQuota
and MemoryMax
in the below systemd config file under [Service]
section:
#1. Open the config file /usr/lib/systemd/system/levo-ebpf-sensor.service
and modify CPUQuota
and MemoryMax
sudo vi /usr/lib/systemd/system/levo-ebpf-sensor.service
For example,
If you want to limit sensor's CPU usage to 75% of CPU, then set CPUQuota=75%
.
If you want to limit sensor's memory usage to 3GB, then set MemoryMax=3G
#2. Reload the config
systemctl daemon-reload
#3. Restart the sensor
sudo systemctl restart levo-ebpf-sensor