Add Go 1.25 Flight Recorder Integration for Performance Debugging

Release Notes - v2.1.0 🚀

Release Date: November 10, 2025

🎉 What's New

Go 1.25 Flight Recorder Integration

The biggest feature in this release is the integration of Go 1.25's Flight Recorder for automatic performance tracing. This powerful diagnostic tool helps you debug production performance issues without any code changes.

Key Capabilities

✅ Automatic Slow Request Detection - Captures execution traces for requests taking > 500ms
✅ Zero Overhead When Disabled - Production-safe with opt-in configuration
✅ Visual Trace Analysis - Use go tool trace to debug performance bottlenecks
✅ Smart Buffer Management - Rolling 1 MiB buffer with 1-second retention window

Go 1.25 Upgrade

• Upgraded from Go 1.24 → Go 1.25
• Updated all dependencies to latest stable versions
• Enhanced CI/CD pipeline for Go 1.25 support

Enhanced Developer Experience

New Commands

make trace TRACE_FILE=./traces/slow-request-GET-orders-1234567890.trace

Better Documentation

• 🎨 Enhanced README with emojis and visual improvements
• 📚 Collapsible sections for better readability
• 📋 Added .env.example template

Improved Configuration

• New enableTracing environment variable

📦 What's Included

New Components

Component	Description
pkg/flightrecorder	Flight recorder package with clean API
.env.example	Environment configuration template
make trace	Trace analysis command

🔧 Configuration

New Environment Variables

# Enable flight recorder for slow request tracing
enableTracing=true  # Default: false

Trace Configuration

• Threshold: 500ms (requests slower than this are traced)
• Buffer Size: 1 MiB (rolling buffer)
• Retention: 1 second (minimum trace age)
• Output Directory: ./traces/

📊 Performance Impact

Mode	Memory Overhead	CPU Overhead	Notes
Disabled	0 bytes	0%	Default, production-safe
Enabled	~1 MiB	~1-2%	Rolling buffer, minimal impact
Capturing	+file size	Negligible	Non-blocking write

🚀 Getting Started

Quick Start

# 1. Pull latest changes
git pull origin main

# 2. Update dependencies
go mod tidy

# 3. Copy environment template
cp .env.example .env

# 4. Enable tracing (optional)
echo "enableTracing=true" >> .env

# 5. Start the application
make start

Analyzing Traces

# Application automatically captures slow requests
# Traces are saved to ./traces/

# List available traces
ls -lhtr ./traces/

# Analyze a trace
make trace TRACE_FILE=./traces/slow-request-GET-orders-1762824976.trace

🔄 Migration Guide

Upgrading from v1.x

This release is backward compatible with no breaking changes.

Automatic Migration

git pull origin main
go mod tidy
make start  # Works immediately!

Optional: Enable Tracing

# Add to .env file
enableTracing=true

Docker Users

# Rebuild with Go 1.25
docker-compose down
docker-compose build
docker-compose up -d

CI/CD

• ✅ Updated to Go 1.25
• ✅ golangci-lint v2.6.2 (latest stable)

🔐 Security

• No security vulnerabilities introduced
• Flight recorder only active when explicitly enabled
• Trace files contain execution data (review before sharing)
• Added .env to .gitignore (prevents credential leaks)

📖 Learning Resources

• Go 1.25 Flight Recorder Blog
• Go Tool Trace Documentation
• Project README

💬 Feedback

I love to hear your feedback!

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Start a discussion
• ⭐ Like this release? Give us a star!

---