sentry-setup-logging

设置 Sentry 日志记录

配置 Sentry 的结构化日志功能。

在以下情况下调用此技能

• 用户询问“设置 Sentry 日志记录”或“在 Sentry 中捕获日志”
• 用户希望将日志库（Pino、Winston、Loguru）集成到 Sentry
• 用户询问 Sentry.logger 或 sentry_sdk.logger

**重要提示：**以下 SDK 版本、API 名称和代码示例仅供参考。实施前，请务必对照 docs.sentry.io 进行验证，因为 API 和最低版本要求可能已发生变化。

快速参考

平台	最低 SDK 版本	启用标记	日志记录器 API
JavaScript	9.41.0+	enableLogs: true	Sentry.logger.*
Python	2.35.0+	enable_logs=True	sentry_sdk.logger.*
Ruby	5.24.0+	config.enable_logs = true	Sentry.logger.*

JavaScript 设置

1. 验证 SDK 版本

grep -E '"@sentry/(nextjs|react|node|browser)"' package.json

2. 在 Sentry.init() 中启用

Sentry.init({
  dsn: "YOUR_DSN",
  enableLogs: true,
});

3. 捕获控制台输出（可选）

integrations: [
  Sentry.consoleLoggingIntegration({ levels: ["warn", "error"] }),
],

4. 使用结构化日志记录

Sentry.logger.info("User logged in", { userId: "123" });
Sentry.logger.error("Payment failed", { orderId: "456", amount: 99.99 });

// Template literals (creates searchable attributes)
Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName}`);

第三方集成

库	集成方式	最低 SDK 版本
Consola	Sentry.createConsolaReporter()	10.12.0+
控制台捕获	Sentry.consoleLoggingIntegration()	10.13.0+

Python 设置

1. 验证 SDK 版本

pip show sentry-sdk | grep Version

2. 在 init() 中启用

sentry_sdk.init(
    dsn="YOUR_DSN",
    enable_logs=True,
)

3. 捕获标准库 logging（可选）

from sentry_sdk.integrations.logging import LoggingIntegration
integrations=[LoggingIntegration(sentry_logs_level=logging.INFO)]

4. 使用结构化日志记录

from sentry_sdk import logger as sentry_logger

sentry_logger.info("User logged in: {user_id}", user_id="123")
sentry_logger.error("Payment failed", order_id="456", amount=99.99)

Loguru 集成

from sentry_sdk.integrations.loguru import LoguruIntegration
integrations=[LoguruIntegration(sentry_logs_level=LoggingLevels.INFO.value)]

Ruby 设置

1. 验证 SDK 版本

bundle show sentry-ruby

2. 在 init 中启用

Sentry.init do |config|
  config.dsn = "YOUR_DSN"
  config.enable_logs = true
  config.enabled_patches << :logger  # Optional: capture stdlib Logger
end

3. 使用结构化日志记录

Sentry.logger.info("User logged in")
Sentry.logger.error("Payment failed. Order: %{order_id}", order_id: "456")

日志过滤

JavaScript

beforeSendLog: (log) => log.level === "info" ? null : log,

Python

def before_send_log(log, hint):
    return None if log["severity_text"] == "info" else log

验证

启用日志后，输出一条测试日志，并检查 Sentry Logs 仪表板（Explore > Logs）：

Sentry.logger.info("Sentry logging test");

故障排除

问题	解决方案
未显示日志	验证 SDK 版本，并检查是否已设置 enableLogs/enable_logs
日志过多	使用 beforeSendLog 进行过滤，并减少捕获的日志级别
未捕获控制台输出	将 consoleLoggingIntegration 添加到 integrations 数组