# hengyoush/kyanos architecture

> Architecture diagram of the GitHub repository hengyoush/kyanos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hengyoush/kyanos
- Repository: https://github.com/hengyoush/kyanos

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI/Entry (main.go, cmd)"]:::cli
    end

    %% Agent Core Layer
    subgraph "Agent Core"
        subgraph "Data Capture"
            CT["Connection Tracking"]:::agent
            KP["Kernel Trace Points"]:::agent
            SB["Streaming Data Buffer"]:::agent
        end
        PD["Protocol Decoding"]:::agent
        AE["Analysis Engine"]:::agent
        ME["Metadata Enrichment"]:::agent
        R["Rendering/UI"]:::agent
    end

    %% Kernel/BPF Layer
    subgraph "Kernel/BPF Layer"
        BL["eBPF Programs & Loader"]:::kernel
    end

    %% Data Flow Connections
    CLI -->|"triggers"| CT
    CLI -->|"triggers"| KP
    CLI -->|"triggers"| SB
    CLI -->|"loads"| BL
    BL -->|"captures"| CT
    BL -->|"captures"| KP
    CT -->|"sends_data"| PD
    KP -->|"sends_events"| PD
    SB -->|"buffers"| PD
    PD -->|"decodes"| AE
    AE -->|"aggregates"| ME
    ME -->|"enriches"| R
    R -->|"displays"| CLI

    %% Click Events
    click CLI "https://github.com/hengyoush/kyanos/blob/main/main.go"
    click CT "https://github.com/hengyoush/kyanos/tree/main/agent/conn"
    click KP "https://github.com/hengyoush/kyanos/tree/main/agent/uprobe"
    click SB "https://github.com/hengyoush/kyanos/tree/main/agent/buffer"
    click PD "https://github.com/hengyoush/kyanos/tree/main/agent/protocol"
    click AE "https://github.com/hengyoush/kyanos/tree/main/agent/analysis"
    click ME "https://github.com/hengyoush/kyanos/tree/main/agent/metadata"
    click R "https://github.com/hengyoush/kyanos/tree/main/agent/render"
    click BL "https://github.com/hengyoush/kyanos/tree/main/bpf"

    %% Styles
    classDef cli fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef agent fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef kernel fill:#ffa07a,stroke:#000,stroke-width:2px;
```
