omnibus-instrument-logs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add PostHog log capture

添加PostHog日志捕获功能

Use this skill to add PostHog log capture for new or changed code. Use it after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. If PostHog log export is not yet configured, this skill also covers initial OTLP exporter setup. Supports any platform or language.

Supported platforms: Next.js, Node.js, Python, Go, Java, Datadog, and any language via OpenTelemetry.

使用此技能可为新增或修改后的代码添加PostHog日志捕获功能。可在功能实现完成或PR评审后使用，确保捕获包含结构化属性的有意义日志事件。如果尚未配置PostHog日志导出，该技能还会涵盖初始OTLP导出器的设置工作。支持所有平台或语言。

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

Instructions

操作步骤

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Detect the language, framework, and existing logging setup.
Look for log libraries (winston, pino, logging module, logrus, log4j, serilog, etc.).
Look for lockfiles to determine the package manager.
Check for existing PostHog log export setup. If the OTLP exporter is already configured, skip to STEP 5 to add log capture for new code.

STEP 2: Research log capture. (Skip if PostHog log export is already configured.) 2.1. Find the reference file below that matches the detected platform — it is the source of truth for OTLP exporter configuration and integration with existing logging. Read it now. 2.2. If no reference matches, use the "Other Languages" reference as a fallback — it covers the generic OpenTelemetry approach.

STEP 3: Install dependencies. (Skip if PostHog log export is already configured.)

Install the OpenTelemetry SDK and OTLP exporter packages for the detected platform.
Do not manually edit dependency files — use the package manager's install command.
Always install packages as a background task. Don't await completion; proceed with other work immediately.

STEP 4: Configure the OTLP exporter. (Skip if PostHog log export is already configured.)

PostHog logs use the OpenTelemetry protocol. Set up an OTLP exporter pointed at PostHog's ingest endpoint.
Follow the platform-specific reference for the exact configuration.

STEP 5: Integrate with existing logging.

Add the PostHog log exporter alongside existing logging. Don't replace existing log handlers or outputs.
Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.
You must read a file immediately before attempting to write it.

STEP 6: Add structured properties.

Ensure logs include structured key-value properties for filtering and search in PostHog.
Prefer structured log formats with key-value properties over plain text messages.

STEP 7: Set up environment variables.

If an env-file-tools MCP server is connected, use check_env_keys then set_env_values to configure the PostHog API key, host, and OpenTelemetry endpoint.
Reference these environment variables in code instead of hardcoding them.

请严格按照以下顺序执行步骤：

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

检测使用的语言、框架以及现有的日志记录设置。
查找日志库（如winston、pino、logging module、logrus、log4j、serilog等）。
查找锁文件以确定包管理器。
检查是否已存在PostHog日志导出设置。如果OTLP导出器已配置完成，直接跳至步骤5为新代码添加日志捕获功能。

步骤2：调研日志捕获配置。（如果已配置PostHog日志导出，请跳过此步骤。） 2.1. 找到与检测到的平台匹配的参考文件——该文件是OTLP导出器配置及与现有日志系统集成的权威依据。请立即阅读该文件。 2.2. 如果没有匹配的参考文件，请使用「其他语言」参考文件作为备选——它涵盖了通用OpenTelemetry方案。

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

为检测到的平台安装OpenTelemetry SDK和OTLP导出器包。
请勿手动编辑依赖文件——请使用包管理器的安装命令。
请始终在后台执行包安装任务。无需等待安装完成，可立即开展其他工作。

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

PostHog日志使用OpenTelemetry协议。请设置一个指向PostHog数据接入端点的OTLP导出器。
请遵循对应平台参考文件中的具体配置说明。

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

在现有日志系统基础上添加PostHog日志导出功能。请勿替换现有的日志处理器或输出方式。
请勿更改现有文件的基础架构。请以最小化、针对性的方式进行添加。
在尝试修改文件前，请务必先阅读该文件。

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

确保日志包含键值对形式的结构化属性，以便在PostHog中进行过滤和搜索。
优先使用带有键值属性的结构化日志格式，而非纯文本消息。

步骤7：设置环境变量。

如果已连接env-file-tools MCP服务器，请使用check_env_keys和set_env_values命令配置PostHog API密钥、主机地址以及OpenTelemetry端点。
在代码中引用这些环境变量，而非硬编码。

Reference files

参考文件

```
references/nextjs.md
```
- Next.js logs installation - docs
```
references/nodejs.md
```
- Node.js logs installation - docs
```
references/python.md
```
- Python logs installation - docs
```
references/go.md
```
- Go logs installation - docs
```
references/java.md
```
- Java logs installation - docs
```
references/datadog.md
```
- Datadog logs installation - docs
```
references/other.md
```
- Other languages logs installation - docs
```
references/start-here.md
```
- Getting started with logs - docs
```
references/search.md
```
- Search logs - docs
```
references/best-practices.md
```
- Logging best practices - docs
```
references/troubleshooting.md
```
- Logs troubleshooting - docs
```
references/link-session-replay.md
```
- Link session replay - docs
```
references/debug-logs-mcp.md
```
- Debug logs with mcp - docs

Each platform reference contains specific OTLP configuration, SDK setup, and integration patterns. Find the one matching the user's stack.

```
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设置和集成模式。请找到与用户技术栈匹配的参考文件。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys and OpenTelemetry endpoints. Never hardcode them.
Minimal changes: Add log export alongside existing logging. Don't replace or restructure existing logging code.
OpenTelemetry: PostHog logs use the OpenTelemetry protocol. Configure an OTLP exporter pointed at PostHog's ingest endpoint.
Structured logging: Prefer structured log formats with key-value properties over plain text messages.

环境变量：始终使用环境变量存储PostHog密钥和OpenTelemetry端点。切勿硬编码。
最小化变更：在现有日志系统基础上添加日志导出功能。请勿替换或重构现有日志代码。
OpenTelemetry：PostHog日志使用OpenTelemetry协议。请配置一个指向PostHog数据接入端点的OTLP导出器。
结构化日志：优先使用带有键值属性的结构化日志格式，而非纯文本消息。