# tracer

**Repository Path**: Elams/tracer

## Basic Information

- **Project Name**: tracer
- **Description**: A comprehensive CLI tool for Linux system troubleshooting and diagnostics.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tracer

A comprehensive CLI tool for Linux system troubleshooting and diagnostics.

## Overview

`tracer` is a single-binary command-line tool designed for Linux system administrators and SREs to diagnose and troubleshoot 80% of common system-level issues. It provides read-only access to system information without requiring agents or external services.

## Features

- **Single Binary**: No dependencies, easy to deploy
- **Read-Only**: Safe to run, never modifies system state
- **Root & Non-Root**: Works with different privilege levels
- **Dual Output**: Human-readable text and structured JSON
- **Multi-Distro**: Supports Ubuntu 18.04+, CentOS/RHEL 7+, and generic Linux
- **AI Assistant**: AI-powered troubleshooting with Coze and Dify integration
- **Host Information**: Comprehensive host details collection (hostname, OS, kernel, CPU, memory)
- **Enhanced Service Management**: Failed, crashed, and slow startup service detection
- **Advanced Network Analysis**: Interface status, IP addresses, routing, DNS, and TCP stats
- **Detailed Memory Information**: Includes slab, hugepages, and swap analysis
- **Comprehensive Log Analysis**: Issue detection, keyword search, and log entry viewing

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        tracer CLI                            │
│                    (Single Binary)                           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼─────────────────────────────┐
│                             │                               │
┌─────────────────────────────▼─────────────────────────────┐
│                    Command Layer (Cobra)                    │
│  sys | cpu | mem | disk | net | proc | svc | log | time | hw │
│                 | ai | host-info                           │
└─────────────────────────────┬─────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────┐
│                   Collector Layer                          │
│  ProcFS | SysFS | Files | Network Readers | Host Info      │
└─────────────────────────────┬─────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────┐
│                   Platform Layer                           │
│  Ubuntu | CentOS/RHEL | Generic Adapters                   │
└─────────────────────────────┬─────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────┐
│                   Agent Layer                              │
│  Coze | Dify AI Integrations                               │
└─────────────────────────────┬─────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────┐
│                   Output Layer                             │
│  Human Formatter | JSON Formatter                          │
└─────────────────────────────────────────────────────────────┘
```

## Project Structure

```
tracer/
├── cmd/
│   └── tracer/              # Main entry point
│       └── main.go
├── internal/
│   ├── cmd/                 # Command implementations
│   │   ├── sys/
│   │   ├── cpu/
│   │   ├── mem/
│   │   ├── disk/
│   │   ├── net/
│   │   ├── proc/
│   │   ├── svc/
│   │   ├── log/
│   │   ├── time/
│   │   ├── hw/
│   │   ├── ai/              # AI assistant commands
│   │   └── hostinfo/        # Host information command
│   ├── collector/           # Data collectors
│   │   ├── sys/
│   │   ├── cpu/
│   │   ├── mem/
│   │   ├── disk/
│   │   ├── net/
│   │   ├── proc/
│   │   ├── svc/
│   │   ├── log/
│   │   ├── time/
│   │   └── hw/
│   ├── hostinfo/            # Host information collection
│   ├── agent/               # AI agent integration
│   ├── model/               # Data models
│   ├── output/              # Output formatters
│   ├── constants/           # Constants
│   └── platform/            # Platform adapters
│       ├── ubuntu/
│       ├── centos/
│       └── generic/
├── pkg/                     # Reusable packages
│   ├── procfs/              # ProcFS utilities
│   ├── sysfs/               # SysFS utilities
│   ├── reader/              # File readers
│   └── utils/               # Common utilities
├── test/
│   ├── unit/                # Unit tests
│   └── integration/         # Integration tests
├── scripts/                 # Build and deployment scripts
└── docs/                    # Documentation
```

## Commands

### System Overview
- `tracer sys info` - System information (distro, kernel, uptime)
- `tracer sys load` - System load averages
- `tracer sys health` - System health check

### CPU
- `tracer cpu info` - CPU details (model, cores, frequency)
- `tracer cpu usage` - CPU usage statistics
- `tracer cpu top` - Top CPU processes
- `tracer cpu governor` - CPU frequency governor status

### Memory
- `tracer mem info` - Memory information (total, available, cached, slab, hugepages)
- `tracer mem usage` - Memory usage statistics
- `tracer mem top` - Top memory processes
- `tracer mem swap` - Swap information

### Disk
- `tracer disk info` - Disk information (devices, size, type)
- `tracer disk usage` - Disk usage (df)
- `tracer disk io` - Disk I/O statistics
- `tracer disk mount` - Mount point information

### Network
- `tracer net info` - Network information (interfaces, IP, routes, DNS, TCP stats)
- `tracer net interface` - Network interface status
- `tracer net ip` - IP addresses
- `tracer net route` - Routing table
- `tracer net dns` - DNS configuration
- `tracer net tcp` - TCP connection statistics

### Process
- `tracer proc list` - Process list
- `tracer proc info <pid>` - Process details
- `tracer proc fd <pid>` - Open file descriptors
- `tracer proc env <pid>` - Environment variables
- `tracer proc tree` - Process tree

### Services
- `tracer svc info` - Show all service information
- `tracer svc status [service-name]` - Show service status
- `tracer svc failed` - Show failed services
- `tracer svc crashed` - Show recently crashed services
- `tracer svc slow` - Show slow startup services
- `tracer svc logs [service-name]` - Show service logs

### Logs
- `tracer log info` - Show log analysis summary
- `tracer log issues` - Show detected log issues
- `tracer log search [keyword]` - Search logs for keyword
- `tracer log entries` - Show log entries
- `tracer log grep <keyword>` - Grep logs for keyword

### Time
- `tracer time now` - Current time
- `tracer time ntp` - NTP sync status
- `tracer time timezone` - Timezone information

### Hardware
- `tracer hw cpu` - CPU hardware details
- `tracer hw mem` - Memory hardware details
- `tracer hw disk` - Disk hardware details
- `tracer hw nic` - Network interface hardware details

### Host Information
- `tracer host-info` - Host basic information (hostname, OS, kernel, CPU, memory)

### AI Assistant
- `tracer ai ask <question>` - Ask a question to AI agent
- `tracer ai` - AI-powered troubleshooting assistance (supports chat mode)
  - `--chat` - Enable chat mode (only for Coze agent)
  - `--with-host-info` - Include host information in AI request
  - `--stream` - Enable streaming output
  - `--config <path>` - Path to agent config file
  - `--agent <name>` - Agent name to use
  - `--debug` - Debug mode (show raw responses)

## Global Options

- `--output json|text` - Output format (default: text)
- `--quiet` - Quiet mode, only show key information
- `--watch <seconds>` - Continuous monitoring mode
- `--no-color` - Disable colored output
- `--version` - Show version information
- `--help` - Show help information

## AI Agent Configuration

To use the AI assistant feature, you need to create a configuration file at `~/.tracer/config.yaml`:

```yaml
agents:
  coze:
    type: coze
    name: coze
    endpoint: https://api.coze.cn/v1/chat
    workflow_id: your_workflow_id
    bot_id: your_bot_id  # Required for chat mode
    timeout: 60
  dify:
    type: dify
    name: dify
    endpoint: https://api.dify.ai/v1/chat
    workflow_id: your_workflow_id
    timeout: 60

