Back to Details

instrument-repo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/instrument-repo

/instrument-repo

Add production observability to a repository. Detects stack, installs SDKs, writes config, opens PR.
为代码仓库添加生产环境可观测性能力。自动检测技术栈、安装SDK、编写配置文件并创建Pull Request。

Shared Config

通用配置

SENTRY_ORG=misty-step
SENTRY_TEAM=misty-step
POSTHOG_PROJECT_ID=293836
POSTHOG_HOST=https://us.i.posthog.com
All repos share ONE PostHog project (segmented by events). Each repo gets its OWN Sentry project.
SENTRY_ORG=misty-step
SENTRY_TEAM=misty-step
POSTHOG_PROJECT_ID=293836
POSTHOG_HOST=https://us.i.posthog.com
所有代码仓库共享同一个PostHog项目（通过事件区分），每个仓库拥有独立的Sentry项目。

Detection

检测逻辑

Before instrumenting, detect what we're working with:
bash
undefined
在集成可观测性工具前，先检测当前项目的技术栈：
bash
undefined

Language detection

语言检测

[ -f package.json ] && echo "typescript" [ -f go.mod ] && echo "go" [ -f pyproject.toml ] || [ -f setup.py ] && echo "python" [ -f Package.swift ] && echo "swift" [ -f Cargo.toml ] && echo "rust"
[ -f package.json ] && echo "typescript" [ -f go.mod ] && echo "go" [ -f pyproject.toml ] || [ -f setup.py ] && echo "python" [ -f Package.swift ] && echo "swift" [ -f Cargo.toml ] && echo "rust"

Framework detection (TypeScript)

框架检测（TypeScript）

grep -q '"next"' package.json 2>/dev/null && echo "nextjs" grep -q '"hono"' package.json 2>/dev/null && echo "hono" grep -q '"express"' package.json 2>/dev/null && echo "express" grep -q '"react-native"' package.json 2>/dev/null && echo "react-native"
grep -q '"next"' package.json 2>/dev/null && echo "nextjs" grep -q '"hono"' package.json 2>/dev/null && echo "hono" grep -q '"express"' package.json 2>/dev/null && echo "express" grep -q '"react-native"' package.json 2>/dev/null && echo "react-native"

LLM usage detection (for Helicone)

LLM使用检测（用于Helicone）

grep -rq '@ai-sdk|openai|anthropic|@google/genai' package.json src/ lib/ app/ 2>/dev/null && echo "has-llm" grep -rq 'openai|anthropic|langchain' *.go cmd/ internal/ 2>/dev/null && echo "has-llm" grep -rq 'openai|anthropic|langchain' *.py src/ 2>/dev/null && echo "has-llm"
grep -rq '@ai-sdk|openai|anthropic|@google/genai' package.json src/ lib/ app/ 2>/dev/null && echo "has-llm" grep -rq 'openai|anthropic|langchain' *.go cmd/ internal/ 2>/dev/null && echo "has-llm" grep -rq 'openai|anthropic|langchain' *.py src/ 2>/dev/null && echo "has-llm"

Existing instrumentation

已集成的可观测性工具检测

grep -q '@sentry' package.json 2>/dev/null && echo "has-sentry" grep -q 'posthog' package.json 2>/dev/null && echo "has-posthog" grep -rq 'helicone' src/ lib/ app/ 2>/dev/null && echo "has-helicone"
undefined
grep -q '@sentry' package.json 2>/dev/null && echo "has-sentry" grep -q 'posthog' package.json 2>/dev/null && echo "has-posthog" grep -rq 'helicone' src/ lib/ app/ 2>/dev/null && echo "has-helicone"
undefined

Per-repo Workflow

单仓库集成流程

1. cd ~/Development/$REPO
2. Detect language, framework, LLM usage, existing instrumentation
3. git fetch origin && git checkout -b infra/observability origin/main (or master)
4. Create Sentry project if needed → mcp__sentry__create_project
5. Install packages (language-specific)
6. Write/update config files from templates
7. Update .env.example
8. Typecheck/build to verify
9. git add <specific files> && git commit
10. git push -u origin infra/observability
11. gh pr create with structured body
1. cd ~/Development/$REPO
2. 检测语言、框架、LLM使用情况及已集成的可观测性工具
3. git fetch origin && git checkout -b infra/observability origin/main（或master分支）
4. 按需创建Sentry项目 → 调用mcp__sentry__create_project
5. 安装对应语言的依赖包
6. 从模板生成/更新配置文件
7. 更新.env.example文件
8. 执行类型检查/构建以验证配置
9. git add <指定文件> && git commit
10. git push -u origin infra/observability
11. 使用结构化内容创建GitHub PR

What to Add (Decision Matrix)

工具集成决策矩阵

ConditionSentryPostHogHelicone
Any app/serviceYES——
User-facing web appYESYES—
Has LLM SDK importsYESmaybeYES
CLI toolYESNOmaybe
GitHub Action / libNONONO
条件SentryPostHogHelicone
任意应用/服务是——
面向用户的Web应用是是—
包含LLM SDK依赖是可选是
CLI工具是否可选
GitHub Action / 类库否否否

Sentry Sampling Rates

Sentry采样率配置

Cost-conscious defaults (5k errors/mo free tier):
tracesSampleRate: 0.1          # 10% of transactions
replaysSessionSampleRate: 0    # Don't record sessions by default
replaysOnErrorSampleRate: 1.0  # Always replay on error
兼顾成本的默认配置（免费层每月支持5000条错误记录）：
tracesSampleRate: 0.1          # 10%的事务会被采样
replaysSessionSampleRate: 0    # 默认不记录会话回放
replaysOnErrorSampleRate: 1.0  # 发生错误时始终记录会话回放

Templates

配置模板

Next.js → 
templates/nextjs/

Next.js → 
templates/nextjs/

Files to create:
  • sentry.client.config.ts
    — Client-side Sentry init
  • sentry.server.config.ts
    — Server-side Sentry init
  • sentry.edge.config.ts
    — Edge runtime Sentry init (same as server)
  • instrumentation.ts
    — Next.js instrumentation hook
  • lib/sentry.ts
    — Shared Sentry config factory with PII scrubbing
  • components/posthog-provider.tsx
    — PostHog React provider
  • components/posthog-pageview.tsx
    — Route-aware pageview tracking
  • lib/posthog.ts
    — PostHog client init + helpers
Install: 
pnpm add @sentry/nextjs posthog-js posthog-node
Next.js config: wrap with 
withSentryConfig()
in 
next.config.ts
PostHog 
/ingest
rewrite in 
next.config.ts
:
typescript
async rewrites() {
  return [
    { source: "/ingest/static/:path*", destination: "https://us-assets.i.posthog.com/static/:path*" },
    { source: "/ingest/:path*", destination: "https://us.i.posthog.com/:path*" },
    { source: "/ingest/decide", destination: "https://us.i.posthog.com/decide" },
  ];
},
需要创建的文件：
  • sentry.client.config.ts
    — 客户端Sentry初始化配置
  • sentry.server.config.ts
    — 服务端Sentry初始化配置
  • sentry.edge.config.ts
    — Edge运行时Sentry初始化配置（与服务端一致）
  • instrumentation.ts
    — Next.js instrumentation钩子
  • lib/sentry.ts
    — 包含PII脱敏逻辑的Sentry共享配置工厂
  • components/posthog-provider.tsx
    — PostHog React提供者组件
  • components/posthog-pageview.tsx
    — 路由感知的页面访问追踪组件
  • lib/posthog.ts
    — PostHog客户端初始化及工具函数
安装命令：
pnpm add @sentry/nextjs posthog-js posthog-node
Next.js配置：在
next.config.ts
中使用
withSentryConfig()
包裹配置
PostHog 
/ingest
路径重写配置（在
next.config.ts
中）：
typescript
async rewrites() {
  return [
    { source: "/ingest/static/:path*", destination: "https://us-assets.i.posthog.com/static/:path*" },
    { source: "/ingest/:path*", destination: "https://us.i.posthog.com/:path*" },
    { source: "/ingest/decide", destination: "https://us.i.posthog.com/decide" },
  ];
},

Node.js (Express/Hono) → 
templates/node/

Node.js (Express/Hono) → 
templates/node/

Files to create:
  • lib/sentry.ts
    — Sentry init for Node
Install: 
pnpm add @sentry/node
Express: 
Sentry.setupExpressErrorHandler(app)
after all routes Hono: Import and init at app entry, use 
onError
hook
需要创建的文件：
  • lib/sentry.ts
    — Node.js环境下的Sentry初始化配置
安装命令：
pnpm add @sentry/node
Express：在所有路由定义后调用
Sentry.setupExpressErrorHandler(app)
Hono：在应用入口导入并初始化，使用
onError
钩子

Go → 
templates/go/

Go → 
templates/go/

Files to create:
  • internal/observability/sentry.go
    — Sentry init + flush helper
Install: 
go get github.com/getsentry/sentry-go
需要创建的文件：
  • internal/observability/sentry.go
    — Sentry初始化及刷新工具函数
安装命令：
go get github.com/getsentry/sentry-go

Python → 
templates/python/

Python → 
templates/python/

Files to create:
  • observability.py
    — Sentry init
Install: 
pip install sentry-sdk
or add to 
pyproject.toml
需要创建的文件：
  • observability.py
    — Sentry初始化配置
安装方式：
pip install sentry-sdk
或添加到
pyproject.toml

Swift → 
templates/swift/

Swift → 
templates/swift/

Files to create:
  • SentrySetup.swift
    — Sentry init via SPM
SPM dependency: 
https://github.com/getsentry/sentry-cocoa
PostHog SPM: 
https://github.com/PostHog/posthog-ios
需要创建的文件：
  • SentrySetup.swift
    — 通过SPM初始化Sentry
SPM依赖：
https://github.com/getsentry/sentry-cocoa
PostHog SPM依赖：
https://github.com/PostHog/posthog-ios

Rust → 
templates/rust/

Rust → 
templates/rust/

Files to create:
  • src/sentry_init.rs
    — Sentry guard init
Install: Add 
sentry = "0.35"
to 
Cargo.toml
需要创建的文件：
  • src/sentry_init.rs
    — Sentry guard初始化配置
安装方式：在
Cargo.toml
中添加
sentry = "0.35"

React Native → 
templates/react-native/

React Native → 
templates/react-native/

Install: 
pnpm add @sentry/react-native posthog-react-native
安装命令：
pnpm add @sentry/react-native posthog-react-native

Helicone → 
templates/helicone/

Helicone → 
templates/helicone/

Files to create:
  • lib/ai-provider.ts
    — Helicone-proxied AI SDK provider
Pattern: Change 
baseURL
on AI SDK provider to Helicone gateway, add auth + property headers.
需要创建的文件：
  • lib/ai-provider.ts
    — 经过Helicone代理的AI SDK提供者配置
配置模式：将AI SDK提供者的
baseURL
修改为Helicone网关地址，添加认证及属性头

Commit Message

提交信息模板

feat: add observability (Sentry [+ PostHog] [+ Helicone])

- Sentry: error tracking with PII-safe defaults
[- PostHog: product analytics with privacy masking]
[- Helicone: LLM cost tracking via gateway proxy]
- Updated .env.example with required variables
feat: add observability (Sentry [+ PostHog] [+ Helicone])

- Sentry: error tracking with PII-safe defaults
[- PostHog: product analytics with privacy masking]
[- Helicone: LLM cost tracking via gateway proxy]
- Updated .env.example with required variables

PR Body

PR内容模板

markdown
undefined
markdown
undefined

Summary

摘要

Add production observability to {repo}.
为{repo}添加生产环境可观测性能力。

Changes

变更内容

  • Sentry error tracking (DSN: 
    {dsn}
    )
    • PII scrubbing (emails, IPs, sensitive headers)
    • Environment-aware (production/preview/development)
    • Traces sample rate: 10% [- PostHog product analytics
    • Pageview tracking via 
      /ingest
      proxy rewrite
    • Privacy: 
      respect_dnt: true
      , manual pageview capture] [- Helicone LLM cost tracking
    • Proxied through gateway for cost/latency monitoring
    • Tagged with product name and environment]
  • Updated 
    .env.example
    with all required variables
  • Sentry错误追踪（DSN: 
    {dsn}
    ）
    • PII脱敏处理（邮箱、IP、敏感请求头）
    • 环境感知（生产/预览/开发环境）
    • 事务采样率：10% [- PostHog产品数据分析
    • 通过
      /ingest
      代理重写实现页面访问追踪
    • 隐私配置：
      respect_dnt: true
      ，手动触发页面访问捕获] [- Helicone LLM成本追踪
    • 通过网关代理实现成本/延迟监控
    • 标记产品名称及环境信息]
  • 更新
    .env.example
    文件，添加所有必填环境变量

Required Env Vars

必填环境变量

