API 监控告警：基于 Prometheus + Alertmanager 的零基础实战指南

我从事 API 运维工作已经超过5年，见过太多团队因为没有完善的监控告警体系，在 API 调用出现问题时手足无措。今天我想用最通俗易懂的方式，从零开始教大家搭建一套完整的 API 监控告警系统。

在开始之前，你需要了解我们监控的核心目标：实时掌握 API 的可用性、响应延迟、调用成功率等关键指标，并在异常发生时第一时间收到通知。本文将以 HolySheep AI 为例进行演示，这家平台的国内直连延迟小于50ms，汇率优势明显（¥7.3=$1），非常适合国内开发者使用。

一、为什么你需要 API 监控

很多初学者可能觉得：我的 API 能正常调用不就好了吗？为什么要监控？

我举个例子你就明白了。去年有个创业团队，他们的 AI 对话功能突然全部返回500错误，整整2小时后才发现问题——期间流失了大量用户。如果他们有一套监控告警系统，这个问题会在5分钟内被检测到并通知运维人员。

API 监控能帮你解决以下问题：

实时知道 API 是否还活着
了解 API 的平均响应时间是否在可接受范围内
知道某个 API 的错误率是否异常飙升
在问题影响用户之前得到通知
通过历史数据分析 API 的使用趋势

二、监控架构概览

我们的监控架构由以下几个组件构成：

Prometheus：负责采集和存储时序数据
Grafana：负责可视化展示监控数据
Alertmanager：负责处理告警和发送通知
Blackbox Exporter：负责探测 HTTP 端点是否可用

简单来说，数据流向是这样的：Blackbox Exporter 定期探测 API 端点 → Prometheus 采集探测结果 → Grafana 展示数据 → Alertmanager 根据规则发送告警。

三、环境准备与安装

3.1 安装 Docker 和 Docker Compose

为了简化安装过程，我们使用 Docker 来部署所有组件。首先安装 Docker：

# Ubuntu/Debian 系统安装 Docker
sudo apt update
sudo apt install -y docker.io docker-compose

启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

验证安装
docker --version
docker-compose --version

3.2 创建监控目录结构

我建议在服务器上创建一个专门的监控目录，方便管理所有配置文件：

# 创建监控目录
mkdir -p ~/monitoring/prometheus
mkdir -p ~/monitoring/alertmanager
mkdir -p ~/monitoring/grafana/provisioning/datasources
mkdir -p ~/monitoring/grafana/provisioning/dashboards
mkdir -p ~/monitoring/blackbox

查看目录结构
tree ~/monitoring

四、配置 Prometheus 采集 API 指标

Prometheus 是整个监控系统的核心，负责采集和存储所有监控数据。我们需要配置它来采集 HolySheep AI API 的状态。

4.1 创建 Prometheus 配置文件

# ~/monitoring/prometheus/prometheus.yml
global:
  scrape_interval: 15s      # 每15秒采集一次
  evaluation_interval: 15s   # 每15秒评估一次告警规则

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093

rule_files:
  - "/etc/prometheus/rules/*.yml"

scrape_configs:
  # 采集 Blackbox Exporter 的探测结果
  - job_name: 'blackbox'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://api.holysheep.ai/v1/models
        labels:
          service: 'holysheep-api'
          env: 'production'
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115

4.2 创建告警规则文件

这是最关键的部分——定义什么情况下需要触发告警。我的经验是，告警阈值要设置得合理，既不能太敏感导致告警疲劳，也不能太迟钝导致发现问题太晚。

