mcpField
O
omnibus-instrument-logs

omnibus-instrument-logs

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

关于 omnibus-instrument-logs

用于为现有项目添加 PostHog 日志采集，或配置 OTLP 日志导出。它指导开发者识别技术栈、设置导出器并补充结构化日志，同时保留现有日志处理器。

主要功能

  1. 01识别语言与日志配置
  2. 02配置 PostHog OTLP 导出
  3. 03集成到现有日志系统
  4. 04添加结构化日志属性
  5. 05涵盖多种平台与语言

适用场景

  1. 01功能变更后添加 PostHog 日志
  2. 02配置初始日志导出
  3. 03检查代码中的结构化事件

安装

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

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

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

包含的文件

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

references/
best-practices.md
datadog.md
debug-logs-mcp.md
go.md
java.md
link-session-replay.md
nextjs.md
nodejs.md
other.md
python.md
search.md
start-here.md
troubleshooting.md

详细介绍

添加 PostHog 日志采集

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

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

说明

按顺序执行以下步骤：

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

  • 检测语言、框架和现有日志设置。
  • 查找日志库（winston、pino、logging module、logrus、log4j、serilog 等）。
  • 查找锁定文件，以确定包管理器。
  • 检查是否已设置 PostHog 日志导出。如果已配置 OTLP 导出器，则跳到 STEP 5，为新增代码添加日志采集。

STEP 2：研究日志采集。（如果已配置 PostHog 日志导出，则跳过。） 2.1. 查找下方与检测到的平台匹配的参考文件——它是 OTLP 导出器配置和与现有日志集成方式的事实来源。现在阅读该文件。 2.2. 如果没有匹配的参考文件，则使用“其他语言”参考文件作为备用方案——其中涵盖通用的 OpenTelemetry 方法。

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

  • 为检测到的平台安装 OpenTelemetry SDK 和 OTLP 导出器包。
  • 不要手动编辑依赖项文件——使用包管理器的安装命令。
  • 始终将包安装作为后台任务运行。不要等待安装完成；立即继续其他工作。

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

  • PostHog 日志使用 OpenTelemetry 协议。设置指向 PostHog 接收端点的 OTLP 导出器。
  • 按照平台专属参考文件中的准确配置操作。

STEP 5：与现有日志集成。

  • 在现有日志记录器旁添加 PostHog 日志导出器。不要替换现有的日志处理器或输出。
  • 不要更改现有文件的基本架构。尽量只做有针对性的最小改动。
  • 尝试写入文件前，必须立即读取该文件。

STEP 6：添加结构化属性。

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

STEP 7：设置环境变量。

  • 如果已连接 env-file-tools MCP 服务，请依次使用 check_env_keys 和 set_env_values 配置 PostHog API 密钥、主机和 OpenTelemetry 端点。
  • 在代码中引用这些环境变量，而不要将值硬编码。

参考文件

  • 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/other.md - 其他语言日志安装 - 文档
  • 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 调试日志 - 文档

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

核心原则

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

评论

支持 Markdown