VariableWhereValue
NEXT_PUBLIC_SENTRY_DSN
Vercel
{dsn}
SENTRY_AUTH_TOKEN
Vercel + GH Actionsorg-level token
[
NEXT_PUBLIC_POSTHOG_KEY
Vercel
[
HELICONE_API_KEY
Vercel (server)
变量名配置位置值
NEXT_PUBLIC_SENTRY_DSN
Vercel
{dsn}
SENTRY_AUTH_TOKEN
Vercel + GH Actions组织级令牌
[
NEXT_PUBLIC_POSTHOG_KEY
Vercel
[
HELICONE_API_KEY
Vercel (服务端)

Test Plan

测试计划

  • pnpm build
    passes
  • Deploy to preview → check Sentry for test error
  • Set env vars on Vercel production [- [ ] Verify PostHog Live Events after deploy] [- [ ] Verify Helicone dashboard shows tagged requests]
undefined
  • pnpm build
    执行成功
  • 部署到预览环境 → 在Sentry中验证测试错误是否被捕获
  • 在Vercel生产环境配置环境变量 [- [ ] 部署后验证PostHog实时事件] [- [ ] 验证Helicone仪表盘显示标记后的请求]
undefined

Env Var Reference

环境变量参考

VariableScopeNotes
NEXT_PUBLIC_SENTRY_DSN
Per-projectUnique per Sentry project
SENTRY_DSN
Per-project (server-only)Same DSN, no NEXT_PUBLIC prefix
SENTRY_AUTH_TOKEN
SharedFor source map uploads
SENTRY_ORG
misty-step
Hardcode in config
SENTRY_PROJECT
Per-projectMatches Sentry project slug
NEXT_PUBLIC_POSTHOG_KEY
SharedPostHog project API key
NEXT_PUBLIC_POSTHOG_HOST
/ingest
Via rewrite proxy
HELICONE_API_KEY
Shared (server-only)Never expose client-side
变量名作用范围说明
NEXT_PUBLIC_SENTRY_DSN
单项目每个Sentry项目唯一
SENTRY_DSN
单项目（仅服务端）与上述DSN相同，无NEXT_PUBLIC前缀
SENTRY_AUTH_TOKEN
共享用于上传source map
SENTRY_ORG
misty-step
在配置中硬编码
SENTRY_PROJECT
单项目与Sentry项目别名一致
NEXT_PUBLIC_POSTHOG_KEY
共享PostHog项目API密钥
NEXT_PUBLIC_POSTHOG_HOST
/ingest
通过代理重写配置
HELICONE_API_KEY
共享（仅服务端）绝不能在客户端暴露

Audit Mode

审计模式

When 
--audit
flag or repo already has instrumentation:
  1. Check Sentry config against best practices (PII scrubbing, sampling rates, env detection)
  2. Check PostHog config (respect_dnt, manual pageview, proxy rewrite)
  3. Check Helicone config (product tag, environment tag, user-id)
  4. Report findings, fix issues, open PR with fixes
当添加
--audit
参数或仓库已集成可观测性工具时：
  1. 检查Sentry配置是否符合最佳实践（PII脱敏、采样率、环境检测）
  2. 检查PostHog配置（Do Not Track支持、手动页面访问捕获、代理重写）
  3. 检查Helicone配置（产品标记、环境标记、用户ID）
  4. 生成审计报告、修复问题并创建包含修复内容的PR

Anti-Patterns

反模式（需避免）

  • tracesSampleRate: 1
    — exhausts free tier instantly
  • Missing PII scrubbing — privacy violation
  • sendDefaultPii: true
    — leaks emails/IPs
  • PostHog without 
    /ingest
    rewrite — blocked by ad blockers
  • Helicone API key in client-side code — key exposure
  • Hardcoded DSN in code instead of env var — can't change per environment
  • Missing 
    respect_dnt: true
    on PostHog — privacy violation
  • tracesSampleRate: 1
    — 瞬间耗尽免费层额度
  • 缺失PII脱敏逻辑 — 违反隐私规定
  • sendDefaultPii: true
    — 泄露邮箱/IP信息
  • PostHog未配置
    /ingest
    重写 — 会被广告拦截器阻止
  • Helicone API密钥出现在客户端代码中 — 密钥泄露风险
  • 代码中硬编码DSN而非使用环境变量 — 无法按环境切换配置
  • PostHog未设置
    respect_dnt: true
    — 违反隐私规定