# ~/monitoring/prometheus/rules/api-alerts.yml
groups:
  - name: api_health_alerts
    interval: 30s
    rules:
      # API 不可用告警
      - alert: APIEndpointDown
        expr: probe_success == 0
        for: 2m
        labels:
          severity: critical
          team: devops
        annotations:
          summary: "API 端点不可用"
          description: "{{ $labels.instance }} 已经2分钟无法访问，当前状态: {{ $value }}"

      # API 响应时间过长告警
      - alert: APIResponseTimeSlow
        expr: probe_duration_seconds > 5
        for: 5m
        labels:
          severity: warning
          team: devops
        annotations:
          summary: "API 响应时间异常"
          description: "{{ $labels.instance }} 响应时间超过5秒，当前: {{ $value }}秒"

      # API SSL 证书即将过期告警
      - alert: SSLCertExpiringSoon
        expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 14
        for: 1h
        labels:
          severity: warning
          team: devops
        annotations:
          summary: "SSL 证书即将过期"
          description: "{{ $labels.instance }} 的 SSL 证书将在14天内过期"

  - name: api_cost_alerts
    interval: 60s
    rules:
      # API 调用成功率低于阈值
      - alert: API Success Rate Low
        expr: rate(probe_success[5m]) < 0.95
        for: 3m
        labels:
          severity: warning
          team: devops
        annotations:
          summary: "API 成功率过低"
          description: "{{ $labels.instance }} 成功率低于95%，当前: {{ $value }}%"

五、配置 Alertmanager 发送告警通知

Alertmanager 负责接收 Prometheus 的告警，并根据配置规则发送通知到不同渠道（邮件、微信、钉钉、Slack等）。

5.1 Alertmanager 配置文件

# ~/monitoring/alertmanager/alertmanager.yml
global:
  resolve_timeout: 5m
  smtp_smarthost: 'smtp.qq.com:587'
  smtp_from: '[email protected]'
  smtp_auth_username: '[email protected]'
  smtp_auth_password: 'YOUR_SMTP_PASSWORD'

route:
  group_by: ['alertname', 'severity']
  group_wait: 10s
  group_interval: 10s
  repeat_interval: 12h
  receiver: 'default-receiver'
  routes:
    - match:
        severity: critical
      receiver: 'critical-receiver'
      continue: true
    - match:
        severity: warning
      receiver: 'warning-receiver'

receivers:
  - name: 'default-receiver'
    email_configs:
      - to: '[email protected]'
        send_resolved: true
        headers:
          subject: '[{{ .Status | toUpper }}] {{ .GroupLabels.alertname }}'

  - name: 'critical-receiver'
    email_configs:
      - to: '[email protected]'
        send_resolved: true
    webhook_configs:
      - url: 'http://wechat-webhook:5000/send'
        send_resolved: true

  - name: 'warning-receiver'
    email_configs:
      - to: '[email protected]'
        send_resolved: true

inhibit_rules:
  - source_match:
      severity: 'critical'
    target_match:
      severity: 'warning'
    equal: ['alertname', 'instance']

5.2 钉钉 Webhook 集成（推荐）

我强烈推荐使用钉钉或企业微信接收告警，因为手机通知的即时性比邮件好太多了。以下是钉钉 Webhook 的配置方式：

# 创建钉钉告警脚本
cat > ~/monitoring/alertmanager/dingtalk.sh << 'EOF'
#!/bin/bash

WEBHOOK_URL="https://oapi.dingtalk.com/robot/send?access_token=YOUR_DINGTALK_TOKEN"
CONTENT="$1"

curl -s -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{
    \"msgtype\": \"text\",
    \"text\": {
      \"content\": \"$CONTENT\"
    }
  }"
EOF

chmod +x ~/monitoring/alertmanager/dingtalk.sh

六、编写 HolySheep API 调用脚本

现在我们来创建一个实际调用 HolySheep AI API 的脚本，并将其集成到监控系统中。

6.1 创建 Python 监控脚本

# ~/monitoring/check_api.py
#!/usr/bin/env python3
"""
HolySheep API 健康检查脚本
用于 Prometheus 的 Blackbox Exporter 自定义探测
"""

import requests
import time
import sys
from datetime import datetime

HolySheep API 配置
BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"

