Logfire项目中的手动追踪功能详解

Logfire作为一款强大的日志和追踪工具，提供了灵活的手动追踪功能，帮助开发者更好地理解和监控应用程序的执行流程。本文将深入介绍Logfire中的核心追踪概念和使用方法。

追踪与跨度基础

在Logfire中，追踪(Trace)和跨度(Span)是两个核心概念。一个追踪代表一个完整的请求或事务处理过程，而跨度则代表其中的一个具体操作单元。追踪本质上是由多个跨度组成的树状结构，其中根跨度就是追踪的起点。

with logfire.span('处理用户请求'):
    logfire.info('开始处理数据')
    time.sleep(1)
    logfire.info('数据处理完成')

在这个例子中，logfire.span创建了一个跨度，其中包含两条日志信息。在Logfire的可视化界面中，你可以看到日志信息被嵌套在跨度内部，形成清晰的层级关系。

属性记录

Logfire允许你为日志和跨度添加自定义属性，这些属性会被记录并可用于后续查询：

logfire.info('用户登录', username='alice', role='admin')

记录后，你可以使用类似attributes->>'username' = 'alice'的查询条件来筛选特定属性的记录。对于跨度，你还可以动态添加属性：

span = logfire.span('处理订单')
span.set_attribute('order_id', 12345)

命名与消息

Logfire区分了跨度名称和消息内容。名称用于分组和聚合，应该保持低基数(即不要有太多唯一值)，而消息可以包含具体细节：

for name in ['Alice', 'Bob', 'Charlie']:
    logfire.info(f'问候用户 {name}', name=name)

在这个例子中，日志消息包含了具体用户名，但如果你使用相同的模式作为跨度名称，可能会导致性能问题。Logfire提供了多种方式控制名称和消息：

1. 使用_span_name参数显式指定
2. 通过span.message属性动态修改
3. 利用f-string魔法自动处理

便捷装饰器

对于函数级别的追踪，Logfire提供了便捷的装饰器：

@logfire.instrument
def process_data(data):
    # 函数执行会自动被记录为一个跨度
    ...

异常处理

Logfire能够自动捕获并记录跨度中的异常：

with logfire.span('危险操作'):
    try:
        risky_operation()
    except Exception:
        logfire.exception('操作失败')
        raise

你也可以手动记录异常：

span.record_exception(exc)

日志级别

Logfire支持标准的日志级别(DEBUG, INFO, WARNING, ERROR等)。你可以通过多种方式控制级别：

logfire.warning('警告信息')
span.set_level('error')  # 提升跨度级别

在Logfire界面中，你可以使用类似level > level_num('info')的查询来筛选特定级别的记录。当跨度中发生未捕获的异常时，其级别会自动提升为ERROR。

通过合理使用这些手动追踪功能，开发者可以获得对应用程序行为的深入洞察，快速定位性能瓶颈和错误源头。Logfire的设计既考虑了灵活性，又保持了使用的简洁性，是现代化应用监控的有力工具。