wehub-resource-sync
361 lines
10 KiB
Markdown
361 lines
10 KiB
Markdown
---
|
||
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
|
||
|
||
---
|