def check_api_health():
    """检查 API 健康状态"""
    start_time = time.time()
    
    try:
        # 测试模型列表接口
        headers = {
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        }
        
        response = requests.get(
            f"{BASE_URL}/models",
            headers=headers,
            timeout=10
        )
        
        elapsed = time.time() - start_time
        
        # 输出 Prometheus 格式的指标
        print(f'probe_duration_seconds {elapsed:.4f}')
        print(f'probe_success 1')
        print(f'probe_http_status_code {response.status_code}')
        
        if response.status_code == 200:
            data = response.json()
            model_count = len(data.get('data', []))
            print(f'api_models_available {model_count}')
            return True
        else:
            print(f'api_error_code {response.status_code}')
            return False
            
    except requests.exceptions.Timeout:
        print(f'probe_duration_seconds 10.0000')
        print(f'probe_success 0')
        print(f'probe_error "Connection timeout"')
        return False
        
    except requests.exceptions.ConnectionError as e:
        elapsed = time.time() - start_time
        print(f'probe_duration_seconds {elapsed:.4f}')
        print(f'probe_success 0')
        print(f'probe_error "Connection refused: {str(e)}"')
        return False
        
    except Exception as e:
        elapsed = time.time() - start_time
        print(f'probe_duration_seconds {elapsed:.4f}')
        print(f'probe_success 0')
        print(f'probe_error "{str(e)}"')
        return False

if __name__ == "__main__":
    check_api_health()

6.2 创建完整的 Docker Compose 编排文件

将所有组件整合到一个 docker-compose.yml 文件中，这样一键启动整个监控 stack：

# ~/monitoring/docker-compose.yml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./prometheus/rules:/etc/prometheus/rules
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
      - '--web.console.templates=/usr/share/prometheus/consoles'
    networks:
      - monitoring

  alertmanager:
    image: prom/alertmanager:latest
    container_name: alertmanager
    restart: unless-stopped
    ports:
      - "9093:9093"
    volumes:
      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml
    networks:
      - monitoring

  blackbox-exporter:
    image: prom/blackbox-exporter:latest
    container_name: blackbox-exporter
    restart: unless-stopped
    ports:
      - "9115:9115"
    volumes:
      - ./blackbox/blackbox.yml:/config/blackbox.yml
    command:
      - '--config.file=/config/blackbox.yml'
    networks:
      - monitoring

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin123
      - GF_USERS_ALLOW_SIGN_UP=false
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

volumes:
  prometheus_data:
  grafana_data:

6.3 配置 Blackbox Exporter

# ~/monitoring/blackbox/blackbox.yml
modules:
  http_2xx:
    prober: http
    timeout: 10s
    http:
      preferred_ip_protocol: ip4
      valid_http_versions:
        - HTTP/1.1
        - HTTP/2
      fail_if_ssl: false
      method: GET

  http_post_2xx:
    prober: http
    timeout: 10s
    http:
      method: POST
      headers:
        Content-Type: application/json
      body_file: /tmp/post_body.json

6.4 启动监控系统

# 启动所有监控组件
cd ~/monitoring
docker-compose up -d

查看容器运行状态
docker-compose ps

查看 Prometheus 日志
docker-compose logs -f prometheus

查看 Alertmanager 日志
docker-compose logs -f alertmanager

七、Grafana 可视化配置

监控数据采集到了，接下来需要用 Grafana 创建漂亮的可视化仪表盘。

7.1 添加 Prometheus 数据源

（文字模拟截图提示：打开浏览器访问 http://your-server:3000，用户名 admin，密码 admin123 → 点击左侧菜单 Configuration → Data Sources → Add data source → 选择 Prometheus → URL 填写 http://prometheus:9090 → Save & Test）

7.2 创建 API 监控仪表盘

（文字模拟截图提示：点击左侧菜单 + → Create → Dashboard → Add new panel）

