instrumentation

使用 Logfire 进行监控

何时使用此技能

在以下情况下调用此技能：

• 用户要求“添加 logfire”“添加可观测性”“添加追踪”或“添加监控”
• 用户想为应用添加结构化日志或追踪（Python、JS/TS 或 Rust）
• 用户在任何上下文中提到 Logfire
• 用户要求“添加日志”或“查看我的应用在做什么”
• 用户想监控 AI/LLM 调用（PydanticAI、OpenAI、Anthropic）
• 用户要求为 AI Agent 或 LLM 流水线添加可观测性

Logfire 的工作原理

Logfire 是一个基于 OpenTelemetry 构建的可观测性平台。它会采集应用中的追踪、日志和指标。Logfire 为 Python、JavaScript/TypeScript 和 Rust 提供原生 SDK，也支持通过 OpenTelemetry 接入任何语言。

此技能存在的原因是，Claude 往往会在一些细节上弄错 Logfire，尤其是 configure() 与 instrument_*() 调用的顺序、结构化日志语法，以及需要安装哪些额外依赖。这些细节很重要，因为配置错误可能会导致追踪数据悄无声息地丢失。

步骤 1：检测语言和框架

识别项目语言和可添加监控的库：

• Python：读取 pyproject.toml 或 requirements.txt。常见的可添加监控的库：FastAPI、httpx、asyncpg、SQLAlchemy、psycopg、Redis、Celery、Django、Flask、requests、PydanticAI。
• JavaScript/TypeScript：读取 package.json。常见框架：Express、Next.js、Fastify。还要检查是否使用了 Cloudflare Workers 或 Deno。
• Rust：读取 Cargo.toml。

然后按照下面对应语言的步骤操作。

---

Python

安装对应的 Extras

根据检测到的框架，安装带有相应 extras 的 logfire。每个添加监控的库都需要对应的 extra，否则运行时调用 instrument_*() 会因缺少依赖而失败。

uv add 'logfire[fastapi,httpx,asyncpg]'

可用 extras 的完整列表：fastapi、starlette、django、flask、httpx、requests、asyncpg、psycopg、psycopg2、sqlalchemy、redis、pymongo、mysql、sqlite3、celery、aiohttp、aws-lambda、system-metrics、litellm、dspy、google-genai。

配置并添加监控

此处的调用顺序很重要。logfire.configure() 会初始化 SDK，必须先于其他所有操作调用。instrument_*() 调用会向各个库注册钩子。如果在 configure() 之前调用 instrument_*()，钩子虽然会注册，但追踪数据不会发送到任何地方。

import logfire

# 1. Configure first - always
logfire.configure()

# 2. Instrument libraries - after configure, before app starts
logfire.instrument_fastapi(app)
logfire.instrument_httpx()
logfire.instrument_asyncpg()

放置规则：

• 将 logfire.configure() 放在应用入口点（main.py 或创建应用的模块）
• 每个进程中只调用 一次，不要放在请求处理程序或库代码中
• instrument_*() 调用紧跟在 configure() 之后
• Web 框架的插桩器（instrument_fastapi、instrument_flask、instrument_django）需要将应用实例作为参数。HTTP 客户端和数据库插桩器（instrument_httpx、instrument_asyncpg）是全局的，无需传入参数。
• 在 Gunicorn 部署中，将 logfire.configure() 放在 post_fork 钩子中，而不是模块级别；每个 worker 都是独立进程

结构化日志

将 print() 和 logging.*() 调用替换为 Logfire 的结构化日志。关键模式：使用带关键字参数的 {key} 占位符，切勿使用 f-string。

# Correct - each {key} becomes a searchable attribute in the Logfire UI
logfire.info("Created user {user_id}", user_id=uid)
logfire.error("Payment failed {amount} {currency}", amount=100, currency="USD")

# Wrong - creates a flat string, nothing is searchable
logfire.info(f"Created user {uid}")

若要将相关操作分组并测量耗时，请使用 spans：

with logfire.span("Processing order {order_id}", order_id=order_id):
    items = await fetch_items(order_id)
    total = calculate_total(items)
    logfire.info("Calculated total {total}", total=total)

