otel-desktop-viewer JSON-RPC API 详解后端与前端通信的核心机制【免费下载链接】otel-desktop-viewerotel-desktop-viewer is a CLI tool for receiving OpenTelemetry traces while working on your local machine.项目地址: https://gitcode.com/gh_mirrors/ot/otel-desktop-viewerotel-desktop-viewer是一个强大的本地 OpenTelemetry 数据查看工具它的核心通信机制基于 JSON-RPC API。这个 API 是后端 Go 服务与前端 Svelte 界面之间的桥梁让开发者能够轻松探索和分析本地收集的追踪、指标和日志数据。本文将深入解析这个 JSON-RPC API 的设计原理、接口规范和使用方法帮助你更好地理解和使用这个工具。什么是 JSON-RPC APIJSON-RPC 是一种轻量级的远程过程调用协议使用 JSON 格式进行数据交换。在 otel-desktop-viewer 中JSON-RPC API 负责处理前端与后端之间的所有数据通信包括数据查询、搜索、删除等操作。API 架构设计otel-desktop-viewer 的 JSON-RPC API 采用单一端点设计所有请求都通过POST /rpc端点处理。这种设计简化了 API 结构同时保持了类型安全和方法调用的清晰性。核心组件API 的实现位于 desktopexporter/internal/server/jsonrpc_handler.go 文件中主要包含以下关键部分JSONRPCHandler 结构体处理所有 JSON-RPC 请求的处理器方法分发机制根据请求的 method 字段路由到对应的处理函数错误处理系统自定义错误代码和映射逻辑参数解析统一的时间戳和查询参数解析完整的 JSON-RPC 方法列表otel-desktop-viewer 提供了丰富的 JSON-RPC 方法覆盖了追踪、日志、指标三大信号类型的数据操作。追踪相关方法方法名称参数返回值功能描述searchTraces[startTime, endTime, queryTree?]TraceSummary[]搜索时间范围内的追踪摘要searchSpans[traceID, queryTree?]TraceData获取指定追踪的所有跨度详情getTraceAttributes[startTime, endTime]FieldDefinition[]获取追踪属性定义getAttributesByTraceID[traceID]FieldDefinition[]获取指定追踪的属性getTraceSpanCount[traceID]number获取追踪的跨度数量clearTraces[]void清除所有追踪数据deleteSpansByTraceID[traceIDs]void按追踪ID删除跨度deleteSpanByID[spanID]void按跨度ID删除日志相关方法方法名称参数返回值功能描述searchLogs[startTime, endTime, queryTree?]LogSummary[]搜索时间范围内的日志摘要getLog[logID]LogData获取单个日志的完整数据getLogAttributes[startTime, endTime]FieldDefinition[]获取日志属性定义clearLogs[]void清除所有日志数据deleteLogByID[logID]void按日志ID删除指标相关方法方法名称参数返回值功能描述searchMetricSummaries[startTime, endTime, queryTree?]MetricSummary[]搜索指标摘要getMetric[streamId, startTime, endTime]MetricData获取指标的详细数据getMetricAttributes[startTime, endTime]FieldDefinition[]获取指标属性定义clearMetrics[]void清除所有指标数据通用方法方法名称参数返回值功能描述getStats[]Stats获取统计数据用于轮询更新请求和响应格式请求格式所有 JSON-RPC 请求都遵循以下格式{ jsonrpc: 2.0, method: searchTraces, params: [1704067200000000000, 1704153599000000000, {...}], id: 123456 }jsonrpc固定为 2.0method要调用的方法名称params参数数组时间戳使用纳秒字符串格式id请求标识符用于匹配响应响应格式成功响应{ jsonrpc: 2.0, result: [...], id: 123456 }错误响应{ jsonrpc: 2.0, error: { code: -32001, message: Trace not found }, id: 123456 }时间戳处理API 中的所有时间参数都使用纳秒精度的时间戳字符串。前端在发送请求前需要将毫秒时间戳转换为纳秒字符串// 前端转换函数位于 telemetry-service.ts function toNanoseconds(milliseconds: number): string { return milliseconds 0 ? 0 : milliseconds.toString() 000000 }查询树系统otel-desktop-viewer 支持复杂的查询功能通过查询树Query Tree系统实现。查询树允许用户构建复杂的过滤条件支持逻辑运算符和嵌套查询。查询树结构查询树有两种类型节点条件节点Condition包含字段、运算符和值分组节点Group包含逻辑运算符和子节点数组查询树转换前端构建的查询树在发送到后端前需要转换为简化格式function convertQueryTreeForBackend(queryTree: QueryNode): any { if (queryTree.type condition) { return { id: queryTree.id, type: condition, query: { field: { ...(queryTree.query.field.searchScope ! global { name: queryTree.query.field.name, type: queryTree.query.field.type, }), searchScope: queryTree.query.field.searchScope, ...(queryTree.query.field.searchScope attribute { attributeScope: queryTree.query.field.attributeScope, }), }, fieldOperator: queryTree.query.operator.symbol, value: queryTree.query.value, }, } } else { return { id: queryTree.id, type: group, group: { logicalOperator: queryTree.group.operator, children: queryTree.group.children.map(convertQueryTreeForBackend), }, } } }错误处理机制API 定义了丰富的错误代码便于前端进行精确的错误处理错误代码错误消息含义-32001Trace not found追踪未找到-32002Log not found日志未找到-32004Invalid trace ID无效的追踪ID-32005Invalid log ID无效的日志ID-32006Span not found跨度未找到-32007Invalid query无效的查询-32600Invalid RequestJSON-RPC 无效请求-32601Method not found方法未找到-32602Invalid params无效参数-32603Internal error内部错误前端 API 客户端前端通过 desktopexporter/internal/frontend/src/services/telemetry-service.ts 文件中的telemetryAPI对象与后端通信。API 调用示例// 搜索追踪 const traces await telemetryAPI.searchTraces( startTime, // 毫秒时间戳 endTime, // 毫秒时间戳 queryTree // 可选的查询树 ) // 获取追踪详情 const traceData await telemetryAPI.searchSpans(traceID, queryTree) // 获取统计数据用于轮询更新 const stats await telemetryAPI.getStats()数据类型转换前端 API 客户端负责将后端返回的 JSON 数据转换为类型化的 TypeScript 对象特别是处理大整数时间戳的转换function traceSummaryFromJSON(json: any): TraceSummary { return { ...json, rootSpan: json.rootSpan ?? undefined, startTime: parseBigInt(json.startTime), // 转换为 BigInt durationNs: parseNullableBigInt(json.durationNs), } }实时更新机制otel-desktop-viewer 使用轮询机制实现实时数据更新。前端定期调用getStats方法检查是否有新数据到达// 定期轮询统计数据 setInterval(async () { const stats await telemetryAPI.getStats() // 检查是否有新数据 if (stats.traces.lastReceived lastPollTime) { // 刷新数据 refreshData() } }, 5000) // 每5秒轮询一次性能优化特性1. 批量数据查询API 支持批量查询减少网络往返次数提高数据加载效率。2. 智能数据分页通过时间范围和查询条件实现数据分页避免一次性加载过多数据。3. 属性发现机制getTraceAttributes、getLogAttributes、getMetricAttributes等方法允许前端动态发现可用的属性字段实现灵活的过滤功能。4. 数据压缩后端直接生成 JSON 响应避免中间数据结构的序列化开销。使用场景示例场景一查看追踪详情// 1. 搜索时间范围内的追踪 const traces await telemetryAPI.searchTraces( Date.now() - 3600000, // 1小时前 Date.now(), // 现在 null // 无查询条件 ) // 2. 选择第一个追踪查看详情 if (traces.length 0) { const traceID traces[0].traceId const traceDetails await telemetryAPI.searchSpans(traceID) // 3. 获取追踪属性 const attributes await telemetryAPI.getAttributesByTraceID(traceID) }场景二搜索特定日志// 构建查询树搜索包含 error 的日志 const queryTree { type: condition, id: 1, query: { field: { name: body, type: string, searchScope: global }, operator: { symbol: contains }, value: error } } // 执行搜索 const logs await telemetryAPI.searchLogs( Date.now() - 300000, // 5分钟前 Date.now(), queryTree )场景三监控指标变化// 定期获取指标摘要 setInterval(async () { const metrics await telemetryAPI.searchMetricSummaries( Date.now() - 60000, // 1分钟前 Date.now() ) // 检查特定指标 const cpuMetric metrics.find(m m.name cpu.usage) if (cpuMetric) { const cpuData await telemetryAPI.getMetric( cpuMetric.streamId, Date.now() - 60000, Date.now() ) // 处理指标数据 } }, 10000) // 每10秒更新一次最佳实践建议1. 合理设置时间范围避免查询过大的时间范围建议使用分页或增量查询。2. 使用查询树优化搜索充分利用查询树的过滤能力减少不必要的数据传输。3. 错误处理始终处理 API 调用可能返回的错误使用 try-catch 包装异步调用。4. 性能监控监控 API 响应时间对于频繁调用的接口考虑添加缓存机制。5. 数据类型安全利用 TypeScript 的类型系统确保 API 调用的类型安全。总结otel-desktop-viewer 的 JSON-RPC API 设计体现了现代 Web 应用的最佳实践简洁的接口设计、类型安全的通信机制、灵活的查询系统和良好的错误处理。通过这个 API开发者可以轻松构建强大的 OpenTelemetry 数据分析工具实现本地开发环境下的实时监控和调试。无论是简单的数据查看还是复杂的分析需求这个 API 都提供了完整的支持。通过深入了解 API 的工作原理和使用方法你可以更高效地利用 otel-desktop-viewer 进行本地开发和调试工作。【免费下载链接】otel-desktop-viewerotel-desktop-viewer is a CLI tool for receiving OpenTelemetry traces while working on your local machine.项目地址: https://gitcode.com/gh_mirrors/ot/otel-desktop-viewer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考