chore: import upstream snapshot with attribution

2026-07-13 13:11:39 +08:00
commit c8cebdfeee
4654 changed files with 626756 additions and 0 deletions
@@ -0,0 +1,360 @@
+---
+id: ai_agent
+title: HertzBeat AI Agent User Guide
+sidebar_label: HertzBeat AI
+keywords: [AI, Chat, Agent, Monitoring, AI Agent, OpenAI]
+---
+
+> HertzBeat AI Agent is an intelligent monitoring AI Agent that helps you manage monitors, configure alerts, and optimize your infrastructure monitoring through natural language conversation.
+
+## Overview
+
+The HertzBeat AI Agent feature provides an interactive chat interface where you can:
+
+**Monitor Management:**
+
+- 🔍 Query and filter existing monitors by status, type, host, and labels
+- ➕ Add new monitors for websites, APIs, databases, and services
+- 📊 Get detailed information about available monitor types and their parameters
+- ⚡ Check monitor status and troubleshoot monitoring issues
+
+**Alert Management:**
+
+- 🚨 Query active alerts with comprehensive filtering (type, status, search)
+- 📈 Get alert summary statistics and distribution
+- 🔔 View both single and grouped alerts
+- 📋 Analyze alert patterns and trends
+
+**Metrics Analysis:**
+
+- 📊 Retrieve real-time metrics data for any monitor
+- 📈 Access historical metrics with customizable time ranges
+- 💾 Check warehouse storage system status
+- 🔍 Query specific metric fields and labels
+
+**Alert Rule Management:**
+
+- ⚙️ Configure alert rules and thresholds
+- 📝 Manage alert definitions for different monitor types
+- 🎯 Set up custom alerting criteria
+
+## Prerequisites
+
+Before using the AI Agent, ensure:
+
+1 **OpenAI Configuration**: Valid OpenAI API key must be configured. Optionally, you can change the model in `application.yml` under `spring.ai.openai.chat.options.model` (default is `gpt-4.1-nano`).
+2 **Database Connection**: HertzBeat database must be accessible for monitor operations
+
+## Configuration
+
+### OpenAI API Key Setup
+
+The AI Agent uses OpenAI's GPT models. You need to configure an OpenAI API key in this ways:
+
+#### Database Configuration via UI
+
+1. Navigate to the AI Agent interface
+2. If no API key is configured, you'll see a configuration dialog
+3. Enter your OpenAI API key
+4. Click **Save Configuration**
+
+### Configuration Priority
+
+- **Database configuration** takes priority over YAML configuration
+- Configuration changes are applied immediately without restart
+- Invalid API keys are automatically validated before saving
+
+## Using the AI Agent
+
+### Accessing the Chat Interface
+
+1. Navigate to the **AI Agent** section in HertzBeat web interface
+2. You'll see the HertzBeat Monitoring AI Agent welcome screen
+3. Start typing your questions in the chat input field
+
+### Sample Conversations
+
+#### Adding a New Monitor
+
+```text
+You: Add a new HTTP monitor for my website https://example.com
+AI Agent: I'll help you add an HTTP monitor for https://example.com. 
+Let me create that monitor with the following configuration:
+- Name: example.com Website Monitor
+- Type: HTTP
+- Host: example.com
+- Port: 443 (HTTPS)
+- Path: /
+- Interval: 60 seconds
+
+Monitor created successfully with ID: 12345
+```
+
+#### Listing Existing Monitors
+
+```text
+You: Show me all my current monitors
+AI Agent: Here are your current monitors:
+
+1. **Linux Server** (ID: 1001)
+   - Status: ✅ Online
+   - Host: 192.168.1.100
+   - Last Check: 2 minutes ago
+
+2. **MySQL Database** (ID: 1002) 
+   - Status: ⚠️ Warning
+   - Host: db.example.com
+   - Last Check: 30 seconds ago
+
+3. **Website Monitor** (ID: 1003)
+   - Status: ✅ Online
+   - Host: https://example.com
+   - Last Check: 1 minute ago
+
+Would you like details on any specific monitor?
+```
+
+#### Getting Monitor Type Information
+
+```text
+You: What parameters do I need to monitor a PostgreSQL database?
+AI Agent: To monitor a PostgreSQL database, you'll need these parameters:
+
+**Required Parameters:**
+- **Host**: Database server IP/hostname
+- **Port**: PostgreSQL port (default: 5432)
+- **Database**: Database name to connect to
+- **Username**: Database username
+- **Password**: Database password
+
+**Optional Parameters:**
+- **Timeout**: Connection timeout (default: 6000ms)
+- **Query Timeout**: SQL query timeout (default: 3000ms)
+- **SSL**: Enable SSL connection (default: false)
+
+Would you like me to help you add a PostgreSQL monitor?
+```
+
+#### Alert Management
+
+```text
+You: Show me all critical alerts from the last 24 hours
+AI Agent: Here are the critical alerts from the last 24 hours:
+
+🚨 **Active Alerts (3 firing)**
+1. **High CPU Usage** - Linux Server (ID: 1001)
+   - Status: 🔥 Firing
+   - Triggered: 2 hours ago
+   - Severity: Critical
+   - Message: CPU usage 95% > threshold 90%
+
+2. **Database Connection Failed** - MySQL Database (ID: 1002)
+   - Status: 🔥 Firing  
+   - Triggered: 45 minutes ago
+   - Severity: Critical
+   - Message: Connection timeout after 10 seconds
+
+3. **Website Response Time** - Website Monitor (ID: 1003)
+   - Status: ⚠️ Warning
+   - Triggered: 15 minutes ago
+   - Severity: Warning
+   - Message: Response time 5.2s > threshold 3s
+
+**Alert Summary:**
+- Total alerts: 12
+- Firing: 3 (2 critical, 1 warning)
+- Resolved: 9
+
+Would you like me to help you investigate any specific alert?
+```
+
+#### Metrics Analysis
+
+```text
+You: Show me the CPU usage for my Linux server over the last 6 hours
+AI Agent: Here's the CPU usage data for your Linux server (Monitor ID: 1001) over the last 6 hours:
+
+📊 **CPU Usage Metrics - Last 6 Hours**
+```
+
+Time          | Usage (%) | Load Avg | Processes
+14:00-15:00   | 45.2%     | 1.2      | 156
+15:00-16:00   | 67.8%     | 2.1      | 178
+16:00-17:00   | 89.4%     | 3.8      | 195
+17:00-18:00   | 92.1%     | 4.2      | 203
+18:00-19:00   | 94.7%     | 4.8      | 210
+19:00-20:00   | 88.3%     | 3.5      | 188
+
+``` text
+
+**Analysis:**
+- Peak usage: 94.7% at 19:00
+- Average usage: 79.6%
+- Trend: High usage sustained for 3+ hours
+- Current status: Decreasing (88.3%)
+
+**Real-time metrics:**
+- Current CPU: 76.2%
+- Memory usage: 82.1%
+- Disk I/O: Normal
+
+Would you like me to check historical data for comparison or investigate the high usage cause?
+```
+
+#### Alert Rule Configuration
+
+```text
+You: Set up an alert rule for when my website response time exceeds 5 seconds
+AI Agent: I'll help you create an alert rule for website response time monitoring.
+
+**Alert Rule Configuration:**
+- **Monitor Type**: HTTP/Website
+- **Metric**: Response Time
+- **Condition**: Greater than 5 seconds
+- **Severity**: Warning
+- **Evaluation**: Check every 60 seconds
+- **Notification**: Email + Dashboard
+
+**Proposed Rule:**
+```yaml
+name: "Website Response Time Alert"
+condition: "response_time > 5000ms"
+severity: "warning"
+description: "Alert when website response time exceeds 5 seconds"
+evaluation_interval: 60s
+for: 2m  # Alert after condition persists for 2 minutes
+```
+
+This rule will:
+
+1. Monitor response time every minute
+2. Trigger alert if response time > 5s for 2+ minutes
+3. Send notifications via configured channels
+4. Show in dashboard with warning status
+
+Would you like me to apply this configuration or modify any settings?
+
+``` text
+
+### Chat Features
+
+#### Message History
+
+- All conversations are automatically saved
+- Access previous conversations from the sidebar
+- Search through conversation history
+- Export conversation logs
+
+#### Real-time Responses
+
+- Streaming responses for immediate feedback
+- Typing indicators show when the assistant is processing
+- Cancel ongoing requests if needed
+
+#### Conversation Management
+
+- Create new conversations for different topics
+- Rename conversations for better organization
+- Delete old conversations to keep things clean
+Note: Conversations are not saved in the database
+
+## Troubleshooting
+
+### Common Issues
+
+#### Chat Interface Not Loading
+
+**Symptoms**: Chat interface shows loading spinner indefinitely
+**Solutions**:
+
+1. Check browser console for JavaScript errors
+2. Ensure network connectivity to HertzBeat server
+
+#### "Service Unavailable" Message
+
+**Symptoms**: Chat shows "HertzBeat AI monitoring service unavailable"
+**Solutions**:
+1.Verify OpenAI API key configuration
+2.Check application logs for errors
+3.Ensure database connectivity
+
+#### Invalid API Key Error
+
+**Symptoms**: Configuration dialog shows "Invalid API key" error
+**Solutions**:
+
+1. Verify your OpenAI API key starts with `sk-`
+2. Check API key has sufficient credits/quota
+3. Test API key directly with OpenAI API
+4. Ensure no extra spaces in the API key
+
+#### Monitor Creation Failures  
+
+**Symptoms**: AI suggests monitor configuration but creation fails
+**Solutions**:
+
+1. Verify you have permissions to create monitors
+2. Check if monitor with same name already exists
+3. Ensure target host/service is accessible
+4. Review monitor parameter validation errors
+
+### Debug Mode
+
+Enable debug logging by setting log level to DEBUG for:
+
+```yaml
+logging:
+  level:
+    org.apache.hertzbeat.ai.agent: DEBUG
+```
+
+## Best Practices
+
+### Effective Chat Usage
+
+1. **Be Specific**: "Add HTTP monitor for api.example.com port 8080" vs "add a monitor"
+2. **Provide Context**: Mention if you want production vs test monitors
+3. **Ask Follow-ups**: Request configuration details if needed
+4. **Use Natural Language**: The AI understands conversational requests
+
+### Monitor Management
+
+1. **Naming Convention**: Use descriptive monitor names
+2. **Documentation**: Ask the AI to document complex configurations
+
+### Security Considerations
+
+1. **API Key Security**: Store OpenAI API keys securely
+2. **Access Control**: Limit AI chat access to authorized users
+3. **Data Privacy**: Be mindful of sensitive information in chat logs
+4. **Network Security**: Ensure secure connections to OpenAI API
+
+## Advanced Features
+
+### Bulk Operations
+
+```text
+You: Add HTTP monitors for all services in my staging environment:
+- api-staging.example.com:8080
+- web-staging.example.com:80  
+- admin-staging.example.com:3000
+```
+
+## Limitations
+
+- Requires active internet connection for OpenAI API
+- OpenAI API usage incurs costs based on token consumption
+- Complex multi-step operations may require multiple interactions
+- Some advanced configurations may need manual setup
+- Rate limiting may apply based on OpenAI plan
+
+## Support
+
+For issues with AI Agent:
+
+1. Check this documentation first
+2. Review application logs for errors
+3. Test OpenAI API connectivity independently  
+4. Contact HertzBeat support with specific error messages
+
+---