Logging & Observability 专题¶

重要性：⭐⭐（可观测性细节——log + event + profiler + sink + metrics） 真实位置：src/utils/log.js + src/services/analytics/ + src/utils/startupProfiler.js + src/utils/sinks.ts 角色：4 通道可观测性关联：topics/cache-strategies.md、analysis/logging-telemetry.md

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 模式）
文件（~/.claude/logs/）
Statsig（采样）

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 参数：name + metadata + 类型契约。

3.2 命名¶

tengu_* 前缀
_I_VERIFIED_* 后缀

3.3 50+ events¶

tengu_managed_settings_loaded, tengu_code_prompt_ignored, tengu_single_word_prompt, tengu_teleport_interactive_mode, ...

4. profileCheckpoint¶

4.1 API¶

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

30+ 埋点 全文。

4.2 Statsig 上报¶

profileReport()  // 采样上报

远程监控。

5. Analytics Sink¶

5.1 services/analytics/¶

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

完整服务。

5.2 initSinks (preAction)¶

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

sink attach —— subcommand 也走。

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

5.3 GrowthBook¶

hasGrowthBookEnvOverride, initializeGrowthBook, refreshGrowthBookAfterAuthChange

feature flag + A/B test。

6. 4 类 Event 类别¶

类别	例子
启动 / 性能	tengu_managed_settings_loaded, tengu_exit_after_first_render
用户行为	tengu_code_prompt_ignored, tengu_single_word_prompt
会话	tengu_teleport_interactive_mode, tengu_teleport_resume_session
安全 / 警告	tengu_deprecated_setting, tengu_auth_failed

4 类 —— 完整业务覆盖。

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 —— fan-out。

7.2 attach¶

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

多 sink 并行。

8. 输出格式¶

8.1 控制台¶

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

dev 调试。

8.2 JSON¶

JSON.stringify({ event, metadata, timestamp })

结构化。

8.3 文件¶

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

每日一个文件。

9. 采样¶

类型	采样
错误 logError	100%（推测）
业务 logEvent	采样
profileCheckpoint	采样

不同采样率。

10. 隐私¶

10.1 命名约定¶

_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS —— 类型级强制。

10.2 脱敏¶

redactUrlCredentials, redactHeaders

显式脱敏。

10.3 用户控制¶

isAnalyticsDisabled

关闭遥测。

11. OpenTelemetry¶

11.1 自定义 headers¶

function getOtelHeadersFromHelper(): Record<string, string>

OTEL headers。

11.2 29min debounce¶

const DEFAULT_OTEL_HEADERS_DEBOUNCE_MS = 29 * 60 * 1000

防止频繁调。

12. 4 通道 vs 4 用途¶

通道	触发	频率	采样	目的地
logError	异常	罕见	100%	Sentry / file
logEvent	业务	频繁	采样	Statsig / 业务
profileCheckpoint	启动	启动时	采样	Statsig
analytics sink	业务	频繁	采样	聚合

4 通道 不同。

13. 关键设计模式¶

13.1 4 通道不混用¶

各司其职。

13.2 命名约定¶

类型级安全。

13.3 Sinks 抽象¶

fan-out。

13.4 subcommand sink 修复¶

PR #11106。

13.5 GrowthBook 集成¶

feature flag + A/B。

13.6 50+ events¶

tengu_* 前缀。

13.7 用户可控¶

isAnalyticsDisabled。

13.8 启动 profiler 独立¶

与业务事件分离。

14. 关键洞察¶

14.1 4 通道不混用¶

logError / logEvent / profileCheckpoint / sink。

14.2 命名约定强制¶