开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载$/setTrace是 Language Server ProtocolLSP中一条由客户端编辑器/IDE发往服务端语言服务器的通知用于在运行时动态修改服务器的 trace追踪设置从而精确控制服务端通过$/logTrace通知上报执行轨迹的详细程度。本文以仓库中 setTrace 规范文档 为主体结合 TraceValue 类型定义、initialize 请求 与 3.17 版 metaModel.json 元数据系统讲解该通知的协议定义、参数结构、取值语义、与$/logTrace的联动关系以及在实际语言客户端与服务端中的落地要点帮助你完整掌握 LSP 运行时追踪的配置机制。一、为什么需要$/setTrace从初始化到运行时的追踪级别控制在 LSP 中语言服务器的执行轨迹trace上报能力并非一成不变。追踪级别最初由客户端在发送initialize请求时通过InitializeParams.trace字段设定但语言服务器是长期运行的进程用户可能随时需要开启或关闭调试信息此时不可能重启服务器重新握手。$/setTrace通知正是为解决这个问题而设计客户端可以在会话进行中的任意时刻通过一条轻量级通知修改服务端的 trace 设置无需重启语言服务器也无需重新初始化。规范原文明确指出A notification that should be used by the client to modify the trace setting of the server.这条通知属于 LSP 的基础协议base protocol消息与$/cancelRequest、$/progress等一样以$前缀标识其为通用基础设施消息而非针对某个具体语言特性如补全、跳转定义的功能消息。二、协议定义与参数结构2.1 通知Notification形态$/setTrace是一条单向通知notification方向为客户端到服务端client → servermethod方法名$/setTraceparams参数SetTraceParams返回无通知不产生响应metaModel 中对其的登记也印证了这一方向与结构metaModel.json 第 21142120 行{ method: $/setTrace, messageDirection: clientToServer, params: { kind: reference, name: SetTraceParams } }2.2SetTraceParams类型规范给出的SetTraceParams定义极其精简只有一个必填字段interface SetTraceParams { /** * The new value that should be assigned to the trace setting. */ value: TraceValue; }valueTraceValue类型表示要赋给服务端 trace 设置的新值。该字段必填且只能取TraceValue枚举中的三个合法字符串之一。metaModel 中对应的结构化定义metaModel.json 第 63956405 行确认该结构仅含value一个属性其类型引用TraceValues枚举{ name: SetTraceParams, properties: [ { name: value, type: { kind: reference, name: TraceValues } } ] }2.3TraceValue三种追踪级别TraceValue定义在 traceValue.md 中export type TraceValue off | messages | verbose;三种取值的语义如下metaModel 中 TraceValues 枚举 第 1382413846 行给出了权威说明取值说明对$/logTrace上报的影响off关闭追踪Turn tracing off服务端不应发送任何$/logTrace通知messages仅追踪消息Trace messages only服务端应发送$/logTrace但不得携带verbose字段verbose详细消息追踪Verbose message tracing服务端应发送$/logTrace并可在参数中附带verbose详细信息{ name: TraceValues, type: { kind: base, name: string }, values: [ { name: Off, value: off, documentation: Turn tracing off. }, { name: Messages, value: messages, documentation: Trace messages only. }, { name: Verbose, value: verbose, documentation: Verbose message tracing. } ] }2.4 追踪的初始值InitializeParams.trace$/setTrace修改的正是初始化时确立的同一份 trace 设置。在 initialize 请求 中InitializeParams携带了初始追踪值interface InitializeParams extends WorkDoneProgressParams { // ... /** * The initial trace setting. If omitted trace is disabled (off). */ trace?: TraceValue; // ... }关键点trace为可选字段省略时默认为off追踪关闭因此$/setTrace通常用于将默认关闭的追踪动态打开例如排障时切到verbose或在使用完毕后降级回off/messages以降低性能开销初始化阶段与服务端协商了初始级别运行阶段则由$/setTrace接管后续调整两者共用同一TraceValue枚举语义完全一致。三、$/setTrace与$/logTrace的联动追踪数据的产生与消费$/setTrace本身不传输任何追踪数据它只是开关和旋钮真正的追踪数据由$/logTrace通知承载。二者构成一对典型的客户端配置 → 服务端上报闭环方向恰好相反$/setTraceclient → server修改服务端的 trace 级别$/logTraceserver → client按当前 trace 级别上报执行轨迹。$/logTrace见 logTrace.md的参数结构为interface LogTraceParams { /** * The message to be logged. */ message: string; /** * Additional information that can be computed if the trace configuration * is set to verbose */ verbose?: string; }规范明确了$/logTrace上报量与当前 trace 配置的严格对应关系trace off服务端不应发送任何$/logTrace通知trace messages服务端发送$/logTrace但LogTraceParams.verbose字段必须省略不得添加trace verbose服务端发送$/logTrace且允许鼓励计算并填充verbose字段提供超出message的附加细节。metaModel 对LogTraceParams的结构化描述metaModel.json 第 64066424 行同样标注了verbose为可选optional: true与规范一致{ name: LogTraceParams, properties: [ { name: message, type: { kind: base, name: string } }, { name: verbose, type: { kind: base, name: string }, optional: true } ] }此外规范还强调了一条使用边界$/logTrace仅用于系统性的轨迹上报对于零散的、一次性的调试消息服务端应改用window/logMessage通知避免把日志通道与追踪通道混为一谈。四、实战应用一次完整的动态调追踪流程综合上述协议定义客户端动态调整服务端追踪级别的完整链路如下初始化协商客户端发送initialize请求在InitializeParams.trace中给出初始级别如省略则服务端按off处理动态调整会话运行期间当用户需要排障时客户端向服务端发送{ jsonrpc: 2.0, method: $/setTrace, params: { value: verbose } }一条完整的 LSP 通知报文示例jsonrpc固定为2.0通知无id字段服务端不返回响应。服务端响应上报服务端收到后将内部 trace 设置更新为verbose随后按新级别发送$/logTrace通知例如{ jsonrpc: 2.0, method: $/logTrace, params: { message: Processing textDocument/hover request, verbose: request: textDocument/hover at position 1:10, document: file:///workspace/src/main.ts } }降级恢复排障结束后客户端发送{ value: off }或{ value: messages }关闭或收敛追踪减少不必要的通信开销。五、服务端实现要点与注意事项从服务端实现角度看处理$/setTrace有以下实践要点实现方式收到$/setTrace后将内部追踪状态更新为参数value对应的枚举值即可通常映射到日志框架的日志级别由于是通知处理过程不应抛错返回通知无响应通道但要保证状态变更对后续$/logTrace的过滤逻辑立即生效过滤逻辑$/logTrace的发送逻辑必须严格遵循规范——off时不发送、messages时不带verbose、verbose时才计算verbose字段避免过度发送导致客户端日志刷屏通道职责分离系统性的执行轨迹走$/logTrace单独的调试/错误信息走window/logMessage二者互补而非替代初始值兜底即使客户端从未发送过$/setTrace服务端也应能依据initialize请求中的trace缺失时视为off正确工作保证$/setTrace只是锦上添花的动态能力而非前置依赖。六、版本与配套资料$/setTrace自 LSP 早期版本base protocol沿用至今在仓库的 3.17、3.18、3.19 三份规范中均有对应文档见 _includes/messages/3.17/setTrace.md、_includes/messages/3.18/setTrace.md 等协议定义保持一致。如需深入掌握相关主题仓库内可直接研读TraceValue 类型定义追踪级别枚举及初始值语义LogTrace 通知规范追踪数据上报通道与字段约束Initialize 请求规范初始追踪值的设置与默认值说明3.17 完整规范将本通知置于完整协议上下文中阅读第 479 行处引入 setTrace 小节metaModel.json机器可读的结构化元数据包含$/setTrace消息、SetTraceParams结构与TraceValues枚举的精确定义可用于代码生成与协议校验。小结$/setTrace用最精简的参数结构一个value字段、三个枚举取值实现了语言服务器运行期追踪级别的动态调控初始化时由InitializeParams.trace设定初值默认off运行中由$/setTrace随时改写服务端再依据当前级别通过$/logTrace按off/messages/verbose三档精确控制执行轨迹的上报内容与详细程度。理解并正确实现这一对通知是语言服务器调试体验与日志治理的关键一环。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐language-server-protocol 3.17 之 workspace/applyEdit服务器驱动客户端执行 WorkspaceEdit 的完整协议指南language server protocol 3.17 之 workspace/applyEdit服务器驱动客户端执行 WorkspaceEdit 的完整开发工具使用 RouterSploit 复现 Cisco RV320 命令注入漏洞CVE-2019-1652证书生成器远程命令执行实战使用 RouterSploit 复现 Cisco RV320 命令注入漏洞CVE 2019 1652证书生成器远程命令执行实战 本文以 RouterSpl开发工具书转 Skill 到底值不值book-to-skill 深度解析——把整书塞进上下文之前先算这笔账书转 Skill 到底值不值book to skill 深度解析——把整书塞进上下文之前先算这笔账 你手头有一本 400 页的技术书想让 AI 助手在写代开发工具上一篇【亲测免费】 推荐Bootstrap Tree View - 极简优雅的树形视图组件下一篇【亲测免费】 推荐开源项目AngularJS UI Select —— 搜索选择器的完美升级创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考