# Grafana Dashboard JSON 配置
{
  "dashboard": {
    "title": "HolySheep API 监控面板",
    "uid": "holysheep-api-monitor",
    "panels": [
      {
        "title": "API 可用率",
        "type": "stat",
        "gridPos": {"h": 8, "w": 6, "x": 0, "y": 0},
        "targets": [
          {
            "expr": "avg(probe_success{service=\"holysheep-api\"}) * 100",
            "legendFormat": "可用率"
          }
        ],
        "fieldConfig": {
          "defaults": {
            "unit": "percent",
            "thresholds": {
              "mode": "absolute",
              "steps": [
                {"color": "red", "value": null},
                {"color": "yellow", "value": 95},
                {"color": "green", "value": 99}
              ]
            }
          }
        }
      },
      {
        "title": "平均响应时间",
        "type": "timeseries",
        "gridPos": {"h": 8, "w": 12, "x": 6, "y": 0},
        "targets": [
          {
            "expr": "probe_duration_seconds{service=\"holysheep-api\"}",
            "legendFormat": "响应时间"
          }
        ],
        "fieldConfig": {
          "defaults": {
            "unit": "s"
          }
        }
      },
      {
        "title": "告警历史",
        "type": "table",
        "gridPos": {"h": 8, "w": 24, "x": 0, "y": 8},
        "targets": [
          {
            "expr": "ALERTS{alertname=~\".*API.*\"}",
            "format": "table"
          }
        ]
      }
    ]
  }
}

八、实战：测试告警功能

配置完成后，我们需要测试告警是否正常工作。我的经验是，每次配置完监控都要亲自测试一遍，不要等到真正出问题才发现告警没发出去。

8.1 模拟 API 不可用场景

# 方法1：使用 iptables 模拟网络中断（需要 root 权限）
sudo iptables -A INPUT -p tcp --dport 443 -d api.holysheep.ai -j DROP

等待2分钟，观察 Prometheus 是否触发告警
访问 http://your-server:9090 → Alerts 页面查看告警状态

恢复网络
sudo iptables -D INPUT -p tcp --dport 443 -d api.holysheep.ai -j DROP

方法2：使用错误的 API Key 触发认证失败
修改 prometheus.yml 中的 target，改为使用无效 Key

8.2 验证告警通知

# 检查 Alertmanager 是否收到告警
curl http://localhost:9093/api/v1/alerts

检查 Prometheus 告警状态
curl http://localhost:9090/api/v1/alerts | jq '.data.alerts[] | {name: .labels.alertname, state: .state}'

查看 Alertmanager 日志确认通知发送
docker-compose logs alertmanager | grep -i "notification"

九、常见报错排查

在配置过程中，你可能会遇到各种问题。我整理了最常见的3个错误及其解决方案，这些都是我踩过的坑。

错误1：Prometheus 无法连接 Blackbox Exporter

# 错误信息
Get "http://blackbox-exporter:9115/probe?target=...": dial tcp: lookup blackbox-exporter on 127.0.0.11:53: no such host

原因分析
这是 Docker 网络配置问题，Prometheus 容器无法解析 Blackbox Exporter 的主机名。

解决方案
1. 确保两个服务在同一个 Docker 网络中
2. 检查 docker-compose.yml 中的 networks 配置
3. 重新创建网络：
docker-compose down
docker network prune
docker-compose up -d

验证网络连接
docker exec prometheus ping blackbox-exporter

错误2：Alertmanager 告警一直处于 Pending 状态

# 错误信息
Alertmanager 页面显示告警状态为 "Pending" 而不是 "Firing"

原因分析
告警规则的 for 参数要求指标持续满足条件一段时间才会触发。如果时间不够长，就会一直处于 Pending。

解决方案
1. 检查告警规则的 for 参数设置
错误配置：for: 0m  # 立即触发，可能不稳定
- alert: APIEndpointDown
  expr: probe_success == 0
  for: 2m  # 正确：持续2分钟才触发

