Skip to content

AGENTS.md

Latest commit

 

History

History
246 lines (180 loc) · 6.77 KB

AGENTS.md

File metadata and controls

246 lines (180 loc) · 6.77 KB
Raw

Kyanos AGENTS.md

This file provides AI agents with project background, structure, coding conventions, and workflow information.

Project Overview

Kyanos is an eBPF-based network troubleshooting tool for capturing and analyzing network requests (HTTP, Redis, MySQL, etc.), helping to quickly diagnose network-related issues such as slow queries, high traffic, and anomalies.

Core Features

  1. Traffic Filtering: Multi-dimensional filtering by process/container, L7 protocol, request/response size, latency, etc.
  2. Traffic Analysis: Aggregated metrics for rapid issue identification (e.g., finding largest responses when bandwidth is saturated)
  3. Kernel-level Latency Details: Visual representation of packet journey from NIC to socket buffer
  4. Automatic SSL Decryption: Automatic HTTPS traffic decryption to plaintext
  5. Zero Dependencies: Single binary file with command-line interface

Technology Stack

  • Language: Go 1.23+
  • Kernel Technology: eBPF (using cilium/ebpf library)
  • UI: Charmbracelet ecosystem (Bubble Tea, Bubbles, Lipgloss)
  • CLI: Cobra + Viper
  • Supported Protocols: HTTP, Redis, MySQL, Kafka, MongoDB, RocketMQ, DNS

Project Structure

kyanos/
├── main.go                 # Entry point, calls cmd.Execute()
├── go.mod                  # Go dependency management
├── Makefile               # Build scripts
├── bpf/                   # eBPF C programs and headers
│   ├── pktlatency.bpf.c   # Main eBPF program
│   ├── openssl_*.bpf.c    # OpenSSL uprobes for various versions
│   ├── gotls.bpf.c        # Go TLS uprobe
│   ├── *.h                # BPF header files
│   └── loader/            # BPF loader (Go)
├── cmd/                   # CLI command definitions
│   ├── root.go            # Root command and global flags
│   ├── watch.go           # watch subcommand
│   ├── stat.go            # stat subcommand
│   └── *.go               # Other protocol commands
├── agent/                 # Core Agent logic
│   ├── agent.go           # Agent startup and main loop
│   ├── conn/              # Connection management, event handling
│   ├── protocol/          # Protocol parsers
│   ├── analysis/          # Traffic analysis
│   ├── render/            # UI rendering
│   └── metadata/          # Container/K8s metadata
├── common/                # Shared utilities and types
│   ├── log.go             # Logging system
│   ├── utils.go           # General utilities
│   └── *.go
├── version/               # Version information
├── vmlinux/               # vmlinux.h for different architectures
├── libbpf/                # libbpf submodule
└── docs/                  # Documentation

Build System

Dependencies

  • Go: 1.23+
  • Clang: 10.0+
  • LLVM: 10.0+
  • Linux Headers: linux-tools-common, linux-tools-generic
  • Others: pkgconf, libelf-dev

Common Build Commands

# Development build (local testing)
make build-bpf && make

# Full build with BTF (for older kernels)
make build-bpf && make btfgen BUILD_ARCH=x86_64 ARCH_BPF_NAME=x86 && make

# Debug build
make kyanos-debug

# Run tests
make test

# Format code
make format

BPF Code Generation

The project uses go generate to generate BPF skeleton code:

# Defined in bpf/loader/loader.go
//go:generate go run github.com/cilium/ebpf/cmd/bpf2go ...

TARGET=amd64 go generate ./bpf/  # x86_64
TARGET=arm64 go generate ./bpf/  # arm64

Coding Conventions

Go Style Guidelines

  1. Package Naming: All lowercase, short and meaningful, avoid underscores
  2. File Naming: All lowercase, use underscores for separation, e.g., kern_event_handler.go
  3. Interface Naming: Verb + Noun, e.g., ProtocolStreamParser
  4. Error Handling: Explicit handling, use common.DefaultLog for logging
  5. Logging: Use dedicated loggers like common.AgentLog, common.BPFLog

Key Patterns

Agent Startup Flow

// agent/agent.go: SetupAgent()
1. Check BPF permissions (CAP_BPF)
2. Initialize ConnManager
3. Initialize ProcessorManager
4. Load BPF programs (loader.LoadBPF)
5. Start event pulling goroutines
6. Start rendering UI

Protocol Parser

// agent/protocol/protocol.go

// Implement ProtocolStreamParser interface
type ProtocolStreamParser interface {
    Match(reqStreams, respStreams) []Record
    FindBoundary(streamBuffer, messageType, startPos) int
    ParseRequest(streamBuffer, messageType) *ParsedMessage
    // ...
}

// Register parser
func init() {
    ParsersMap[bpf.AgentTrafficProtocolTKProtocolXXX] = func() ProtocolStreamParser {
        return &XXXStreamParser{}
    }
}

eBPF Map Definition

// bpf/pktlatency.bpf.c
struct {
    __uint(type, BPF_MAP_TYPE_HASH);
    __uint(key_size, sizeof(struct sock_key));
    __uint(value_size, sizeof(struct conn_id_s_t));
    __uint(max_entries, 65535);
} sock_key_conn_id_map SEC(".maps");

Testing

Test Structure

agent/
├── agent_test.go              # Agent tests
├── agent_utils_test.go        # Utility tests
└── protocol/
    └── http_test.go           # Protocol parser tests

Running Tests

# All tests
go test -v ./...

# Specific package tests
go test -v ./agent/...

# Benchmark tests
go test -bench=. ./...

Troubleshooting

1. BPF Loading Failed

  • Check kernel version (requires 3.10.0-957+ or 4.14+)
  • Check if BTF is enabled: zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
  • Use --btf flag to specify external BTF file

2. Container-related Features Not Working

  • Ensure access to Docker/Containerd/CRI
  • Use --docker-address, --containerd-address to specify endpoints

3. SSL Decryption Failed

  • Check if OpenSSL version is supported
  • Ensure the process has ptrace permissions

Contributing

Adding New Protocol Support

  1. Add protocol detection logic in bpf/protocol_inference.h
  2. Create parser in agent/protocol/ implementing ProtocolStreamParser
  3. Add corresponding subcommand in cmd/
  4. Add test cases

Modifying BPF Code

  1. Modify .c or .h files
  2. Run make build-bpf to regenerate skeleton code
  3. Test and verify

Resources

Related Projects

Kyanos development was inspired by the following projects: