Back to Details

error-tracking-node

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PostHog error tracking for Node.js

适用于Node.js的PostHog错误追踪

This skill helps you add PostHog error tracking to Node.js applications.
本技能可帮助你在Node.js应用中添加PostHog错误追踪功能。

Reference files

参考文件

  • references/node.md
    - Node.js 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
Consult the documentation for API details and framework-specific patterns.
  • references/node.md
    - Node.js错误追踪安装文档
  • references/fingerprints.md
    - 指纹识别文档
  • references/alerts.md
    - 发送错误追踪告警文档
  • references/monitoring.md
    - 监控与搜索问题文档
  • references/assigning-issues.md
    - 向团队成员分配问题文档
  • references/upload-source-maps.md
    - 上传源码映射文档
如需了解API详情和特定框架的实现模式，请查阅相关文档。

Key principles

核心原则

  • Environment variables: Always use environment variables for PostHog keys and host URLs. Never hardcode them.
  • Minimal changes: Add error tracking alongside existing error handling. Don't replace or restructure existing error handling code.
  • Autocapture first: Enable exception autocapture in the SDK initialization 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密钥和主机URL，切勿硬编码。
  • 最小改动：在现有错误处理基础上添加错误追踪，不要替换或重构现有错误处理代码。
  • 优先自动捕获：在SDK初始化时启用异常自动捕获，再添加手动捕获逻辑。
  • 源码映射：上传源码映射，以便将堆栈跟踪解析为原始源代码，而非压缩后的包文件。
  • 边界处手动捕获：在错误边界和catch块中使用
    captureException()
    捕获那些不会传播到全局处理器的错误。

Framework guidelines

框架指南

  • posthog-node is the Node.js server-side SDK package name – do NOT use posthog-js on the server
  • Include enableExceptionAutocapture: true in the PostHog constructor options
  • Add posthog.capture() calls in route handlers for meaningful user actions – every route that creates, updates, or deletes data should track an event with contextual properties
  • Add posthog.captureException(err, distinctId) in the application's error handler (e.g., Express error middleware, Fastify setErrorHandler, Koa app.on('error'))
  • In long-running servers, the SDK batches events automatically – do NOT set flushAt or flushInterval unless you have a specific reason to
  • For short-lived processes (scripts, CLIs, serverless), set flushAt to 1 and flushInterval to 0 to send events immediately
  • Reverse proxy is NOT needed for server-side Node.js – only client-side JavaScript needs a proxy to avoid ad blockers
  • Remember that source code is available in the node_modules directory
  • Check package.json for type checking or build scripts to validate changes
  • posthog-node是Node.js服务端SDK的包名——请勿在服务端使用posthog-js
  • 在PostHog构造函数选项中设置enableExceptionAutocapture: true
  • 在路由处理器中添加posthog.capture()调用，以追踪有意义的用户操作——所有创建、更新或删除数据的路由都应追踪带有上下文属性的事件
  • 在应用的错误处理器中添加posthog.captureException(err, distinctId)（例如Express错误中间件、Fastify setErrorHandler、Koa app.on('error')）
  • 在长期运行的服务器中，SDK会自动批量处理事件——除非有特殊需求，否则不要设置flushAt或flushInterval
  • 对于短生命周期进程（脚本、CLI、无服务器函数），将flushAt设为1，flushInterval设为0以立即发送事件
  • 服务端Node.js无需反向代理——仅客户端JavaScript需要代理以避开广告拦截器
  • 请记住源代码位于node_modules目录中
  • 检查package.json中的类型检查或构建脚本，以验证更改是否正确