logs-python

Python 的 PostHog 日志

此技能可帮助你为 Python 应用添加 PostHog 日志摄取。

参考文件

• references/python.md - Python 日志安装 - 文档
• references/start-here.md - 日志入门 - 文档
• references/search.md - 搜索日志 - 文档
• references/best-practices.md - 日志记录最佳实践 - 文档
• references/troubleshooting.md - 日志故障排查 - 文档
• references/link-session-replay.md - 关联会话回放 - 文档
• references/debug-logs-mcp.md - 使用 mcp 调试日志 - 文档

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

关键原则

• 环境变量：始终使用环境变量配置 PostHog 密钥和 OpenTelemetry 端点。切勿将其硬编码。
• 尽量少改动：在现有日志记录旁添加日志导出。不要替换或重构现有日志记录代码。
• OpenTelemetry：PostHog 日志使用 OpenTelemetry 协议。请配置一个指向 PostHog 摄取端点的 OTLP 导出器。
• 结构化日志：优先使用包含键值属性的结构化日志格式，而非纯文本消息。

框架指南

• 请记住，源代码位于 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)