2. 等待足够时间让条件满足
3. 如果想快速测试，可以临时将 for 改为 0s：
- alert: APIEndpointDown
  expr: probe_success == 0
  for: 0s

4. 重新加载 Prometheus 配置：
curl -X POST http://localhost:9090/-/reload

错误3：邮件告警发送成功但收不到邮件

# 错误信息
Alertmanager 日志显示 "notify success" 但收件箱没有邮件

原因分析
这种情况通常是因为：
1. 邮件被误判为垃圾邮件
2. SMTP 配置使用了不支持的端口或加密方式
3. 发件邮箱开启了授权码验证

解决方案
1. 检查 Alertmanager 日志获取详细错误：
docker-compose logs alertmanager 2>&1 | grep -A5 "smtp"

2. 使用正确的 SMTP 配置（以 QQ 邮箱为例）：
global:
  smtp_smarthost: 'smtp.qq.com:587'  # 使用 587 端口（TLS）
  smtp_auth_username: '[email protected]'
  smtp_auth_password: 'your-auth-code'  # 不是邮箱密码，是授权码

3. 获取 QQ 邮箱授权码：
登录 QQ 邮箱 → 设置 → 账户 → POP3/SMTP服务 → 生成授权码

4. 检查垃圾邮件箱

5. 临时改用企业微信/钉钉告警，更可靠：
webhook_configs:
  - url: 'http://your-webhook-server/dingtalk'
    send_resolved: true

十、进阶：成本监控与优化

对于 HolySheep AI 这类按 token 计费的 API，成本监控同样重要。我来分享一个实用的成本监控方案。

10.1 添加 Token 使用量监控

# 在 Prometheus 中添加自定义指标采集脚本
~/monitoring/metrics.py

from prometheus_client import Counter, Histogram, Gauge, start_http_server
import requests
import time
import os

定义指标
TOKEN_USAGE = Counter('api_tokens_total', 'Total tokens used', ['model', 'api_key_hash'])
API_COST = Counter('api_cost_total', 'Total API cost in USD', ['model'])
REQUEST_LATENCY = Histogram('api_request_duration_seconds', 'API request latency')

HolySheep API 基础配置
BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = os.environ.get('HOLYSHEEP_API_KEY', 'YOUR_HOLYSHEEP_API_KEY')

2026年主流模型价格（来自 HolySheep 官方）
MODEL_PRICES = {
    'gpt-4.1': {'input': 2.0, 'output': 8.0},      # $/MTok
    'claude-sonnet-4': {'input': 3.0, 'output': 15.0},
    'gemini-2.5-flash': {'input': 0.35, 'output': 2.50},
    'deepseek-v3.2': {'input': 0.07, 'output': 0.42}
}

def collect_usage_metrics():
    """定期采集 API 使用量指标"""
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    try:
        # 获取使用量报告（假设 API 支持）
        response = requests.get(
            f"{BASE_URL}/usage",
            headers=headers,
            timeout=10
        )
        
        if response.status_code == 200:
            data = response.json()
            for item in data.get('data', []):
                model = item['model']
                prompt_tokens = item['prompt_tokens']
                completion_tokens = item['completion_tokens']
                
                prices = MODEL_PRICES.get(model, {'input': 0, 'output': 0})
                cost = (prompt_tokens / 1_000_000 * prices['input'] +
                        completion_tokens / 1_000_000 * prices['output'])
                
                TOKEN_USAGE.labels(model=model, api_key_hash='***').inc(prompt_tokens + completion_tokens)
                API_COST.labels(model=model).inc(cost)
                
    except Exception as e:
        print(f"Error collecting metrics: {e}")

if __name__ == '__main__':
    start_http_server(9091)  # 指标暴露端口
    while True:
        collect_usage_metrics()
        time.sleep(60)  # 每分钟采集一次

10.2 添加成本告警

