instrument-error-tracking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add PostHog error tracking

添加PostHog错误追踪

Use this skill to add PostHog error tracking that captures and monitors exceptions in your application. Use it after implementing features or reviewing PRs to ensure errors are tracked with full stack traces and source maps. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any platform or language.

Supported platforms: React, Next.js, Web (JavaScript), Node.js, Python, Ruby, Ruby on Rails, Go, Angular, Svelte, Nuxt, React Native, Flutter, Android, and Hono.

使用该技能可为你的应用添加PostHog错误追踪功能，用于捕获和监控异常。建议在功能开发完成或PR评审后使用，确保错误可附带完整stack traces和source maps被追踪。若尚未安装PostHog，该技能还包含SDK的初始配置步骤。支持所有平台和语言。

支持的平台：React、Next.js、Web（JavaScript）、Node.js、Python、Ruby、Ruby on Rails、Go、Angular、Svelte、Nuxt、React Native、Flutter、Android和Hono。

Instructions

操作步骤

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Look for dependency files (package.json, requirements.txt, go.mod, Gemfile, composer.json, etc.) to determine the language and framework.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) to determine the package manager.
Check for existing PostHog setup (SDK initialization, env vars, etc.). If PostHog is already installed and initialized, skip to STEP 4.

STEP 2: Research instrumentation. (Skip if PostHog is already set up.) 2.1. Find the reference file below that matches the detected platform — it is the source of truth for SDK initialization, exception autocapture, and framework-specific error tracking patterns. Read it now. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.

STEP 3: Install and initialize the PostHog SDK. (Skip if PostHog is already set up.)

Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.
Follow the framework reference for where and how to initialize.

STEP 4: Enable exception autocapture.

Follow the platform reference to enable exception autocapture. This automatically captures unhandled exceptions without additional code.

STEP 5: Add manual error captures.

Identify error boundaries, catch blocks, and critical user flows where errors should be explicitly captured.
Add
```
posthog.captureException()
```
or the platform-equivalent at these locations.
Do not alter the fundamental architecture of existing error handling. Make additions minimal and targeted.
You must read a file immediately before attempting to write it.

STEP 6: Upload source maps (frontend/mobile only).

Configure source map uploads so stack traces resolve to original source code, not minified bundles.
Follow the platform-specific reference for upload configuration (build plugins, CI scripts, etc.).

STEP 7: Set up environment variables.

Check if the project already has PostHog environment variables configured (e.g. in
```
.env
```
,
```
.env.local
```
, or framework-specific env files). If valid values already exist, skip this step.
If the PostHog API key is missing, use the PostHog MCP server's
```
projects-get
```
tool to retrieve the project's
```
api_token
```
. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
For the PostHog host URL, use
```
https://us.i.posthog.com
```
for US Cloud or
```
https://eu.i.posthog.com
```
for EU Cloud.
Write these values to the appropriate env file using the framework's naming convention.
Reference these environment variables in code instead of hardcoding them.

STEP 8: Verify and clean up.

Check the project for errors. Look for type checking or build scripts in package.json.
Ensure any components created were actually used.
Run any linter or prettier-like scripts found in the package.json.

请按以下顺序执行步骤：

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

查看依赖文件（package.json、requirements.txt、go.mod、Gemfile、composer.json等）以确定语言和框架。
查看锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）以确定包管理器。
检查是否已存在PostHog配置（SDK初始化、环境变量等）。若PostHog已安装并初始化，直接跳至步骤4。

步骤2：调研工具集成方式（若已配置PostHog则跳过此步骤）。 2.1. 找到与检测到的平台匹配的参考文件——该文件是SDK初始化、异常自动捕获以及框架特定错误追踪模式的权威来源。请先阅读该文件。 2.2. 若没有匹配的参考文件，可依靠通用知识和网络搜索。优先使用posthog.com/docs作为搜索来源。

步骤3：安装并初始化PostHog SDK（若已配置PostHog则跳过此步骤）。

为检测到的平台添加PostHog SDK包。请勿手动编辑package.json——使用包管理器的安装命令。
始终将包安装作为后台任务执行。无需等待安装完成，启动安装后立即进行其他操作。
遵循框架参考文件中的说明，确定初始化的位置和方式。

步骤4：启用异常自动捕获。

遵循平台参考文件的说明启用异常自动捕获。此功能无需额外代码即可自动捕获未处理的异常。

步骤5：添加手动错误捕获。

识别错误边界、catch代码块以及需要显式捕获错误的关键用户流程。
在这些位置添加
```
posthog.captureException()
```
或对应平台的等效方法。
请勿修改现有错误处理的基础架构。仅进行最小化、针对性的添加。
在尝试写入文件前，必须先读取该文件。

步骤6：上传source maps（仅前端/移动端）。

