How hengyoush/kyanos works
Project Type and Purpose
• Kyanos is a systems-level tool that leverages eBPF to capture, analyze, and diagnose network traffic. It supports multiple protocols (HTTP, Redis, MySQL, etc.) and provides in-depth kernel latency details and traffic filtering.
• The tool is launched as a single binary with a CLI interface, and it integrates components such as protocol decoders, connection trackers, kernel-level event handling (via eBPF programs), and a rendering module for display.
File Structure
• Top-Level Components:
• The “agent” directory contains the heart of the logic. Inside it, you find key submodules:
▸ Analysis: Modules for computing statistics, percentiles, and aggregating network metrics.
▸ Buffer: Streaming data buffers for event capture.
▸ Connection (conn): Modules for connection tracking, metrics, and event processors.
▸ Metadata: Modules that collect container, Kubernetes, and process metadata.
▸ Protocol: Extensive code for parsing several network protocols (HTTP, Kafka, MongoDB, MySQL, etc.), including both generic filters and protocol-specific decoders.
▸ Render: UI components that create the “watch” and “stat” views (e.g., detailed latency nodes).
▸ uprobe: Code that handles kernel-level trace points and integrates with the eBPF aspect.
• The “bpf” directory contains source files that represent the in-kernel programs. It includes multiple implementations (for different architectures and kernel versions), a loader for these BPF programs, and related headers and helper scripts.
• “cmd” houses the command-line interface logic (such as watch, stat, top, version commands) driven by the main entry point (main.go).
• “common”, “utils”, and “version” provide supporting libraries and utilities.
• There are additional test data and documentation directories which hint at testing and usage guidelines.
Relationships and Interactions
• The CLI (from “cmd” and main.go) is the user’s starting point. When you execute a command (e.g., “kyanos watch”), the CLI triggers the agent code.
• The agent module performs several key functions:
▸ It loads the appropriate eBPF programs from the “bpf” module using a loader (in bpf/loader). These programs are injected into the kernel to intercept network events.
▸ As network packets and events occur, the kernel (via eBPF) sends data through maps and perf buffers back to userspace.
▸ The “conn” submodule captures connection data and metrics.
▸ The “protocol” submodules (with decoders for HTTP, Kafka, etc.) translate raw packet data into meaningful application-layer information.
▸ The “analysis” subcomponent aggregates latency, response sizes, and other metrics for troubleshooting.
▸ The “render” module then formats and displays this data as live dashboards or detailed record views on the CLI.
▸ The metadata modules enrich captured data with context (container IDs, Kubernetes pod info, etc.).
• Data flow is essentially from kernel (BPF programs) to the agent’s processing pipelines (connection tracking, protocol parsing, analysis) and then to the presentation layer for visualization.
Key Architectural Patterns and Design Principles
• Modular design: Clear separation into components (agent submodules, bpf programs, cmd interface) enables maintainability and easy extensibility (for example, adding a new protocol decoder).
• Low-level kernel integration: Heavy use of eBPF allows capturing events at the kernel level, with a dedicated loader and version-specific code maintained in the “bpf” directory.
• Separation of concerns: There is a clear demarcation between data capture (BPF/agent/conn), protocol-level processing (agent/protocol), analysis (agent/analysis), metadata enrichment (agent/metadata), and presentation (agent/render).
• Lightweight and efficient design: Emphasis on a nearly dependency-free, single-binary executable that interacts directly with system tracing mechanisms.
Technology and Frameworks
• Programming Language: Go (all core logic is in Go).
• eBPF: Deep integration with BPF technology, with various components for different CPU architectures and kernel versions.
• Kernel-level integration and low-level C components for BPF programs.
• The project also utilizes standard tooling for code quality (GitHub workflows, Makefile, go modules) and continuous integration.