Aquila

Aquila is a lightweight telemetry framework that emphasizes efficiency, reliability, and semantic fidelity for Kubernetes container monitoring using eBPF technology.

Features

• eBPF-based Monitoring: High-performance system call tracing using eBPF
• Kubernetes Integration: Native support for Kubernetes container monitoring
• Container Runtime Support: Compatible with containerd and other CRI-compatible runtimes
• Namespace Filtering: Monitor specific namespaces or exclude system namespaces
• Flexible Export: Export telemetry data to stdout, files or gRPC
• Low Overhead: Minimal performance impact on monitored workloads
• Configurable Logging: Multiple log levels and output destinations

Deployment

Prerequisites

• Linux kernel 5.4+ (with eBPF support)
• Kubernetes cluster (for Kubernetes monitoring)
• Root privileges (required for eBPF operations)

Kubernetes Deployment

• Deploy Aquila as a DaemonSet in your Kubernetes cluster:

  kubectl apply -f deployments/aquila.yaml

Local Installation

Prerequisites

• Linux kernel 5.4+ (with eBPF support)
• Go 1.24.0+
• Clang 14+
• LLVM 14+
• Kubernetes cluster (for Kubernetes monitoring)
• Root privileges (required for eBPF operations)

Install Dependencies

make install-tools

Build Aquila

make clean # to remove pre-compiled BPF code
make       # to compile Aquila and its BPF code for syscall monitoring

Run Aquila on the host (not container)

make run   # sudo -E ./aquila --exceptNS=kube-system,kube-flannel

Command-line Arguments

Argument	Default	Description
--cluster	default	Kubernetes cluster identifier
--node	$(hostname)	Kubernetes node identifier
--procDir	/proc	Path to the /proc directory
--coverage	k8s	Coverage to monitor (k8s, all)
--rawSyscalls	false	Whether to include raw syscalls
--targetNS	""	Target namespaces to monitor (comma-separated)
--exceptNS	""	Namespaces to exclude from monitoring (comma-separated)
--logLevel	info	Logging verbosity level (debug, info, warn, error)
--logPath	stdout	Log output destination (file path or stdout)
--exportWorkers	1	Number of workers for exporting events
--exportPath	stdout	Path to store exported events (file path or stdout)

Usage Examples

• Basic Monitoring

  Monitor all Kubernetes containers (excluding system namespaces):

  sudo -E ./aquila --exceptNS=kube-system,kube-flannel

• Targeted Monitoring

  Monitor only specific namespaces (e.g., default namespace):

  sudo -E ./aquila --targetNS=default

• Raw System Call Monitoring

  Enable raw system call tracing:

  sudo -E ./aquila --rawSyscalls=true

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Copyright 2025 BoanLab @ DKU