Polar 后端 Sentry 问题全链路排查与修复实战从 correlation_id 关联 Logfire 到 Worktree 提交 PR【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar本文基于 Polar 开源仓库的.agents/skills/fix-sentry/SKILL.md技能文档完整还原 Polar 团队在日常开发中排查与修复 Sentry 上报问题的标准工作流先用 sentry_polar 工具定位错误与堆栈再以correlation_id为纽带关联 Logfire 全链路日志随后回到源码搜索根因、形成假设最后在独立 git worktree 中实现修复并通过 GitHub 工具提交 PR。读完本文你将掌握一套可复用的“可观测性数据交叉验证 源码定位 隔离开发”的线上问题修复方法论。技能定位谁在什么场景下使用 fix-sentry在 Polar 仓库中fix-sentry是一个面向 AI Agent 的 Claude Code 技能Skill其元信息定义在 .agents/skills/fix-sentry/SKILL.md 的文件头 Frontmatter 中--- name: fix-sentry description: Analyze and fix issues reported by Sentry in the Polar codebase. user-invocable: true allowed-tools: Bash(gh:*) Bash(git:*) logfire_polar* sentry_polar* github* ---description明确技能职责是“分析并修复 Polar 代码库中由 Sentry 上报的问题”user-invocable: true用户可直接显式调用该技能allowed-tools技能运行期间被允许使用的工具集合包括 GitHub CLIgh:*、Git 命令git:*、Logfire 相关工具logfire_polar*、Sentry 相关工具sentry_polar*以及 GitHub 工具github*。这说明整个流程依赖四类能力Sentry 数据访问、Logfire 日志检索、源码检索、GitHub 协作。技能文档对执行者Agent的要求是调查 Sentry 报告、识别问题根因、并实施修复以解决问题。整个流程被拆解为 5 个明确步骤下面逐一展开。第一步确定输入 —— 获取 Sentry Issue ID技能在执行前需要拿到一个 Sentry Issue ID 或 Sentry Issue 链接。如果调用提示invocation prompt中没有提供应当主动向用户询问以便访问问题详情并开始分析。Polar 在 Sentry 中的组织标识是两个固定值Organization ID4505046560538624Slugpolar-sh这两个标识在技能的所有sentry_polar工具调用中作为组织维度参数使用。第二步分析 Sentry IssueStep 1使用sentry_polar工具访问用户提供的 Sentry Issue 详情。技能要求获取的信息包括错误消息error message堆栈追踪stack trace与该问题关联的附加上下文或元数据additional context / metadataSentry 报告往往只是“症状”包含发生位置与调用栈但缺少业务链路上下文。因此下一步必须借助日志系统还原“来龙去脉”。第三步关联 Logfire 日志Step 2—— correlation_id 的妙用技能要求从 Sentry Issue 中提取correlation_id标签tag若存在则用它到 Logfire 中检索关联日志从而获得问题发生前的事件上下文帮助理解根因。检索子句形式如下attributes-correlation_id correlation_id注意如果检索到的日志中带有source_correlation_id也需要一并查询这些日志。它代表“来源方”的关联 ID典型场景是后台任务由某次 HTTP 请求触发时任务日志会保留请求的source_correlation_id。correlation_id 从何而来中间件与后台任务correlation_id并不是 Sentry 或 Logfire 自动生成的而是 Polar 在请求入口主动注入的。核心实现在 server/polar/middlewares.py 的LogCorrelationIdMiddlewareasync def __call__(self, scope: Scope, receive: Receive, send: Send) - None: if scope[type] ! http: return await self.app(scope, receive, send) correlation_id CorrelationID.set() structlog.contextvars.bind_contextvars( correlation_idcorrelation_id, methodscope[method], pathscope[path] ) sentry_sdk.set_tag(correlation_id, correlation_id) ...该中间件在每次 HTTP 请求进入时调用CorrelationID.set()生成一个新的 UUIDstr(uuid.uuid4())CorrelationID类定义在 server/polar/logging.py内部基于contextvars.ContextVar(polar.correlation_id)实现请求级线程上下文隔离通过sentry_sdk.set_tag(correlation_id, correlation_id)写入 Sentry 标签——这就是 Sentry Issue 上correlation_id标签的来源通过logfire.set_baggage(correlation_idcorrelation_id)写入 OpenTelemetry baggage并直接为 OTel 根 Span 设置correlation_id属性注释说明根 Span 由更早执行的 OTel ASGI 中间件创建baggage 不会被自动拾取因此必须显式root_span.set_attribute(correlation_id, correlation_id)同时绑定 structlog 上下文使应用日志也携带correlation_id、method、path。该中间件还会捕获移动端 App 发送的x-polar-client-version、x-polar-client-runtime、x-polar-client-update三个请求头作为client_version、client_runtime、client_update标签同步写入 structlog、Sentry 与根 Span用于按客户端构建版本追溯兼容性问题。请求结束后在finally中统一清理上下文。后台任务侧同样会生成correlation_id。在 server/polar/worker/_runner.py 的任务执行器_run_async中correlation_id CorrelationID.set() structlog.contextvars.bind_contextvars( actor_nameactor_name, correlation_idcorrelation_id, source_correlation_idsource_correlation_id, ) ... with _task_span(actor_name, message, correlation_id, source_correlation_id): ...任务执行时会生成新的correlation_id同时把触发来源的source_correlation_id若任务由请求派发而来一并绑定并在 Logfire 的_task_span中同时记录这两个 ID。这正是技能要求“同时查询source_correlation_id日志”的原因——它可以帮你从后台任务回溯到发起它的那次 HTTP 请求。Logfire 侧的检索依据correlation_id之所以能在 Logfire 中被 SQL 检索是因为 server/polar/logfire.py 中configure_logfire完成了 OpenTelemetry 导出配置。该模块值得注意的细节包括采样控制通过自定义IgnoreSampler过滤掉/healthz健康检查与 worker 心跳类 Span_healthz_matcher、_worker_health_matcher再叠加LevelSampler按settings.LOG_LEVEL过滤低级别日志脱敏scrubbing_scrubbing_callback明确豁免subject、thread_stacks、event_loop_stack、asyncio_tasks等路径防止误伤认证主体与事件循环栈中的session字样S3 导出当配置了S3_LOGS_BUCKET_NAME时会通过S3SpanExporter以 2048 条/批、60 秒延迟的节奏把 Span 批量导出到 S3并提供email、user.name、phone、address、ip_address、cookie、http.url等模式的脱敏规则。第四步搜索源码Step 3利用从 Sentry Issue 与 Logfire 日志中获得的信息回到代码库中检索相关代码。技能建议的检索维度包括具体的错误消息文本error messages函数名function names其他相关关键词relevant keywords在 Polar 仓库中可优先在 server/polar 目录下按业务模块检索如checkout/、subscription/、benefit/、webhook/等或直接搜索唯一性强的标识符。由于 structlog 日志、Sentry 标签与 Logfire Span 都携带correlation_id你甚至可以先用correlation_id本身在代码库中检索定位中间件、日志绑定与任务执行等关键链路。第五步分析发现形成根因假设Step 4综合 Sentry Issue、Logfire 日志与源码检索三方面的信息综合归纳synthesize后对问题根因形成一个假设hypothesis。一个典型的排查闭环示例Sentry 报告某接口抛错并给出堆栈附带correlation_id标签用attributes-correlation_id correlation_id在 Logfire 中拉出该请求的完整 Span 序列与前后日志发现数据库查询超时或某外部 API 调用失败回到源码检索堆栈中的函数名确认失败点所在模块与调用参数最终假设例如“某个枚举值未处理导致状态机走到非法分支”或“未对空列表做防御性判空”。假设形成后进入修复阶段。第六步实施修复Step 5技能在此处设置了一条重要边界重要如果分析表明问题涉及重度架构变更heavy architectural changes或者你不确定最佳修复方案不要自行实施修复。此时应在polarsource/polar上开一个 Issue附上你的发现与分析结果。只有确认是局部、可控的修复时才走下述 4 个子步骤。Step 5.1创建独立 Worktree强制始终先为要开展的工作创建 git worktree使改动与主代码库隔离直到准备合并。运行./dev/create-worktree branch-namebranch-name必须是仅由小写字母、数字和下划线组成的描述性名称脚本强制校验^[a-z0-9_]$不合法会直接报错退出Worktree 创建在仓库的.worktrees目录下技能文档写作./worktrees以脚本实际实现 dev/create-worktree 为准之后用以下命令进入cd .worktrees/branch-name从脚本实现看dev/create-worktree实际做了三件事git worktree add .worktrees/name创建独立工作目录在本地 PostgreSQL 中为本次开发创建独立数据库polar_dev_name若不存在PGPASSWORD$password psql -h $host -U $user -d postgres -tAc \ SELECT 1 FROM pg_database WHERE datname$db_name | grep -q 1在新 worktree 中运行./dev/cli/dev up --skip-integrations --database-name $db_name完成带独立数据库的环境初始化--skip-integrations跳过集成依赖--database-name指向新库。IMPORTANT从此刻起所有修改与命令都必须在刚创建的 worktree 上下文内执行以保证改动隔离、易于管理。Step 5.2实现修复基于分析结论实施修复可能涉及修改现有代码新增代码配置变更提交前必须按仓库 AGENTS.md 的约定执行检查即运行lint代码检查、类型检查type checking与测试tests。Step 5.3提交变更把改动提交到 worktree 中创建的本地分支。提交信息要求清晰且有描述性既要说明改了什么也要说明为什么这么改reason for those changes。Step 5.4打开 Pull Request使用github工具在polarsource/polar上打开 PRPR 描述中需要详述分析过程your analysis附上 Sentry Issue 与 Logfire 日志的相关链接说明为修复问题所做的改动。这样既为 reviewer 提供了完整证据链也便于后续回溯。与可观测性基础设施的联动Sentry 侧的代码佐证技能流程中的sentry_polar工具所读到的 Issue 数据最终都来自 server/polar/sentry.py 的configure_sentry初始化逻辑。理解其配置有助于判断哪些 Issue 值得跟进def configure_sentry(*, aws_lambda: bool False) - None: sentry_sdk.init( dsnsettings.SENTRY_DSN, traces_sample_rateNone, # 0 仍会参与 trace continuation profiles_sample_rateNone, releaseos.environ.get(RELEASE_VERSION, development), server_nameos.environ.get(RENDER_INSTANCE_ID, localhost), environmentsettings.ENV, default_integrationsFalse, auto_enabling_integrationsFalse, before_sendbefore_send, integrations[...], )几个直接影响排查体验的关键点before_send过滤若事件 tags 中is_operational_error为true事件会被直接丢弃返回None。这意味着你在 Sentry 上看到的 Issue 已经排除了被标记为“操作性错误”的事件聚焦真正的代码缺陷Integration 组合同时启用StarletteIntegration与FastApiIntegrationSentry 官方 FastAPI 文档明确要求两者都装transaction_styleendpoint让事务名以接口端点命名DramatiqIntegration为 Polar 自定义子类用于在 broker 已初始化后才注入SentryMiddlewareAWS Lambda 环境会追加AwsLambdaIntegration用户身份关联set_sentry_user在已登录用户请求中写入sentry_sdk.set_user({id: ..., email: ...})并额外设置posthog_distinct_id标签server/polar/sentry.py便于把错误关联到具体用户会话日志面包屑LoggingIntegration(levellogging.INFO, event_levelNone)会把 INFO 及以上日志作为 breadcrumbs 附加到事件配合correlation_id标签可以在 Sentry Issue 详情页直接看到请求链路关键日志。完整流程速查步骤动作关键工具/命令产物输入获取 Sentry Issue ID 或链接询问用户org id4505046560538624/ slugpolar-shIssue 标识Step 1分析 Sentry Issuesentry_polar错误消息、堆栈、上下文Step 2关联 Logfire 日志logfire_polarattributes-correlation_id correlation_id请求/任务链路上下文Step 3搜索源码源码检索错误文本/函数名/关键词相关代码片段Step 4分析发现综合三路信息根因假设Step 5.1创建 worktree./dev/create-worktree branch-name.worktrees/branch-name隔离环境Step 5.2实现修复修改代码 lint/类型/测试见 AGENTS.md修复代码Step 5.3提交变更git commit描述性提交Step 5.4打开 PRgithub工具含分析、Sentry/Logfire 链接的 PR注意事项与最佳实践小结重大变更先开 Issue涉及重度架构调整或对修复方案不确定时绝不盲目动手应先在polarsource/polar开 Issue 并附上分析隔离开发一切改动在 worktree 中完成主代码库保持干净便于多任务并行与安全合并证据链完整PR 中必须附带 Sentry Issue 链接、Logfire 日志链接与分析过程这是 Polar 团队可观测性工作流的核心纪律双向追溯HTTP 请求通过LogCorrelationIdMiddleware生成correlation_id并注入 Sentry/Logfire/structlog后台任务在 server/polar/worker/_runner.py 中生成新correlation_id并保留source_correlation_id。排查时两条链路都要查才能还原完整事件因果。【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
