尧图网站建设 
T3 Code可观测性体系详解日志、追踪与遥测如何组成故障排查闭环【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款开源的 AI 编程代理控制台支持通过 Web、桌面和移动端统一调度本机的 Claude、Codex 等编码代理。它的服务端内置了一套完整的可观测性体系人读的日志直接输出到控制台结构化的追踪Traces落盘为本地 NDJSON 文件指标Metrics与追踪可选择导出到 OTLP 后端另有匿名遥测Telemetry与进程级资源监控作为补充。对新手来说理解这三层数据如何分工就能在遇到请求失败界面卡顿时快速定位根因。T3 Code 可观测性的三大支柱日志、追踪与遥测T3 Code 采用单一、清晰的服务端可观测性模型三种数据各管一摊 数据类型去向适合回答的问题日志Logsstdout人类可读格式刚刚发生了什么追踪Traces本地 NDJSON 文件可选 OTLP 导出这一次请求具体卡在哪一步指标Metrics仅 OTLP 远程导出不落盘是不是整体变慢了哪类命令失败最多本地追踪文件是普通本地启动时持久化的事实来源它带轮转默认单文件 10 MB、保留 10 个文件任何一次会话的 span 数据都能事后复盘。整套观测层在 apps/server/src/observability/Layers/Observability.ts 中组装包括漂亮日志器、本地 NDJSON tracer、可选的 OTLP 追踪/指标导出器。日志直接看控制台不用翻文件T3 Code 的日志默认输出到 stdout使用Logger.consolePretty()美化渲染本地启动不写单独的日志文件——因为结构化信息都进追踪文件了。一个实用技巧在活跃 span 内用Effect.log...发出的日志会被Logger.tracerLogger自动挂为span 事件随追踪一起持久化。也就是说你在控制台看到的关键日志事后在追踪文件里也能找到上下文。SSH 托管的远程启动则会把远端进程的 stdout/stderr 额外落盘到~/.t3/ssh-launch/state/server.log。追踪本地 trace 文件在哪如何快速排查追踪是 T3 Code 可观测性的核心。已完成的 span 以 NDJSON 记录写入server.trace.ndjson路径因启动方式而异生产/默认 home~/.t3/userdata/logs/server.trace.ndjsonworktree 开发运行worktree/.t3/userdata/logs/server.trace.ndjson共享开发目录~/.t3/dev/logs/server.trace.ndjson每条记录包含traceId、spanId、parentSpanId、durationMs、attributes、events等字段effect-span类型还带有Success/Failure/Interrupted的退出状态。记录的模式定义位于 packages/shared/src/observability.ts。排查三板斧官方文档 docs/operations/observability.md 有完整命令找失败的 span过滤exit._tag ! Success的effect-span记录找慢的 span过滤durationMs 1000顺藤摸瓜用traceId把同一次请求的所有子 span 串起来看是哪个环节sqlite、git、provider、终端拖慢了整体。Agent 会话的每一步工具调用、代码变更都会经过 RPC 与编排引擎这些边界全部有 span 覆盖——界面如下所示的正在工作状态背后都有对应的追踪数据指标发现系统性性能问题接入 Grafana LGTM指标只通过 OTLP 导出不做本地持久化。当前定义的指标族都在 apps/server/src/observability/Metrics.ts重点关注这几组时长类t3_rpc_request_duration、t3_orchestration_command_duration、t3_provider_turn_duration、t3_git_command_duration计数类t3_rpc_requests_total、t3_orchestration_commands_total、t3_provider_turns_total其中t3_orchestration_command_ack_duration度量命令进入编排引擎 → 首个领域事件发布的服务端确认延迟是判断命令处理本身慢不慢的关键信号。想接入本地 Grafana LGTM 栈只需三步用 Docker 启动grafana/otel-lgtm镜像开放 3000 与 4317/4318 端口设置T3CODE_OTLP_TRACES_URL、T3CODE_OTLP_METRICS_URL、T3CODE_OTLP_SERVICE_NAME三个环境变量从同一 shell 完整重启应用——观测配置只在进程启动时读取改完环境变量必须彻底重启。在 Grafana 的 Explore 中选择 Tempo 数据源先用服务名如t3-local粗查再按 span 名如sendTurn或git.operation、orchestration.command_type属性收窄就能可视化地钻取任意一次请求的完整 span 树。遥测匿名产品分析数据流向哪里除排查故障T3 Code 还有面向产品本身的遥测层服务端通过 apps/server/src/telemetry/AnalyticsService.ts 向 PostHog 发送匿名产品事件如client.turn.requested、client.connected采用内存缓冲 批量上报并支持通过T3CODE_TELEMETRY_ENABLEDfalse完全关闭。隐私边界很明确标识符使用哈希后的账号 ID 或安装级匿名 ID不采集 URL、令牌、提示词、IP 地址或用户自定义设备名。事件与属性的完整语义见 docs/internals/product-analytics.md。资源遥测进程级的体检仪除了应用层观测T3 Code 还有一个独立的资源遥测子系统用常驻的 Rust 小程序替代反复ps/ioreg子进程探测原生监控进程通过操作系统 API 直接读取 CPU、内存、I/O 计数器历史保留在 1 小时、64 MiB 的有界环形缓冲中采样间隔随电源状态自适应交流电 1 秒、电池 5 秒、锁屏/热限 15 秒诊断页面可看到聚合 CPU/内存/I/O、可折叠的实时进程树、采集器自身开销甚至能对后端子进程做安全信号操作。设计原则是观察者成本可测量、故障可隔离监控进程崩溃不会影响服务端。完整架构见 docs/internals/resource-telemetry.md原生实现位于 native/resource-monitor/。远程可观测性Relay 服务如何接入 Axiom 追踪后端T3 Code 的云端 Relay 组件则演示了 OTLP 追踪在真实后端上的落地Worker、移动端与一方客户端共享同一个 Axiom OpenTelemetry 数据集各自持有数据集范围的只写 ingest token最小权限隔离写入方与查询方Worker 发出 Effect 内建 HTTP 服务端 span 及端点/数据库子 span排障时优先查预置的近期 span 视图而非滚动 Worker 日志DPoP 认证失败还会带上稳定的relay.dpop.failure_code属性如time_window提示时钟偏差让客户端自动判断是否为时钟问题。详见 docs/operations/relay-observability.md。故障排查闭环四步定位法把三层数据串起来就形成了完整的排查闭环 问这次为什么失败→ 打开本地server.trace.ndjson过滤失败 span按traceId分组检查同链路兄弟 span 与内嵌日志事件问是不是整体变慢→ 看指标趋势t3_rpc_request_duration等区分偶发慢与系统性慢问卡在哪个环节→ 在 Tempo 或 trace 文件中钻取子 span检查 sqlite、git 钩子git.hook.started/finished事件、provider 轮次等具体耗时问环境层面有没有异常→ 用资源遥测确认 CPU/内存/进程树健康度用遥测事件核对客户端连接与版本。一句话总结分工日志讲故事追踪答个案指标看趋势。核心文件速查表内容路径可观测性总文档含 jq 排查命令docs/operations/observability.md观测层组装Logger/Tracer/OTLPapps/server/src/observability/Layers/Observability.ts指标定义apps/server/src/observability/Metrics.tsRPC 请求埋点apps/server/src/observability/RpcInstrumentation.ts追踪记录模式NDJSON schemapackages/shared/src/observability.ts匿名遥测服务apps/server/src/telemetry/AnalyticsService.ts产品分析事件语义docs/internals/product-analytics.md资源遥测架构docs/internals/resource-telemetry.mdRelay 可观测性docs/operations/relay-observability.md这套本地零配置可用、需要时一键接入专业后端的设计让从第一次运行npx t3到深度故障排查始终有合适的数据粒度可用——这正是 T3 Code 可观测性体系值得借鉴的地方。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 T3 Code可观测性体系详解：日志、追踪与遥测如何组成故障排查闭环
T3 Code可观测性体系详解日志、追踪与遥测如何组成故障排查闭环【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeT3 Code 是一款开源的 AI 编程代理控制台支持通过 Web、桌面和移动端统一调度本机的 Claude、Codex 等编码代理。它的服务端内置了一套完整的可观测性体系人读的日志直接输出到控制台结构化的追踪Traces落盘为本地 NDJSON 文件指标Metrics与追踪可选择导出到 OTLP 后端另有匿名遥测Telemetry与进程级资源监控作为补充。对新手来说理解这三层数据如何分工就能在遇到请求失败界面卡顿时快速定位根因。T3 Code 可观测性的三大支柱日志、追踪与遥测T3 Code 采用单一、清晰的服务端可观测性模型三种数据各管一摊 数据类型去向适合回答的问题日志Logsstdout人类可读格式刚刚发生了什么追踪Traces本地 NDJSON 文件可选 OTLP 导出这一次请求具体卡在哪一步指标Metrics仅 OTLP 远程导出不落盘是不是整体变慢了哪类命令失败最多本地追踪文件是普通本地启动时持久化的事实来源它带轮转默认单文件 10 MB、保留 10 个文件任何一次会话的 span 数据都能事后复盘。整套观测层在 apps/server/src/observability/Layers/Observability.ts 中组装包括漂亮日志器、本地 NDJSON tracer、可选的 OTLP 追踪/指标导出器。日志直接看控制台不用翻文件T3 Code 的日志默认输出到 stdout使用Logger.consolePretty()美化渲染本地启动不写单独的日志文件——因为结构化信息都进追踪文件了。一个实用技巧在活跃 span 内用Effect.log...发出的日志会被Logger.tracerLogger自动挂为span 事件随追踪一起持久化。也就是说你在控制台看到的关键日志事后在追踪文件里也能找到上下文。SSH 托管的远程启动则会把远端进程的 stdout/stderr 额外落盘到~/.t3/ssh-launch/state/server.log。追踪本地 trace 文件在哪如何快速排查追踪是 T3 Code 可观测性的核心。已完成的 span 以 NDJSON 记录写入server.trace.ndjson路径因启动方式而异生产/默认 home~/.t3/userdata/logs/server.trace.ndjsonworktree 开发运行worktree/.t3/userdata/logs/server.trace.ndjson共享开发目录~/.t3/dev/logs/server.trace.ndjson每条记录包含traceId、spanId、parentSpanId、durationMs、attributes、events等字段effect-span类型还带有Success/Failure/Interrupted的退出状态。记录的模式定义位于 packages/shared/src/observability.ts。排查三板斧官方文档 docs/operations/observability.md 有完整命令找失败的 span过滤exit._tag ! Success的effect-span记录找慢的 span过滤durationMs 1000顺藤摸瓜用traceId把同一次请求的所有子 span 串起来看是哪个环节sqlite、git、provider、终端拖慢了整体。Agent 会话的每一步工具调用、代码变更都会经过 RPC 与编排引擎这些边界全部有 span 覆盖——界面如下所示的正在工作状态背后都有对应的追踪数据指标发现系统性性能问题接入 Grafana LGTM指标只通过 OTLP 导出不做本地持久化。当前定义的指标族都在 apps/server/src/observability/Metrics.ts重点关注这几组时长类t3_rpc_request_duration、t3_orchestration_command_duration、t3_provider_turn_duration、t3_git_command_duration计数类t3_rpc_requests_total、t3_orchestration_commands_total、t3_provider_turns_total其中t3_orchestration_command_ack_duration度量命令进入编排引擎 → 首个领域事件发布的服务端确认延迟是判断命令处理本身慢不慢的关键信号。想接入本地 Grafana LGTM 栈只需三步用 Docker 启动grafana/otel-lgtm镜像开放 3000 与 4317/4318 端口设置T3CODE_OTLP_TRACES_URL、T3CODE_OTLP_METRICS_URL、T3CODE_OTLP_SERVICE_NAME三个环境变量从同一 shell 完整重启应用——观测配置只在进程启动时读取改完环境变量必须彻底重启。在 Grafana 的 Explore 中选择 Tempo 数据源先用服务名如t3-local粗查再按 span 名如sendTurn或git.operation、orchestration.command_type属性收窄就能可视化地钻取任意一次请求的完整 span 树。遥测匿名产品分析数据流向哪里除排查故障T3 Code 还有面向产品本身的遥测层服务端通过 apps/server/src/telemetry/AnalyticsService.ts 向 PostHog 发送匿名产品事件如client.turn.requested、client.connected采用内存缓冲 批量上报并支持通过T3CODE_TELEMETRY_ENABLEDfalse完全关闭。隐私边界很明确标识符使用哈希后的账号 ID 或安装级匿名 ID不采集 URL、令牌、提示词、IP 地址或用户自定义设备名。事件与属性的完整语义见 docs/internals/product-analytics.md。资源遥测进程级的体检仪除了应用层观测T3 Code 还有一个独立的资源遥测子系统用常驻的 Rust 小程序替代反复ps/ioreg子进程探测原生监控进程通过操作系统 API 直接读取 CPU、内存、I/O 计数器历史保留在 1 小时、64 MiB 的有界环形缓冲中采样间隔随电源状态自适应交流电 1 秒、电池 5 秒、锁屏/热限 15 秒诊断页面可看到聚合 CPU/内存/I/O、可折叠的实时进程树、采集器自身开销甚至能对后端子进程做安全信号操作。设计原则是观察者成本可测量、故障可隔离监控进程崩溃不会影响服务端。完整架构见 docs/internals/resource-telemetry.md原生实现位于 native/resource-monitor/。远程可观测性Relay 服务如何接入 Axiom 追踪后端T3 Code 的云端 Relay 组件则演示了 OTLP 追踪在真实后端上的落地Worker、移动端与一方客户端共享同一个 Axiom OpenTelemetry 数据集各自持有数据集范围的只写 ingest token最小权限隔离写入方与查询方Worker 发出 Effect 内建 HTTP 服务端 span 及端点/数据库子 span排障时优先查预置的近期 span 视图而非滚动 Worker 日志DPoP 认证失败还会带上稳定的relay.dpop.failure_code属性如time_window提示时钟偏差让客户端自动判断是否为时钟问题。详见 docs/operations/relay-observability.md。故障排查闭环四步定位法把三层数据串起来就形成了完整的排查闭环 问这次为什么失败→ 打开本地server.trace.ndjson过滤失败 span按traceId分组检查同链路兄弟 span 与内嵌日志事件问是不是整体变慢→ 看指标趋势t3_rpc_request_duration等区分偶发慢与系统性慢问卡在哪个环节→ 在 Tempo 或 trace 文件中钻取子 span检查 sqlite、git 钩子git.hook.started/finished事件、provider 轮次等具体耗时问环境层面有没有异常→ 用资源遥测确认 CPU/内存/进程树健康度用遥测事件核对客户端连接与版本。一句话总结分工日志讲故事追踪答个案指标看趋势。核心文件速查表内容路径可观测性总文档含 jq 排查命令docs/operations/observability.md观测层组装Logger/Tracer/OTLPapps/server/src/observability/Layers/Observability.ts指标定义apps/server/src/observability/Metrics.tsRPC 请求埋点apps/server/src/observability/RpcInstrumentation.ts追踪记录模式NDJSON schemapackages/shared/src/observability.ts匿名遥测服务apps/server/src/telemetry/AnalyticsService.ts产品分析事件语义docs/internals/product-analytics.md资源遥测架构docs/internals/resource-telemetry.mdRelay 可观测性docs/operations/relay-observability.md这套本地零配置可用、需要时一键接入专业后端的设计让从第一次运行npx t3到深度故障排查始终有合适的数据粒度可用——这正是 T3 Code 可观测性体系值得借鉴的地方。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考