Automated Kubernetes debugging and tracing tool that constructs complete event chains from Deployment/Pod to Ingress/Service, including logs, events, readiness probes, and network traces.
# Install from source
go install github.com/Gosayram/kubetraceflow@latest
# Or download binary from releases
curl -LO https://github.com/Gosayram/kubetraceflow/releases/latest/download/kubetraceflow-linux-amd64
chmod +x kubetraceflow-linux-amd64
sudo mv kubetraceflow-linux-amd64 /usr/local/bin/kubetraceflow# Trace application by deployment name
kubetraceflow --app my-app --namespace staging
# Trace by label selector
kubetraceflow --selector app=my-app,version=v1.0
# Include detailed network analysis
kubetraceflow --app my-app --network-detailed
# Export results to file
kubetraceflow --app my-app --output json > trace-report.json- Complete Chain Analysis: Traces from Deployment to external access
- Root Cause Detection: Identifies specific failure points
- Network Policy Evaluation: Analyzes connectivity issues
- Service Mesh Support: Istio, Linkerd, Cilium integration
- Multiple Output Formats: CLI tables, JSON, SVG visualization
- Real-time Monitoring: Follow mode for live debugging
kubetraceflow --app nginx --namespace default
✓ Deployment found: nginx (3/3 replicas ready)
✓ ReplicaSet: nginx-7c5ddbdf54 (3 pods)
✓ Pods: 3/3 running
- nginx-7c5ddbdf54-abc12: Ready (10.244.1.15)
- nginx-7c5ddbdf54-def34: Ready (10.244.2.8)
- nginx-7c5ddbdf54-ghi56: Ready (10.244.1.22)
✓ Service: nginx-service (ClusterIP: 10.96.45.123)
✓ Endpoints: 3 ready addresses
✓ Ingress: nginx-ingress (host: nginx.example.com)
✗ DNS Resolution: nginx.example.com → FAILED (check external DNS)
✓ NetworkPolicy: No restrictions found
✓ TLS Certificate: Valid (expires: 2024-12-31)
Issues Found:
1. External DNS resolution failed for nginx.example.com
Recommendation: Verify DNS configuration and external accessibility
Status: 1 issue detected (DNS)
Usage: kubetraceflow [flags]
Application Selection (choose one):
-a, --app string Application name (deployment/service name)
-s, --selector string Label selector (e.g., app=nginx,version=v1)
-i, --ingress string Ingress name to trace backwards
Options:
-n, --namespace string Kubernetes namespace (default: current context)
-A, --all-namespaces Search across all namespaces
--follow Follow mode for real-time monitoring
--network-detailed Include detailed network analysis
--include-logs Include recent container logs
--max-events int Maximum events to show (default: 10)
Output:
-o, --output string Output format: table|json|yaml|svg (default: table)
-f, --file string Output file path
--no-color Disable colored output
Debug:
-v, --verbose Verbose output
--debug Debug logging
--dry-run Show what would be analyzed without execution
- Go 1.24.4 or later
- Kubernetes cluster access
- kubectl configured
# Clone repository
git clone https://github.com/Gosayram/kubetraceflow.git
cd kubetraceflow
# Install dependencies
make deps
# Build binary
make build
# Run tests
make test
# Install locally
make installkubetraceflow/
├── cmd/
│ └── kubetraceflow/ # CLI entry point
├── internal/
│ ├── analyzer/ # Component analysis logic
│ ├── chain/ # Dependency chain builder
│ ├── discovery/ # Kubernetes resource discovery
│ ├── policy/ # NetworkPolicy evaluator
│ └── reporter/ # Output formatting
├── pkg/
│ ├── k8s/ # Kubernetes client utilities
│ └── types/ # Shared data structures
├── configs/ # Configuration files
├── examples/ # Usage examples
├── docs/ # Documentation
└── scripts/ # Build and utility scripts
# Run unit tests
make test
# Run integration tests (requires cluster)
make test-integration
# Run linting
make lint
# Generate coverage report
make coverage- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
See CONTRIBUTING.md for detailed guidelines.
kubetraceflow supports a configuration file at ~/.kubetraceflow.yaml for setting default values and preferences.
# Show current configuration
kubetraceflow config --show
# Edit configuration in default editor
kubetraceflow config --edit
# Reset to defaults
kubetraceflow config --reset
# Show config file path
kubetraceflow config --path# Default namespace to use when not specified
defaultNamespace: "default"
# Default output format (text, json, svg)
defaultOutput: "text"
# Kubernetes client configuration
kubernetes:
# Default context to use (optional)
context: ""
# Path to kubeconfig file (optional, uses default if not specified)
configPath: ""
# Output formatting options
output:
# Show detailed container information
showContainerDetails: true
# Show network policy details
showNetworkPolicies: true
# Show RBAC information
showRBAC: true
# Show PVC information
showPVCs: true
# Discovery options
discovery:
# Include all namespaces when no specific namespace is given
allNamespaces: false
# Timeout for API calls in seconds
timeoutSeconds: 30# ~/.kubetraceflow.yaml
defaultNamespace: "staging"
defaultOutput: "json"
kubernetes:
context: "staging-cluster"
output:
showContainerDetails: true
showNetworkPolicies: true
showRBAC: false
showPVCs: true
discovery:
allNamespaces: false
timeoutSeconds: 60kubetraceflow uses your current kubectl context by default. You can specify alternative configurations:
# Use specific kubeconfig file
export KUBECONFIG=/path/to/kubeconfig
kubetraceflow --app my-app
# Use specific context
kubectl config use-context my-cluster
kubetraceflow --app my-app-
Permission Denied
Error: failed to list deployments: deployments.apps is forbidden
Solution: Ensure RBAC permissions for required resources
-
No Resources Found
Error: no deployment found matching criteria
Solution: Verify application name, namespace, and label selectors
-
Network Timeout
Error: context deadline exceeded
Solution: Check cluster connectivity and increase timeout
# Enable debug logging
kubetraceflow --app my-app --debug
# Dry run to see what would be analyzed
kubetraceflow --app my-app --dry-runThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Documentation: docs/
- Issues: GitHub Issues
- Discussions: GitHub Discussions