wehub-resource-sync
1 line
9.8 KiB
JSON
1 line
9.8 KiB
JSON
{"content": "---\nallowed-tools: Read, Write, Edit, Bash\nargument-hint: [system-component] | --application | --database | --network | --deployment | --comprehensive\ndescription: Generate systematic troubleshooting documentation with diagnostic procedures, common issues, and automated solutions\n---\n\n# Troubleshooting Guide Generator\n\nGenerate troubleshooting documentation: $ARGUMENTS\n\n## Current System Context\n\n- System architecture: @docker-compose.yml or @k8s/ or detect deployment type\n- Log locations: !`find . -name \"*log*\" -type d | head -3`\n- Monitoring setup: !`grep -r \"prometheus\\|grafana\\|datadog\" . 2>/dev/null | wc -l` monitoring references\n- Error patterns: !`find . -name \"*.log\" | head -3` recent logs\n- Health endpoints: !`grep -r \"health\\|status\" src/ 2>/dev/null | head -3`\n\n## Task\n\nCreate comprehensive troubleshooting guide with systematic diagnostic procedures: $ARGUMENTS\n\n1. **System Overview and Architecture**\n - Document the system architecture and components\n - Map out dependencies and integrations\n - Identify critical paths and failure points\n - Create system topology diagrams\n - Document data flow and communication patterns\n\n2. **Common Issues Identification**\n - Collect historical support tickets and issues\n - Interview team members about frequent problems\n - Analyze error logs and monitoring data\n - Review user feedback and complaints\n - Identify patterns in system failures\n\n3. **Troubleshooting Framework**\n - Establish systematic diagnostic procedures\n - Create problem isolation methodologies\n - Document escalation paths and procedures\n - Set up logging and monitoring checkpoints\n - Define severity levels and response times\n\n4. **Diagnostic Tools and Commands**\n \n ```markdown\n ## Essential Diagnostic Commands\n \n ### System Health\n ```bash\n # Check system resources\n top # CPU and memory usage\n df -h # Disk space\n free -m # Memory usage\n netstat -tuln # Network connections\n \n # Application logs\n tail -f /var/log/app.log\n journalctl -u service-name -f\n \n # Database connectivity\n mysql -u user -p -e \"SELECT 1\"\n psql -h host -U user -d db -c \"SELECT 1\"\n ```\n ```\n\n5. **Issue Categories and Solutions**\n\n **Performance Issues:**\n ```markdown\n ### Slow Response Times\n \n **Symptoms:**\n - API responses > 5 seconds\n - User interface freezing\n - Database timeouts\n \n **Diagnostic Steps:**\n 1. Check system resources (CPU, memory, disk)\n 2. Review application logs for errors\n 3. Analyze database query performance\n 4. Check network connectivity and latency\n \n **Common Causes:**\n - Database connection pool exhaustion\n - Inefficient database queries\n - Memory leaks in application\n - Network bandwidth limitations\n \n **Solutions:**\n - Restart application services\n - Optimize database queries\n - Increase connection pool size\n - Scale infrastructure resources\n ```\n\n6. **Error Code Documentation**\n \n ```markdown\n ## Error Code Reference\n \n ### HTTP Status Codes\n - **500 Internal Server Error**\n - Check application logs for stack traces\n - Verify database connectivity\n - Check environment variables\n \n - **404 Not Found**\n - Verify URL routing configuration\n - Check if resources exist\n - Review API endpoint documentation\n \n - **503 Service Unavailable**\n - Check service health status\n - Verify load balancer configuration\n - Check for maintenance mode\n ```\n\n7. **Environment-Specific Issues**\n - Document development environment problems\n - Address staging/testing environment issues\n - Cover production-specific troubleshooting\n - Include local development setup problems\n\n8. **Database Troubleshooting**\n \n ```markdown\n ### Database Connection Issues\n \n **Symptoms:**\n - \"Connection refused\" errors\n - \"Too many connections\" errors\n - Slow query performance\n \n **Diagnostic Commands:**\n ```sql\n -- Check active connections\n SHOW PROCESSLIST;\n \n -- Check database size\n SELECT table_schema, \n ROUND(SUM(data_length + index_length) / 1024 / 1024, 1) AS 'DB Size in MB' \n FROM information_schema.tables \n GROUP BY table_schema;\n \n -- Check slow queries\n SHOW VARIABLES LIKE 'slow_query_log';\n ```\n ```\n\n9. **Network and Connectivity Issues**\n \n ```markdown\n ### Network Troubleshooting\n \n **Basic Connectivity:**\n ```bash\n # Test basic connectivity\n ping example.com\n telnet host port\n curl -v https://api.example.com/health\n \n # DNS resolution\n nslookup example.com\n dig example.com\n \n # Network routing\n traceroute example.com\n ```\n \n **SSL/TLS Issues:**\n ```bash\n # Check SSL certificate\n openssl s_client -connect example.com:443\n curl -vI https://example.com\n ```\n ```\n\n10. **Application-Specific Troubleshooting**\n \n **Memory Issues:**\n ```markdown\n ### Out of Memory Errors\n \n **Java Applications:**\n ```bash\n # Check heap usage\n jstat -gc [PID]\n jmap -dump:format=b,file=heapdump.hprof [PID]\n \n # Analyze heap dump\n jhat heapdump.hprof\n ```\n \n **Node.js Applications:**\n ```bash\n # Monitor memory usage\n node --inspect app.js\n # Use Chrome DevTools for memory profiling\n ```\n ```\n\n11. **Security and Authentication Issues**\n \n ```markdown\n ### Authentication Failures\n \n **Symptoms:**\n - 401 Unauthorized responses\n - Token validation errors\n - Session timeout issues\n \n **Diagnostic Steps:**\n 1. Verify credentials and tokens\n 2. Check token expiration\n 3. Validate authentication service\n 4. Review CORS configuration\n \n **Common Solutions:**\n - Refresh authentication tokens\n - Clear browser cookies/cache\n - Verify CORS headers\n - Check API key permissions\n ```\n\n12. **Deployment and Configuration Issues**\n \n ```markdown\n ### Deployment Failures\n \n **Container Issues:**\n ```bash\n # Check container status\n docker ps -a\n docker logs container-name\n \n # Check resource limits\n docker stats\n \n # Debug container\n docker exec -it container-name /bin/bash\n ```\n \n **Kubernetes Issues:**\n ```bash\n # Check pod status\n kubectl get pods\n kubectl describe pod pod-name\n kubectl logs pod-name\n \n # Check service connectivity\n kubectl get svc\n kubectl port-forward pod-name 8080:8080\n ```\n ```\n\n13. **Monitoring and Alerting Setup**\n - Configure health checks and monitoring\n - Set up log aggregation and analysis\n - Implement alerting for critical issues\n - Create dashboards for system metrics\n - Document monitoring thresholds\n\n14. **Escalation Procedures**\n \n ```markdown\n ## Escalation Matrix\n \n ### Severity Levels\n \n **Critical (P1):** System down, data loss\n - Immediate response required\n - Escalate to on-call engineer\n - Notify management within 30 minutes\n \n **High (P2):** Major functionality impaired\n - Response within 2 hours\n - Escalate to senior engineer\n - Provide hourly updates\n \n **Medium (P3):** Minor functionality issues\n - Response within 8 hours\n - Assign to appropriate team member\n - Provide daily updates\n ```\n\n15. **Recovery Procedures**\n - Document system recovery steps\n - Create data backup and restore procedures\n - Establish rollback procedures for deployments\n - Document disaster recovery processes\n - Test recovery procedures regularly\n\n16. **Preventive Measures**\n - Implement monitoring and alerting\n - Set up automated health checks\n - Create deployment validation procedures\n - Establish code review processes\n - Document maintenance procedures\n\n17. **Knowledge Base Integration**\n - Link to relevant documentation\n - Reference API documentation\n - Include links to monitoring dashboards\n - Connect to team communication channels\n - Integrate with ticketing systems\n\n18. **Team Communication**\n \n ```markdown\n ## Communication Channels\n \n ### Immediate Response\n - Slack: #incidents channel\n - Phone: On-call rotation\n - Email: alerts@company.com\n \n ### Status Updates\n - Status page: status.company.com\n - Twitter: @company_status\n - Internal wiki: troubleshooting section\n ```\n\n19. **Documentation Maintenance**\n - Regular review and updates\n - Version control for troubleshooting guides\n - Feedback collection from users\n - Integration with incident post-mortems\n - Continuous improvement processes\n\n20. **Self-Service Tools**\n - Create diagnostic scripts and tools\n - Build automated recovery procedures\n - Implement self-healing systems\n - Provide user-friendly diagnostic interfaces\n - Create chatbot integration for common issues\n\n**Advanced Troubleshooting Techniques:**\n\n**Log Analysis:**\n```bash\n# Search for specific errors\ngrep -i \"error\" /var/log/app.log | tail -50\n\n# Analyze log patterns\nawk '{print $1}' access.log | sort | uniq -c | sort -nr\n\n# Monitor logs in real-time\ntail -f /var/log/app.log | grep -i \"exception\"\n```\n\n**Performance Profiling:**\n```bash\n# System performance\niostat -x 1\nsar -u 1 10\nvmstat 1 10\n\n# Application profiling\nstrace -p [PID]\nperf record -p [PID]\n```\n\nRemember to:\n- Keep troubleshooting guides up-to-date\n- Test all documented procedures regularly\n- Collect feedback from users and improve guides\n- Include screenshots and visual aids where helpful\n- Make guides searchable and well-organized"} |