mcpField
I
instrument-logs

instrument-logs

github.com/posthog开发76460 次安装今天更新
代码仓库

关于 instrument-logs

用于为代码库添加 PostHog 日志采集的开发技能，适用于实现功能或审查 PR 的开发者。它根据平台指导配置 OpenTelemetry 导出，并在现有日志系统旁添加结构化日志采集。

主要功能

  1. 01检测语言、框架与日志配置
  2. 02配置 OTLP 导出器
  3. 03与现有日志处理器并行集成
  4. 04添加结构化键值属性
  5. 05提供平台专属配置参考

适用场景

  1. 01为新功能添加 PostHog 日志采集
  2. 02在不替换现有日志的情况下配置导出
  3. 03为日志补充便于筛选的结构化属性

MCP 相关

技能可使用 PostHog MCP 服务的 `projects-get` 工具获取项目 API 令牌。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill instrument-logs

安装后在 Claude Code 中输入/instrument-logs确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
android.md
best-practices.md
COMMANDMENTS.md
datadog.md
flutter.md
go.md
ios.md
java.md
link-session-replay.md
mcp.md
nextjs.md
nodejs.md
other.md
python.md
react-native.md
search.md
start-here.md
troubleshooting.md

详细介绍

添加 PostHog 日志采集

使用此技能为新增或修改的代码添加 PostHog 日志采集。在实现功能或审查 PR 后使用此技能，确保采集到包含结构化属性的有效日志事件。如果尚未配置 PostHog 日志导出，此技能也涵盖 OTLP 导出器的初始设置。支持任何平台或语言。

支持的平台：Next.js、Node.js、Python、Go、Java、Datadog、Android、React Native、iOS，以及通过 OpenTelemetry 支持的任何语言。

说明

请按顺序执行以下步骤：

步骤 1：分析代码库并检测平台。

  • 检测语言、框架和现有日志设置。
  • 查找依赖文件和项目文件（package.json、Podfile、Package.swift、requirements.txt、go.mod、pom.xml 等）。
  • 查找日志库（winston、pino、logging module、logrus、log4j、serilog、os_log、Logger 等）。
  • 查找锁定文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、Podfile.lock、Package.resolved 等），以确定包管理器。
  • 检查是否已设置 PostHog 日志导出。如果已配置 OTLP 导出器，则跳到步骤 5，为新代码添加日志捕获。

步骤 2：研究日志捕获。（如果已配置 PostHog 日志导出，则跳过。） 2.1. 找到下方与检测到的平台匹配的参考文件——它是 OTLP 导出器配置以及与现有日志集成方式的权威依据。现在阅读该文件。 2.2. 如果没有匹配的参考文件，则使用“其他语言”参考文件作为备用方案——其中介绍了通用的 OpenTelemetry 方法。

步骤 3：安装依赖项。（如果已配置 PostHog 日志导出，则跳过。）

  • 为检测到的平台安装 OpenTelemetry SDK 和 OTLP 导出器包。
  • 不要手动编辑依赖文件——请使用包管理器的安装命令。

步骤 4：配置 OTLP 导出器。（如果已配置 PostHog 日志导出，则跳过。）

  • PostHog 日志使用 OpenTelemetry 协议。请设置指向 PostHog 接收端点的 OTLP 导出器。
  • 对于 Android、React Native 和 iOS 等支持 SDK 原生日志的情况，请遵循平台参考文件，而不是添加单独的 OTLP 导出器。
  • 按照平台专属参考文件进行精确配置。

步骤 5：与现有日志集成。

  • 在现有日志设置旁添加 PostHog 日志导出器。不要替换现有日志处理器或输出。
  • 不要改变现有文件的基本架构。只进行最少且有针对性的添加。
  • 尝试写入文件前，必须立即读取该文件。

步骤 6：添加结构化属性。

  • 确保日志包含结构化键值属性，以便在 PostHog 中进行筛选和搜索。
  • 优先使用带键值属性的结构化日志格式，而不是纯文本消息。

步骤 7：设置环境变量。

  • 检查项目是否已配置 PostHog 环境变量（例如在 .env、.env.local 或框架专属环境文件中）。如果已有有效值，则跳过此步骤。
  • 如果缺少 PostHog 项目令牌，请使用 PostHog MCP 服务的 projects-get 工具获取项目的 api_token。如果返回了多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未经身份验证，请改为向用户索取 PostHog 项目令牌。
  • 对于 PostHog 主机 URL：检查 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要默认使用 US Cloud。
  • 对于 OpenTelemetry 端点，根据上面确定的区域，使用 https://us.i.posthog.com/v1（US）或 https://eu.i.posthog.com/v1（EU）。
  • 按照框架的命名约定，将这些值写入相应的环境文件。
  • 在代码中引用这些环境变量，而不是将它们硬编码。

参考文件

  • references/nextjs.md - Next.js 日志安装
  • references/nodejs.md - Node.js 日志安装
  • references/python.md - Python 日志安装
  • references/go.md - Go 日志安装
  • references/java.md - Java 日志安装
  • references/datadog.md - Datadog 日志安装
  • references/android.md - Android 日志安装
  • references/react-native.md - React Native 日志安装
  • references/ios.md - iOS 日志安装
  • references/flutter.md - Flutter 日志安装
  • references/other.md - 其他语言的日志安装
  • references/start-here.md - 日志入门
  • references/search.md - 搜索日志
  • references/best-practices.md - 日志最佳实践
  • references/troubleshooting.md - 日志故障排查
  • references/link-session-replay.md - 关联会话回放
  • references/mcp.md - 通过 PostHog MCP 使用日志
  • references/COMMANDMENTS.md - 集成必须遵循的特定框架规则

每个平台参考文件都包含特定的 OTLP 配置、SDK 设置和集成模式。请找到与用户技术栈匹配的文件。

关键原则

  • 环境变量：始终使用环境变量存储 PostHog 密钥和 OpenTelemetry 端点。切勿将它们硬编码。
  • 最小改动：在现有日志记录旁添加日志导出。不要替换或重构现有日志代码。
  • OpenTelemetry：PostHog 日志使用 OpenTelemetry 协议。配置一个指向 PostHog 接收端点的 OTLP 导出器，除非平台 SDK 提供原生日志捕获功能。
  • SDK 原生日志：对于 Android、React Native 和 iOS，请使用平台参考文件中的 SDK 日志记录器／捕获 API，而不是添加单独的 OTLP 导出器。
  • 结构化日志：优先使用带有键值属性的结构化日志格式，而不是纯文本消息。

评论

支持 Markdown