context:
  max_diagnose_input_length: 10000

debug: false
```

### Supported AI Agent Types
- **coze**: Coze AI platform (supports chat mode)
- **dify**: Dify AI platform

## Host Information Collection

The `host-info` command collects comprehensive host details including:
- Hostname
- Host type (physical, virtual, container)
- OS distribution and version
- Kernel version
- Architecture
- System uptime
- CPU model and core count
- Total memory

## Usage Examples

```bash
# Get system overview
tracer sys info

# Check CPU usage with JSON output
tracer cpu usage --output json

# Monitor disk I/O every 5 seconds
tracer disk io --watch 5

# List failed services
tracer svc failed

# Check process details
tracer proc info 1234

# View listening ports
tracer net listen

# Get host information
tracer host-info

# Get host information in JSON format
tracer host-info --output json

# Ask AI agent about system issues
tracer ai ask "Why is my system slow?"

# Ask AI agent with host information included
tracer ai ask "Why is my system slow?" --with-host-info

# Start AI chat mode
tracer ai --chat --agent coze

# Use AI agent with streaming output
tracer ai ask "How to optimize my system?" --stream
```

## Building

```bash
# Build for Linux
make build

# Build for multiple platforms
make build-all

# Run tests
make test
```

## Supported Distributions

- Ubuntu 18.04+
- CentOS / RHEL 7+
- Other distributions (with generic fallback)

## License

MIT License