# ~/monitoring/prometheus/rules/cost-alerts.yml
groups:
  - name: cost_alerts
    interval: 60s
    rules:
      # 日成本超过阈值告警
      - alert: DailyCostTooHigh
        expr: increase(api_cost_total[24h]) > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "API 日成本超过阈值"
          description: "过去24小时 API 成本已达 ${{ $value }}，超过 $100 阈值"

      # 某模型成本异常
      - alert: ModelCostAnomaly
        expr: increase(api_cost_total{model="deepseek-v3.2"}[1h]) > 10
        for: 5m
        labels:
          severity: info
        annotations:
          summary: "DeepSeek V3.2 成本较高"
          description: "DeepSeek V3.2 过去1小时成本 ${{ $value }}"

十一、总结与下一步

到这里，一套完整的 API 监控告警系统就搭建完成了。回顾一下我们做了什么：

✅ 安装了 Prometheus、Alertmanager、Grafana、Blackbox Exporter
✅ 配置了自动采集 HolySheep API 的健康指标
✅ 设置了多级别告警规则（Critical/Warning）
✅ 配置了邮件和钉钉告警通知
✅ 创建了可视化监控仪表盘
✅ 添加了成本监控与告警

我的经验是，监控系统不是一劳永逸的，需要根据业务实际情况持续优化告警阈值和通知策略。建议每周回顾一次告警记录，优化那些误报率高的规则。

如果你还没有 HolySheep AI 账号，建议先注册体验一下。这家平台的汇率优势非常明显（¥7.3=$1），而且国内直连延迟小于50ms，对于需要稳定调用 AI API 的团队来说是个不错的选择。

还有什么问题？欢迎在评论区留言，我会尽力解答。

👉 免费注册 HolySheep AI，获取首月赠额度

一、为什么你需要 API 监控

二、监控架构概览

三、环境准备与安装

3.1 安装 Docker 和 Docker Compose

启动 Docker 服务

验证安装

3.2 创建监控目录结构

查看目录结构

四、配置 Prometheus 采集 API 指标

4.1 创建 Prometheus 配置文件

4.2 创建告警规则文件

五、配置 Alertmanager 发送告警通知

5.1 Alertmanager 配置文件

5.2 钉钉 Webhook 集成（推荐）

六、编写 HolySheep API 调用脚本

6.1 创建 Python 监控脚本

HolySheep API 配置

6.2 创建完整的 Docker Compose 编排文件

6.3 配置 Blackbox Exporter

6.4 启动监控系统

查看容器运行状态

查看 Prometheus 日志

查看 Alertmanager 日志

七、Grafana 可视化配置

7.1 添加 Prometheus 数据源

7.2 创建 API 监控仪表盘

八、实战：测试告警功能

8.1 模拟 API 不可用场景

等待2分钟，观察 Prometheus 是否触发告警

访问 http://your-server:9090 → Alerts 页面查看告警状态

恢复网络

方法2：使用错误的 API Key 触发认证失败

修改 prometheus.yml 中的 target，改为使用无效 Key

8.2 验证告警通知

检查 Prometheus 告警状态

查看 Alertmanager 日志确认通知发送

九、常见报错排查

错误1：Prometheus 无法连接 Blackbox Exporter

原因分析

解决方案

验证网络连接

错误2：Alertmanager 告警一直处于 Pending 状态

原因分析

解决方案

错误配置：for: 0m # 立即触发，可能不稳定

错误3：邮件告警发送成功但收不到邮件

原因分析

解决方案

登录 QQ 邮箱 → 设置 → 账户 → POP3/SMTP服务 → 生成授权码

十、进阶：成本监控与优化

10.1 添加 Token 使用量监控

~/monitoring/metrics.py

定义指标

HolySheep API 基础配置

2026年主流模型价格（来自 HolySheep 官方）

10.2 添加成本告警

十一、总结与下一步

相关资源

相关文章

🔥 推荐使用 HolySheep AI

`修改 prometheus.yml 中的 target，改为使用无效 Key`