Pydantic/Logfire 手动追踪功能深度解析

Pydantic/Logfire 手动追踪功能深度解析

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

前言

在现代应用开发中，良好的日志和追踪系统对于问题诊断和性能优化至关重要。Pydantic/Logfire 提供了一套强大的手动追踪功能，帮助开发者构建结构化的日志系统。本文将深入解析 Logfire 的核心功能和使用技巧。

基础概念

1. Span（跨度）与 Trace（追踪）

Span 是 Logfire 中的基本追踪单元，代表一个具有明确开始和结束时间的操作。多个相关的 Span 组成一个 Trace（追踪），形成树状结构。

import time
import logfire

logfire.configure()

with logfire.span('数据库查询'):
    time.sleep(1)  # 模拟耗时操作
    logfire.info('查询用户数据')
    time.sleep(0.5)

这段代码会产生一个包含子日志的 Span，在控制台输出时会显示层级关系：

21:02:55.078 数据库查询
21:02:56.084  查询用户数据

2. 属性附加

Logfire 允许为 Span 和日志附加结构化数据：

logfire.info('用户登录', username='张三', ip='192.168.1.1')

这些属性会被存储为 JSON 格式，便于后续查询和分析。

高级功能

1. 动态属性设置

可以在 Span 执行过程中动态添加属性：

with logfire.span('计算任务') as span:
    result = complex_calculation()
    span.set_attribute('计算结果', result)

2. 消息与 Span 名称

Logfire 区分 Span 名称和显示消息：

# 推荐做法 - 低基数 Span 名称
logfire.info('处理订单 {order_id}', order_id=12345)

# 不推荐做法 - 高基数 Span 名称
logfire.info(f'处理订单 {order_id}')

3. f-string 智能处理

Python 3.11+ 中，Logfire 可以智能解析 f-string：

user = '李四'
logfire.info(f'欢迎用户 {user}')  # 自动转换为等效的模板形式

异常处理

1. 自动异常捕获

Span 会自动捕获未处理的异常：

with logfire.span('危险操作'):
    raise ValueError('操作失败')

2. 手动异常记录

对于已处理的异常，可以手动记录：

with logfire.span('安全操作') as span:
    try:
        risky_operation()
    except Exception as e:
        span.record_exception(e)
        handle_error(e)

函数级追踪装饰器

@logfire.instrument 装饰器简化了函数追踪：

@logfire.instrument('处理用户 {user_id}')
def process_user(user_id: int):
    # 函数体

日志级别管理

Logfire 支持多种日志级别：

logfire.debug('调试信息')
logfire.info('常规信息')
logfire.warn('警告信息')
logfire.error('错误信息')

Span 级别可以动态调整：

with logfire.span('关键操作') as span:
    if operation_failed:
        span.set_level('error')

最佳实践

1. Span 命名规范：使用低基数名称，便于过滤和分析
2. 异常处理：重要操作应记录所有异常，包括已处理的
3. 属性设计：附加有意义的上下文信息，但避免过大对象
4. 层级结构：合理组织 Span 层级，反映业务逻辑
5. 性能考量：生产环境中适当调整日志级别

结语

Pydantic/Logfire 的手动追踪功能为开发者提供了强大的日志结构化工具。通过合理使用 Span、Trace 和属性系统，可以构建出既易于阅读又便于分析的日志体系，大幅提升应用的可观测性和问题排查效率。

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