Migration and Upgrade Guide
This guide helps you migrate to new features and upgrade existing Swit framework applications to take advantage of the latest enhancements including Sentry monitoring, switctl CLI tools, and security improvements.
Recent Major Updates
Version Timeline
- v0.3.0: Comprehensive Sentry integration, switctl CLI tool, security enhancements
- v0.2.0: Enhanced testing framework, race condition fixes
- v0.1.0: Core framework with HTTP/gRPC transports
Upgrading to Sentry Integration (v0.3.0)
1. Update Dependencies
Add Sentry SDK to your project:
go get github.com/getsentry/sentry-go@v0.27.0
Update your go.mod
:
require (
github.com/innovationmech/swit v0.3.0
github.com/getsentry/sentry-go v0.27.0
)
2. Configuration Migration
Before (v0.2.0 and earlier)
service_name: "my-service"
http:
port: "8080"
grpc:
port: "9080"
After (v0.3.0+)
service_name: "my-service"
http:
port: "8080"
grpc:
port: "9080"
# Add Sentry configuration
sentry:
enabled: true
dsn: "${SENTRY_DSN}"
environment: "production"
sample_rate: 1.0
traces_sample_rate: 0.1
3. Environment Variables
Add Sentry environment variables:
# Required for Sentry
export SENTRY_DSN="https://your-dsn@sentry.io/project-id"
# Optional
export SENTRY_ENVIRONMENT="production"
export SENTRY_RELEASE="v1.0.0"
4. Code Changes (Optional)
The framework handles Sentry automatically, but you can add custom context:
// Before: Basic error handling
func (h *Handler) ProcessOrder(c *gin.Context) {
if err := h.service.Process(); err != nil {
log.Error("Process failed", zap.Error(err))
c.JSON(500, gin.H{"error": "Internal error"})
return
}
}
// After: Enhanced with Sentry context
func (h *Handler) ProcessOrder(c *gin.Context) {
if err := h.service.Process(); err != nil {
// Keep existing logging
log.Error("Process failed", zap.Error(err))
// Add Sentry context (optional)
sentry.WithScope(func(scope *sentry.Scope) {
scope.SetTag("operation", "process_order")
scope.SetContext("request", map[string]interface{}{
"user_id": c.GetHeader("User-ID"),
"order_id": c.Param("id"),
})
sentry.CaptureException(err)
})
c.JSON(500, gin.H{"error": "Internal error"})
return
}
}
5. Gradual Rollout Strategy
Phase 1: Enable with Low Sampling
sentry:
enabled: true
dsn: "${SENTRY_DSN}"
sample_rate: 0.1 # Start with 10% sampling
traces_sample_rate: 0.01 # 1% performance sampling
Phase 2: Increase Sampling
sentry:
enabled: true
dsn: "${SENTRY_DSN}"
sample_rate: 1.0 # Full error sampling
traces_sample_rate: 0.1 # 10% performance sampling
Phase 3: Full Production Configuration
sentry:
enabled: true
dsn: "${SENTRY_DSN}"
environment: "production"
sample_rate: 1.0
traces_sample_rate: 0.1
enable_profiling: true
# Production filtering
http_ignore_status_codes: [400, 401, 403, 404]
http_ignore_paths: ["/health", "/metrics"]
Adopting switctl CLI Tools
1. Installation
Build switctl from the framework source:
# From framework root directory
make build
# Add to PATH
sudo cp ./bin/switctl /usr/local/bin/
2. Existing Project Integration
Initialize switctl in existing projects:
# In your project directory
switctl init --existing
# This creates .switctl.yaml with current project configuration
3. Configuration File Creation
switctl will create .switctl.yaml
:
project:
name: "my-service"
type: "microservice"
templates:
default: "http-grpc"
database:
type: "postgresql" # Based on existing configuration
testing:
coverage_threshold: 80
race_detection: true
security:
enabled: true
scan_deps: true
4. Gradual Adoption Workflow
Start with Quality Checks
# Run checks on existing codebase
switctl check --quality
switctl check --security
switctl check --tests --coverage
Add Code Generation
# Generate new components using templates
switctl generate api user --methods=crud
switctl generate middleware auth --type=jwt
Adopt Development Workflow
# Use development utilities
switctl dev watch # Auto-rebuild on changes
switctl deps check # Dependency management
Security Enhancements Migration
1. GitHub Actions Workflow Updates
Before: Minimal permissions
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
After: Explicit minimal permissions
name: CI
on: [push, pull_request]
# Add explicit permissions
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
2. Update All Workflows
Apply security improvements to all workflow files:
# Update existing workflows
find .github/workflows -name "*.yml" -o -name "*.yaml" | \
xargs sed -i '1i permissions:\n contents: read\n'
3. Dependency Security Scanning
Use switctl for enhanced security:
# Scan dependencies for vulnerabilities
switctl check --security --deps
# Check for outdated packages
switctl deps check --security
Testing Framework Enhancements
1. Race Condition Fixes
If you experienced race conditions in tests, update test patterns:
Before: Potential race conditions
func TestConcurrentAccess(t *testing.T) {
service := NewService()
// Multiple goroutines without proper synchronization
for i := 0; i < 10; i++ {
go func() {
service.Process()
}()
}
}
After: Proper synchronization
func TestConcurrentAccess(t *testing.T) {
service := NewService()
var wg sync.WaitGroup
for i := 0; i < 10; i++ {
wg.Add(1)
go func() {
defer wg.Done()
service.Process()
}()
}
wg.Wait()
}
2. Enhanced Test Commands
Use new test management features:
# Run tests with race detection
make test-race
# Generate coverage reports
make test-coverage
# Use switctl for advanced testing
switctl test --coverage --race --benchmark
Configuration Schema Updates
1. ServerConfig Structure Changes
New configuration fields added:
type ServerConfig struct {
// Existing fields
ServiceName string `yaml:"service_name"`
ShutdownTimeout time.Duration `yaml:"shutdown_timeout"`
HTTP HTTPConfig `yaml:"http"`
GRPC GRPCConfig `yaml:"grpc"`
Discovery DiscoveryConfig `yaml:"discovery"`
// NEW: Sentry configuration
Sentry SentryConfig `yaml:"sentry"`
}
2. Validation Enhancements
Enhanced configuration validation:
// Configuration is now validated more strictly
config := &ServerConfig{
Sentry: SentryConfig{
Enabled: true,
DSN: "invalid-format", // Will cause validation error
SampleRate: 2.0, // Will cause validation error (must be 0.0-1.0)
},
}
if err := config.Validate(); err != nil {
// More detailed error messages
log.Fatal("Configuration validation failed:", err)
}
Backward Compatibility
What's Preserved
- ✅ All existing HTTP/gRPC transport configurations
- ✅ Service discovery settings
- ✅ Middleware configurations
- ✅ Business service interfaces
- ✅ Dependency injection patterns
- ✅ Health check implementations
What's New (Opt-in)
- 🆕 Sentry configuration (disabled by default)
- 🆕 switctl CLI tools (optional installation)
- 🆕 Enhanced security checks
- 🆕 Improved testing utilities
Breaking Changes
None - This is a backward-compatible update. All existing services will continue to work without changes.
Step-by-Step Migration Checklist
Pre-Migration
- [ ] Backup existing configuration files
- [ ] Review current error handling patterns
- [ ] Document current monitoring setup
- [ ] Test current application thoroughly
Dependencies
- [ ] Update framework dependency to v0.3.0+
- [ ] Add Sentry SDK dependency
- [ ] Run
go mod tidy
- [ ] Verify all tests pass
Configuration
- [ ] Add Sentry section to configuration files
- [ ] Set up environment variables
- [ ] Configure appropriate sampling rates
- [ ] Test configuration validation
Development Tools
- [ ] Build and install switctl CLI
- [ ] Initialize .switctl.yaml in projects
- [ ] Run quality checks with switctl
- [ ] Update development scripts/Makefile
Security
- [ ] Update GitHub Actions workflows
- [ ] Add explicit permissions
- [ ] Run security scans
- [ ] Review dependency vulnerabilities
Testing
- [ ] Run race detection tests
- [ ] Generate coverage reports
- [ ] Test Sentry integration (with mock DSN)
- [ ] Verify monitoring works in staging
Production Deployment
- [ ] Deploy with Sentry disabled initially
- [ ] Enable Sentry with low sampling
- [ ] Monitor Sentry dashboard
- [ ] Gradually increase sampling rates
- [ ] Configure production filters
Rollback Procedures
If Sentry Causes Issues
- Immediate disable:
sentry:
enabled: false
- Or remove configuration entirely - service will work without Sentry
If switctl Causes Issues
switctl is completely optional:
- Remove .switctl.yaml file
- Continue using existing build processes
- Framework functions normally without CLI tools
If Security Updates Cause Issues
Revert GitHub Actions workflows:
git checkout HEAD~1 .github/workflows/
Common Migration Issues
Issue 1: Sentry Events Not Appearing
Symptoms: No events in Sentry dashboard Solutions:
- Verify DSN format and network connectivity
- Enable debug mode:
sentry.debug: true
- Check sampling rates (must be > 0)
- Test with curl requests to error endpoints
Issue 2: Too Many Sentry Events
Symptoms: High event volume, billing concerns Solutions:
- Lower sampling rates
- Add more filters
- Filter out health checks and expected errors
Issue 3: switctl Command Not Found
Symptoms: switctl: command not found
Solutions:
- Verify build:
make build
- Check PATH:
which switctl
- Use full path:
./bin/switctl
Issue 4: Performance Impact
Symptoms: Increased latency or memory usage Solutions:
- Lower performance sampling rates
- Disable profiling in production
- Monitor with smaller batch sizes
Getting Help
Documentation
Community Support
Professional Support
For enterprise migrations or complex scenarios:
- Create detailed GitHub issue with configuration
- Provide logs and error messages
- Include environment and version information
Best Practices for Migration
1. Incremental Approach
- Migrate one service at a time
- Start with development/staging environments
- Use feature flags for gradual rollout
2. Testing Strategy
- Test new features in isolation
- Run comprehensive integration tests
- Monitor performance during migration
3. Monitoring During Migration
- Watch error rates during deployment
- Monitor performance metrics
- Have rollback plan ready
4. Team Communication
- Inform team about new monitoring capabilities
- Share switctl CLI tool usage
- Document new development workflows
This migration guide ensures smooth transition to the latest Swit framework features while maintaining system reliability and team productivity.