Python项目监控指标设计需覆盖存活性、资源消耗、业务逻辑、内部状态四类指标，采用Prometheus语义化命名与多维标签，分层埋点延迟与错误，并用prometheus_client+psutil轻量落地。
Python项目监控指标设计，核心是围绕“运行状态是否健康、问题能否快速定位、趋势是否可预测”这三点展开。不是堆砌指标，而是选对指标、打上合理标签、设定有效阈值、配合可视化与告警。
关键运行状态指标必须覆盖这四类
一个Python服务（如Flask/FastAPI后台、Celery任务、数据处理脚本）的运行状态，至少要采集以下四类基础指标：
-
存活性指标：进程是否在运行（如通过
psutil.pid_exists()或HTTP探针返回200）、启动时间、Uptime秒数； - 资源消耗指标：CPU使用率（按进程而非整机）、内存RSS（避免只看%被共享内存干扰）、线程/协程数、打开文件描述符数；
- 业务逻辑指标：请求量（QPS）、响应延迟（P50/P95/P99）、错误率（HTTP 4xx/5xx、自定义异常捕获数）、任务积压量（如Redis队列长度、Celery active queues size）；
- 内部状态指标：数据库连接池使用率、缓存命中率（Redis/Memcached）、日志ERROR/WARN频次（结构化日志+计数器）、配置热加载是否成功标记。
指标命名与标签设计要“能查、能分、能比”
不推荐用api_response_time_ms这种模糊名，而应采用Prometheus风格的语义化命名+多维标签：
- 命名示例：
python_http_request_duration_seconds_bucket（直指用途+单位+类型）； - 必带标签：
app_name（服务名）、env（prod/staging）、endpoint（如/v1/user）、method（GET/POST）、status_code； - 慎用高基数标签：如
user_id或原始request_id会导致存储爆炸，改用user_type=premium或region=cn-east等聚合维度。
延迟与错误指标要区分“可观测层级”
同一接口的延迟，在不同环节意义不同，需分层埋点：
立即学习“Python免费学习笔记（深入）”；
- 入口层延迟：从WSGI/ASGI收到请求到开始写响应头的时间（含反向代理转发耗时），反映整体链路压力；
-
业务层延迟：进入视图函数后，到调用DB/API前的纯Python执行时间（可用
contextvars或装饰器隔离）； -
依赖层延迟：单独记录SQL执行时间、HTTP外部调用耗时、Redis命令耗时，并打上
db_name、upstream_host等标签； - 错误同理：区分
client_error（4xx，参数校验失败）、server_error（5xx，DB连不上/空指针）、timeout_error（requests超时），各自独立计数并告警。
轻量级实现：用red">prometheus_client + psutil快速落地
无需引入复杂APM，几行代码就能暴露核心指标：
- 安装：
pip install prometheus-client psutil； - 在应用启动时注册指标：
from prometheus_client import Counter, Histogram, Gauge
from psutil import Process
# 定义
HTTP_REQUESTS_TOTAL = Counter('http_requests_total', 'Total HTTP Requests', ['method', 'endpoint', 'status_code'])
HTTP_REQUEST_DURATION = Histogram('http_request_duration_seconds', 'HTTP Request Duration', ['endpoint'])
PROCESS_MEMORY_MB = Gauge('process_memory_mb', 'Process Memory Usage (MB)') - 在中间件或信号钩子中更新：
@app.middleware('http')
async def record_metrics(request, call_next):
start = time.time()
response = await call_next(request)
duration = time.time() - start
HTTP_REQUEST_DURATION.labels(endpoint=request.url.path).observe(duration)
HTTP_REQUESTS_TOTAL.labels(
method=request.method,
endpoint=request.url.path,
status_code=str(response.status_code)
).inc()
return response - 定时刷新资源指标：
def collect_system_metrics():
p = Process()
PROCESS_MEMORY_MB.set(p.memory_info().rss / 1024 / 1024)
配合BackgroundTasks或APScheduler每10秒执行一次。
