error-tracking-python

Python 的 PostHog 错误跟踪

此技能可帮助你为 Python 应用添加 PostHog 错误跟踪。

参考文件

• references/python.md - Python 错误跟踪安装 - 文档
• references/fingerprints.md - 指纹 - 文档
• references/alerts.md - 发送错误跟踪警报 - 文档
• references/monitoring.md - 监控和搜索问题 - 文档
• references/assigning-issues.md - 将问题分配给团队成员 - 文档
• references/upload-source-maps.md - 上传源映射 - 文档

请查阅文档，了解 API 详情和特定框架的模式。

关键原则

• 环境变量：始终使用环境变量配置 PostHog 密钥和主机 URL。切勿将它们硬编码。
• 尽量少改动：在现有错误处理中添加错误跟踪。不要替换或重构现有错误处理代码。
• 优先启用自动捕获：在 SDK 初始化时启用异常自动捕获，然后再添加手动捕获。
• 源映射：上传源映射，以便堆栈跟踪能解析到原始源代码，而不是压缩后的代码包。
• 在边界处手动捕获：对于不会传递给全局处理程序的错误，请在错误边界和 catch 块中使用 captureException()。

框架指南

• 请记住，源代码位于 venv/site-packages 目录中
• posthog 是 Python SDK 的包名
• 使用 pip install posthog 或 pip install -r requirements.txt 安装依赖项，切勿在 Shell 命令中直接使用未加引号的版本说明符，例如 >=
• 在 CLI 和脚本中：必须在退出前调用 posthog.shutdown()，否则所有事件都会丢失
• 始终使用 Posthog() 类构造函数（基于实例的 API），而不是模块级别的 posthog.api_key 配置
• 始终在 Posthog() 构造函数中添加 enable_exception_autocapture=True，以自动跟踪异常
• 绝不在 capture() 事件属性中发送 PII——包括电子邮件、全名、电话号码、实际地址、IP 地址或用户生成的内容
• PII 应放在 identify() 人员属性中，而不是 capture() 事件属性中。安全的事件属性包括 message_length、form_type 和布尔标志等元数据。
• 使用 atexit.register() 注册 posthog_client.shutdown，以确保退出时刷新所有事件
• Python SDK 没有 identify() 方法——请使用 posthog_client.set(distinct_id=user_id, properties={...}) 设置人员属性，或在上下文中使用 identify_context(user_id)