Pydantic Logfire 指标监控完全指南：从基础到高级应用

原创于 2025-06-12 09:10:07 发布 · 259 阅读

4 ·

CC 4.0 BY-SA版权

Pydantic Logfire 指标监控完全指南：从基础到高级应用

logfire Uncomplicated Observability for Python and beyond! 🪵🔥 项目地址: https://gitcode.com/gh_mirrors/lo/logfire

什么是应用指标监控？

在现代应用开发中，指标监控是系统可观测性的三大支柱之一（另外两个是日志和追踪）。Pydantic Logfire 提供了强大的指标收集功能，可以帮助开发者轻松获取应用运行时的关键数据。

指标监控的核心价值在于：

提供数值数据的聚合视图
展示随时间变化的趋势
帮助识别性能瓶颈和异常模式

系统指标：快速入门

对于刚接触指标监控的开发者，Pydantic Logfire 提供了开箱即用的系统指标功能。这些指标自动收集系统级信息，包括：

CPU 使用率
内存占用
磁盘 I/O
网络流量

启用系统指标无需额外配置，是快速建立应用监控基础的最佳起点。

自定义指标实战

当系统指标不能满足需求时，Pydantic Logfire 提供了多种自定义指标类型，每种类型针对不同的监控场景。

1. 计数器(Counter) - 记录事件发生次数

计数器是最基础的指标类型，适合记录只增不减的数值。典型应用场景包括：

import logfire

# 创建请求计数器
request_counter = logfire.metric_counter(
    'http_requests',
    unit='1',
    description='Total HTTP requests received'
)

# 在处理请求时递增计数器
def handle_request():
    request_counter.add(1)
    # 处理请求逻辑...

最佳实践建议：

为每个计数器指定有意义的名称
即使是无单位的计数器也应设置 unit='1'
添加清晰的描述信息

2. 直方图(Histogram) - 分析数值分布

直方图特别适合分析数值的分布情况，常用于性能监控：

response_time_histogram = logfire.metric_histogram(
    'api_response_time',
    unit='ms',
    description='API endpoint response time distribution'
)

# 记录API响应时间
def record_response_time(start_time):
    duration = (time.time() - start_time) * 1000  # 转换为毫秒
    response_time_histogram.record(duration)

直方图会自动计算以下统计信息：

平均值
百分位数(P50/P90/P99等)
最大值/最小值

3. 升降计数器(Up-Down Counter) - 跟踪可变数量

升降计数器可以增加也可以减少，适合跟踪资源使用情况：

active_connections = logfire.metric_up_down_counter(
    'db_connections',
    unit='1',
    description='Current active database connections'
)

def open_connection():
    # 连接建立时增加
    active_connections.add(1)

def close_connection():
    # 连接关闭时减少
    active_connections.add(-1)

4. 仪表(Gauge) - 捕获瞬时值

仪表用于记录当前时刻的数值，不会累积历史数据：

memory_usage = logfire.metric_gauge(
    'memory_usage',
    unit='MB',
    description='Current memory usage in megabytes'
)

def update_memory_usage():
    # 获取当前内存使用量
    used_mem = get_memory_usage()
    memory_usage.set(used_mem)

高级技巧：回调指标

对于需要定期采集的指标，Pydantic Logfire 提供了回调机制，可以自动按固定间隔采集数据。

CPU 使用率监控示例

import logfire
from opentelemetry.metrics import CallbackOptions, Observation

def cpu_usage_callback(options: CallbackOptions):
    # 实际项目中这里会读取/proc/stat或使用psutil等库
    cpu_percent = get_cpu_usage()  
    yield Observation(cpu_percent, {"core": "all"})

# 注册回调指标
logfire.metric_gauge_callback(
    'system.cpu.usage',
    unit='%',
    callbacks=[cpu_usage_callback],
    description='CPU usage percentage'
)

回调指标特别适合：