配置source maps上传，使堆栈跟踪能够解析为原始源代码，而非压缩后的打包文件。
遵循平台特定参考文件中的上传配置说明（构建插件、CI脚本等）。

步骤7：设置环境变量。

检查项目是否已配置PostHog环境变量（例如在
```
.env
```
、
```
.env.local
```
或框架特定的环境文件中）。若已存在有效配置，跳过此步骤。
若缺少PostHog API密钥，使用PostHog MCP服务器的
```
projects-get
```
工具获取项目的
```
api_token
```
。若返回多个项目，请询问用户使用哪个项目。若未连接或未认证MCP服务器，请直接向用户索要PostHog项目API密钥。
PostHog主机URL：美国云使用
```
https://us.i.posthog.com
```
，欧盟云使用
```
https://eu.i.posthog.com
```
。
将这些值写入符合框架命名规范的对应环境文件中。
在代码中引用这些环境变量，而非硬编码。

步骤8：验证与清理。

检查项目是否存在错误。查看package.json中的类型检查或构建脚本。
确保创建的所有组件均已实际使用。
运行package.json中找到的任何linter或prettier类脚本。

Reference files

参考文件

```
references/react.md
```
- React error tracking installation - docs
```
references/web.md
```
- Web error tracking installation - docs
```
references/nextjs.md
```
- Next.js error tracking installation - docs
```
references/node.md
```
- Node.js error tracking installation - docs
```
references/python.md
```
- Python error tracking installation - docs
```
references/ruby.md
```
- Ruby error tracking installation - docs
```
references/ruby-on-rails.md
```
- Ruby on rails error tracking installation - docs
```
references/go.md
```
- Go error tracking installation - docs
```
references/angular.md
```
- Angular error tracking installation - docs
```
references/svelte.md
```
- Sveltekit error tracking installation - docs
```
references/nuxt.md
```
- Nuxt error tracking installation (v3.7 and above) - docs
```
references/react-native.md
```
- React native error tracking installation - docs
```
references/flutter.md
```
- Flutter error tracking installation - docs
```
references/android.md
```
- Android error tracking installation - docs
```
references/hono.md
```
- Hono error tracking installation - docs
```
references/fingerprints.md
```
- Fingerprints - docs
```
references/alerts.md
```
- Send error tracking alerts - docs
```
references/monitoring.md
```
- Monitor and search issues - docs
```
references/assigning-issues.md
```
- Assign issues to teammates - docs
```
references/upload-source-maps.md
```
- Upload source maps - docs

Each platform reference contains SDK-specific installation and manual capture patterns. Find the one matching the user's stack.

```
references/react.md
```
- React错误追踪安装文档
```
references/web.md
```
- Web错误追踪安装文档
```
references/nextjs.md
```
- Next.js错误追踪安装文档
```
references/node.md
```
- Node.js错误追踪安装文档
```
references/python.md
```
- Python错误追踪安装文档
```
references/ruby.md
```
- Ruby错误追踪安装文档
```
references/ruby-on-rails.md
```
- Ruby on Rails错误追踪安装文档
```
references/go.md
```
- Go错误追踪安装文档
```
references/angular.md
```
- Angular错误追踪安装文档
```
references/svelte.md
```
- SvelteKit错误追踪安装文档
```
references/nuxt.md
```
- Nuxt错误追踪安装文档（v3.7及以上版本）
```
references/react-native.md
```
- React Native错误追踪安装文档
```
references/flutter.md
```
- Flutter错误追踪安装文档
```
references/android.md
```
- Android错误追踪安装文档
```
references/hono.md
```
- Hono错误追踪安装文档
```
references/fingerprints.md
```
- 指纹识别文档
```
references/alerts.md
```
- 发送错误追踪告警文档
```
references/monitoring.md
```
- 监控与搜索问题文档
```
references/assigning-issues.md
```
- 问题分配给团队成员文档
```
references/upload-source-maps.md
```
- 上传source maps文档

每个平台参考文件都包含特定于SDK的安装和手动捕获模式。请找到与用户技术栈匹配的文件。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing code.
Autocapture first: Enable exception autocapture before adding manual captures.
Source maps: Upload source maps so stack traces resolve to original source code, not minified bundles.
Manual capture for boundaries: Use
```
captureException()
```
at error boundaries and catch blocks for errors that don't propagate to the global handler.

环境变量：始终使用环境变量存储PostHog密钥，切勿硬编码。
最小修改：在现有错误处理基础上添加错误追踪，请勿替换或重构现有代码。
优先自动捕获：在添加手动捕获前，先启用异常自动捕获。
Source Maps：上传source maps，使堆栈跟踪能够解析为原始源代码，而非压缩后的打包文件。
边界处手动捕获：在错误边界和catch代码块中使用
```
captureException()
```
，捕获那些不会传播到全局处理器的错误。