日志 + 遥测架构¶

重要性：⭐⭐⭐（可观测性——log + telemetry + analytics + 启动 profiler + 错误日志）范围：src/utils/log.js + src/services/analytics/ + 全文 logEvent/logError 方法：grep log / telemetry / analytics / Statsig / event

1. 4 大可观测性通道¶

┌────────────────────────────────────────┐
│  1. logError  (错误日志)              │
│  2. logEvent  (业务事件)              │
│  3. profileCheckpoint (启动性能)     │
│  4. analytics sink (聚合遥测)        │
└────────────────────────────────────────┘

4 通道 —— 用途不同。

2. logError（错误日志）¶

2.1 API¶

import { logError } from './utils/log.js'
logError(err)

单一函数 —— 内部处理。

2.2 用途¶

异常捕获后
业务失败
安全事件

2.3 输出位置¶

推测： - 控制台（debug mode） - 文件（~/.claude/logs/，推测） - Statsig（采样） - Sentry / 内部 metrics（推测）

3. logEvent（业务事件）¶

3.1 API¶

import { logEvent } from 'src/services/analytics/index.js'
logEvent('tengu_managed_settings_loaded', { 
  keyCount: 5,
  keys: '...' as unknown as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS
})

3 个参数： - 事件名（tengu_* 前缀） - metadata（key-value） - 命名约定（_I_VERIFIED_* 后缀）

3.2 事件命名¶

'tengu_managed_settings_loaded'
'tengu_code_prompt_ignored'
'tengu_single_word_prompt'
'tengu_teleport_interactive_mode'
'tengu_teleport_resume_session'

tengu_* 前缀 —— 商业产品内部命名。

3.3 AnalyticsMetadata_I_VERIFIED¶

type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS = string

类型级契约 —— 强制作者审查。

3.4 事件数¶

50+ events（推测）—— 覆盖各业务领域。

4. 4 大 event 类别¶

4.1 启动 / 性能¶

'tengu_managed_settings_loaded'  // 启动时
'tengu_exit_after_first_render'  // perf 模式

4.2 用户行为¶

'tengu_code_prompt_ignored'  // 输入 "code"
'tengu_single_word_prompt'  // 单字 prompt

4.3 会话¶

'tengu_teleport_interactive_mode'  // teleport
'tengu_teleport_resume_session'  // teleport resume

4.4 安全 / 警告¶

'tengu_deprecated_setting'  // deprecation
'tengu_auth_failed'  // auth fail

5. profileCheckpoint（启动性能）¶

详见 analysis/performance-history.md。

import { profileCheckpoint, profileReport } from './utils/startupProfiler.js'
profileCheckpoint('main_tsx_entry')
profileReport()

30+ 埋点 —— 启动全程。

6. Analytics Sink 架构¶

6.1 `services/analytics/`¶

analytics/
├── config.js           (isAnalyticsDisabled)
├── growthbook.js       (feature flags)
├── index.js            (logEvent 入口)
├── sink.js             (sinks attach)
└── ...

多文件 —— analytics 完整服务。

6.2 `isAnalyticsDisabled`¶

function isAnalyticsDisabled(): boolean { ... }

环境开关 —— DISABLE_TELEMETRY=1 等。

6.3 `initializeAnalyticsGates`¶

async function initializeAnalyticsGates(): Promise<void> { ... }

门控初始化 —— 首屏后。

6.4 `logEvent` 入口¶

function logEvent(name: string, metadata: AnalyticsMetadata) {
  // 1. 检查 isAnalyticsDisabled
  // 2. 校验 metadata
  // 3. dispatch to sinks
}

3 步 —— 检查 + 校验 + 分发。

6.5 `initSinks`（preAction）¶

const { initSinks } = await import('./utils/sinks.js')
initSinks()

sink attach —— subcommand 也走这个。

注释：

Before PR #11106 logEvent dispatched directly; after, events queue until a sink attaches. setup() attaches sinks for the default command, but subcommands (doctor, mcp, plugin, auth) never call setup() and would silently drop events on process.exit().

关键修复 —— subcommand 不丢事件。

6.6 GrowthBook¶

hasGrowthBookEnvOverride, initializeGrowthBook, refreshGrowthBookAfterAuthChange

GrowthBook 集成 —— feature flag + A/B test。

6.7 AgentSummary¶

