🦝 gcp-racoon

GCP Log Spy with Gemini AI

A powerful terminal UI for streaming, querying, and analyzing Google Cloud Platform logs with Gemini powered insights.

✨ Features

• 🔴 Real-time Log Streaming - Watch logs as they happen with a beautiful TUI
• 🔍 Powerful Querying - Use GCP filter syntax or natural language
• 🤖 AI-Powered Analysis - Explain errors, generate queries, answer questions about your logs
• 📁 Offline Mode - Export logs and analyze them later without internet
• 🎨 Themeable - Dark and light themes for comfortable viewing
• ⌨️ Vim-style Navigation - Efficient keyboard-driven interface
• 🔒 Secure - Uses your existing GCP credentials

📦 Installation

From Binary (Recommended)

Download the latest release for your platform:

# macOS (Apple Silicon)
curl -L https://github.com/Staninbui/racoon/releases/latest/download/gcp-racoon-aarch64-apple-darwin.tar.gz | tar xz
sudo mv gcp-racoon /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/Staninbui/racoon/releases/latest/download/gcp-racoon-x86_64-apple-darwin.tar.gz | tar xz
sudo mv gcp-racoon /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/Staninbui/racoon/releases/latest/download/gcp-racoon-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv gcp-racoon /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/Staninbui/racoon/releases/latest/download/gcp-racoon-x86_64-pc-windows-msvc.zip -OutFile gcp-racoon.zip
Expand-Archive gcp-racoon.zip -DestinationPath .
Move-Item gcp-racoon.exe C:\Windows\System32\

From Source

# Clone the repository
git clone https://github.com/Staninbui/racoon.git
cd racoon

# Build and install
cargo install --path .

Using Cargo

cargo install gcp-racoon

Using Docker

# Pull the image
docker pull ghcr.io/staninbui/gcp-racoon:latest

# Run directly
docker run --rm -it \
    -v ~/.config/gcloud:/root/.config/gcloud:ro \
    -e GEMINI_API_KEY \
    ghcr.io/staninbui/gcp-racoon tail --project my-project

# Create an alias for convenience
alias racoon='docker run --rm -it \
    -v ~/.config/gcloud:/root/.config/gcloud:ro \
    -v ~/.config/racoon:/root/.config/racoon:ro \
    -e GEMINI_API_KEY \
    ghcr.io/staninbui/gcp-racoon'

# Now use like a normal command
racoon --help

Using Homebrew (macOS/Linux)

# Coming soon
# brew tap staninbui/tap
# brew install gcp-racoon

🚀 Quick Start

1. Authenticate with GCP

Racoon uses your existing GCP credentials. Make sure you're authenticated:

# Using gcloud
gcloud auth application-default login

# Or set service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

2. Set up AI (Optional)

For AI features, set your Gemini API key:

export GEMINI_API_KEY=your-api-key-here

Or add to config file (~/.config/racoon/config.toml):

[ai]
api_key = "your-api-key-here"

3. Start Using Racoon

# Stream logs in real-time
racoon tail --project your-project-id

# Query logs
racoon query --project your-project-id --filter 'severity>=ERROR'

# List projects
racoon projects

# Check authentication
racoon auth

📖 Usage

Commands

Tail Mode (TUI)

racoon tail --project my-project --since 1h --severity WARNING

Keyboard Shortcuts

Query Mode

# Basic query
racoon query --project my-project --since 2h --limit 50

# With filter
racoon query --project my-project --filter 'resource.type="cloud_run_revision"'

# With AI-generated filter
racoon query --project my-project --ai "all errors from Cloud Run today"

Export & Offline Mode

# Export logs to JSON
racoon export --project my-project --output logs.json --limit 1000

# Export with AI query
racoon export --project my-project --output errors.json --ai "critical errors last 24h"

# Export to NDJSON (newline-delimited)
racoon export --project my-project --output logs.ndjson --format ndjson

# View exported logs offline
racoon view logs.json

Configuration

# Show config file path
racoon config path

# Create default config
racoon config init

# Show current config
racoon config show

# Edit config
racoon config edit

⚙️ Configuration

Config file location: ~/.config/racoon/config.toml

# AI Settings
[ai]
api_key = "your-gemini-api-key"
model = "gemini-2.0-flash"

# Default Values
[defaults]
project = "my-default-project"
since = "1h"
limit = 100
severity = "INFO"

# UI Settings
[ui]
max_logs = 100
mouse = false
theme = "dark"  # or "light"

# Logging
[logging]
level = "info"

Environment Variables

🤖 AI Features

Racoon integrates with Google Gemini for intelligent log analysis.

Explain Logs

Press e on any log to get an AI explanation:

┌─ AI Analysis ────────────────────────────────────────┐
│ ### 1. Summary                                       │
│ This error indicates a connection timeout to the     │
│ database server. The request waited 30 seconds but   │
│ no response was received.                            │
│                                                      │
│ ### 2. Severity Assessment                           │
│ **High** - Database connectivity issues can cause    │
│ cascading failures across dependent services.        │
│                                                      │
│ ### 3. Recommended Actions                           │
│ 1. Check database server health                      │
│ 2. Verify network connectivity                       │
│ 3. Review connection pool settings                   │
└──────────────────────────────────────────────────────┘

Ask Questions

Press ? and ask in natural language:

? Are there any errors from Cloud Run in the last hour?

┌─ AI Analysis ────────────────────────────────────────┐
│ Yes, I found 3 errors from Cloud Run:                │
│                                                      │
│ 1. 10:23:15 - Container failed to start (OOM)        │
│ 2. 10:25:33 - Request timeout after 300s             │
│ 3. 10:45:01 - Connection refused to backend          │
│                                                      │
│ The most critical is the OOM error which suggests    │
│ your container needs more memory allocation.         │
└──────────────────────────────────────────────────────┘

AI Commands

You can also use AI to set filters:

? 帮我设置过滤条件为仅显示ERROR以上的日志

✅ 已设置过滤条件: severity>=ERROR

🌐 Supported GCP Log Types

• Cloud Run
• Cloud Functions
• App Engine
• Kubernetes Engine (GKE)
• Compute Engine
• Cloud SQL
• BigQuery
• Custom logs (any logName)

🔧 Troubleshooting

Authentication Issues

# Re-authenticate
gcloud auth application-default login

# Check current credentials
racoon auth

No Logs Showing

1. Check project ID is correct
2. Verify you have roles/logging.viewer permission
3. Try a broader time range: --since 24h

AI Not Working

1. Check API key is set: racoon config show
2. Verify API key at Google AI Studio
3. Check network connectivity

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• ratatui - Terminal UI framework
• Google Cloud Logging - Log infrastructure
• Google Gemini - AI capabilities

Made with ❤️ and 🦝