处理异常时，使用 logfire.exception() 自动捕获回溯信息：

try:
    await process_order(order_id)
except Exception:
    logfire.exception("Failed to process order {order_id}", order_id=order_id)
    raise

AI/LLM 插桩（Python）

Logfire 会自动为 AI 库添加插桩，以采集 LLM 调用、令牌用量、工具调用和 Agent 运行情况。

uv add 'logfire[pydantic-ai]'
# or: uv add 'logfire[openai]' / uv add 'logfire[anthropic]'

可用的 AI extras：pydantic-ai、openai、anthropic、litellm、dspy、google-genai。

logfire.configure()
logfire.instrument_pydantic_ai()  # captures agent runs, tool calls, LLM request/response
# or:
logfire.instrument_openai()       # captures chat completions, embeddings, token counts
logfire.instrument_anthropic()    # captures messages, token usage

对于 PydanticAI，每次 Agent 运行都会成为一个父 span，其中包含每次工具调用和 LLM 请求对应的子 span。

---

JavaScript / TypeScript

安装

# Node.js
npm install @pydantic/logfire-node

# Cloudflare Workers
npm install @pydantic/logfire-cf-workers logfire

# Next.js / generic
npm install logfire

配置

Node.js（Express、Fastify 等） —— 创建一个在应用前加载的 instrumentation.ts：

import * as logfire from '@pydantic/logfire-node'
logfire.configure()

使用以下命令启动：node --require ./instrumentation.js app.js

SDK 会在应用前加载时自动检测常用库。请在环境中设置 LOGFIRE_TOKEN，或将 token 传入 configure()。

Cloudflare Workers —— 使用 instrument() 包装处理程序：

import { instrument } from '@pydantic/logfire-cf-workers'

export default instrument(handler, {
  service: { name: 'my-worker', version: '1.0.0' }
})

Next.js —— 设置用于 OpenTelemetry 导出的环境变量：

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-write-token>

结构化日志（JS/TS）

// Structured attributes as second argument
logfire.info('Created user', { user_id: uid })
logfire.error('Payment failed', { amount: 100, currency: 'USD' })

// Spans
logfire.span('Processing order', { order_id }, {}, async () => {
  logfire.info('Processing step completed')
})

// Error reporting
logfire.reportError('order processing', error)

日志级别：trace、debug、info、notice、warn、error、fatal。

---

Rust

安装

[dependencies]
logfire = "0.6"

配置

let shutdown_handler = logfire::configure()
    .install_panic_handler()
    .finish()?;

请在环境中设置 LOGFIRE_TOKEN，或使用 Logfire CLI 选择项目。

结构化日志（Rust）

Rust SDK 基于 tracing 和 opentelemetry 构建，现有的 tracing 宏会自动生效。

// Spans
logfire::span!("processing order", order_id = order_id).in_scope(|| {
    // traced code
});

// Events
logfire::info!("Created user {user_id}", user_id = uid);

程序退出前务必调用 shutdown_handler.shutdown()，以刷新数据。

---

验证

完成检测后，请验证设置是否生效：

1. 运行 logfire auth 检查身份验证（或设置 LOGFIRE_TOKEN）
2. 启动应用并触发一个请求
3. 前往 https://logfire.pydantic.dev/ 检查追踪

如果未显示追踪：请检查是否在调用 instrument_*()（Python）前调用了 configure()，检查是否设置了 LOGFIRE_TOKEN，并确认已安装正确的包和额外依赖。

参考资料

按语言整理的详细用法模式和集成表：

• Python：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/logging-patterns.md（日志级别、跨度、标准库集成、指标、capfire 测试）和 ${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/integrations.md（包含额外依赖的完整检测器表）
• JavaScript/TypeScript：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/patterns.md（日志级别、跨度、错误处理、配置）和 ${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/frameworks.md（Node.js、Cloudflare Workers、Next.js、Deno 设置）
• Rust：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/rust/patterns.md（宏、跨度、tracing/log crate 集成、异步、关闭）