services/AgentSummary

会话 summary —— session 结束上传。

6.8 SessionMemory¶

services/SessionMemory

会话记忆 —— 跨 session 提取。

6.9 PrefetchPassesEligibility¶

services/api/referral.ts (prefetchPassesEligibility)

推荐资格 —— 预取。

6.10 PrefetchOfficialMcpUrls¶

services/mcp/officialRegistry.ts

官方 MCP 预取。

6.11 RefreshModelCapabilities¶

// 推测
refreshModelCapabilities()

模型能力刷新。

7. Sinks 抽象¶

7.1 `utils/sinks.ts`¶

// 推测
interface Sink {
  send(event: AnalyticsEvent): Promise<void>
}

class StdoutSink implements Sink { ... }
class StatsigSink implements Sink { ... }
class FileSink implements Sink { ... }

多 sink —— 不同目的地。

7.2 attach 模式¶

function initSinks(): void {
  attach(new StdoutSink());
  attach(new StatsigSink());
  // ...
}

多 sink 并行 —— fan-out。

8. 输出格式¶

8.1 控制台¶

console.log('[DEBUG]', message)

debug 模式可见。

8.2 JSON¶

// 推测
JSON.stringify({ event, metadata, timestamp })

结构化 —— 便于解析。

8.3 文件¶

// ~/.claude/logs/2026-06-05.jsonl

每日一个文件 —— log rotation。

9. 采样¶

9.1 Statsig 采样¶

// 推测
profileReport();  // 采样上报

采样 —— 不是所有用户都上报。

9.2 错误 100% 上报¶

logError(err)  // 推测 100% 上报

关键事件 —— 不采样。

9.3 业务事件采样¶

logEvent(...)  // 推测采样

业务事件 —— 可采样。

10. 隐私¶

10.1 命名约定¶

_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS —— 类型级强制。

10.2 脱敏¶

redactUrlCredentials, redactHeaders

显式脱敏。

10.3 用户控制¶

isAnalyticsDisabled  // 关闭遥测

用户可关闭。

11. 错误日志 vs 业务事件¶

维度	logError	logEvent
触发	异常 / 失败	业务行为
频率	罕见	频繁
采样	通常 100%	可采样
结构	Error 对象	name + metadata
目的地	Sentry / 文件	Statsig / 业务

2 个通道不同 —— 不混用。

12. 与其他可观测性工具¶

工具	用途	状态
console.log	dev 调试	✅ 有
chalk	彩色输出	✅ 有
logError	错误	✅ 有
logEvent	业务	✅ 有
profileCheckpoint	性能	✅ 有
Sentry	错误聚合	❓ 推测有
Statsig	feature flag + 指标	✅ 有
OpenTelemetry	分布式追踪	⚠️ 推测有 header helper
Datadog	APM	❓ 推测无

13. 关键洞察¶

13.1 4 通道不混用¶

logError / logEvent / profileCheckpoint / analytics sink —— 各司其职。

13.2 命名约定强制安全¶

_I_VERIFIED_* —— 类型级契约。

13.3 subcommand sink 修复¶

PR #11106 —— 防止 subcommand 丢事件。

13.4 GrowthBook 集成¶

feature flag + A/B test。

13.5 50+ events¶

tengu_* 前缀 —— 业务覆盖广。

13.6 用户可控¶

isAnalyticsDisabled —— 隐私友好。

13.7 Sinks 抽象¶

fan-out 多目的地。

13.8 启动 profiler 独立通道¶

与业务事件分离。

14. 改进方向¶

14.1 完整 OTel 集成¶

import { trace } from '@opentelemetry/api'

分布式追踪。

14.2 错误聚合¶

// Sentry / Rollbar

错误聚合服务。

14.3 业务 dashboard¶

// Statsig 自定义 dashboard

业务指标可视化。

14.4 用户级别遥测¶

// per-user metrics

用户行为分析。

15. 阅读建议¶

看 services/analytics/index.js —— logEvent 入口
看 utils/log.js —— logError
看 utils/sinks.ts —— sink 抽象
看 utils/startupProfiler.js —— profileCheckpoint
grep logEvent 全文 —— 50+ 事件分布

16. 与其他分析的关系¶

文件	关系
`performance-history.md`	启动 profiler
`security-audit.md`	错误脱敏
`architecture-history.md`	演进