otel-desktop-viewer：本地OpenTelemetry可观测性可视化工具

【免费下载链接】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

🔧本地开发监控⚡实时数据可视化📊一体化观测平台

otel-desktop-viewer是一款专为本地开发环境设计的OpenTelemetry可视化CLI工具，它将追踪、指标和日志三大观测信号整合到统一的Web界面中，为开发者提供开箱即用的本地可观测性解决方案。

核心理念：本地优先的观测性体验

架构设计哲学

otel-desktop-viewer采用"单二进制、零配置"的设计理念，基于OpenTelemetry Collector构建，但摒弃了传统Collector的复杂配置。项目核心架构采用DuckDB作为存储引擎，通过Go语言实现高性能数据摄取，前端使用Svelte 5构建响应式Web界面。

技术栈对比

实战部署：快速启动指南

多种安装方式

Homebrew安装（macOS用户）

brew tap ctrlspice/otel-desktop-viewer brew install --cask otel-desktop-viewer

Docker运行

docker run -p 8000:8000 -p 4317:4317 -p 4318:4318 \ ghcr.io/ctrlspice/otel-desktop-viewer:latest

源码编译安装

go install github.com/CtrlSpice/otel-desktop-viewer@latest export PATH="$(go env GOPATH)/bin:$PATH" otel-desktop-viewer

Docker Compose集成

在现有Docker Compose项目中添加otel-desktop-viewer服务：

services: your-app: image: your-app:latest environment: OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-desktop-viewer:4318 OTEL_TRACES_EXPORTER: otlp OTEL_METRICS_EXPORTER: otlp OTEL_LOGS_EXPORTER: otlp otel-desktop-viewer: image: ghcr.io/ctrlspice/otel-desktop-viewer:latest ports: - "8000:8000" # Web UI - "4317:4317" # OTLP gRPC - "4318:4318" # OTLP HTTP

端口配置说明

高级配置：自定义数据流

环境变量配置

根据应用程序使用的SDK，配置相应的环境变量：

# HTTP协议配置 export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318" export OTEL_TRACES_EXPORTER="otlp" export OTEL_METRICS_EXPORTER="otlp" export OTEL_LOGS_EXPORTER="otlp" export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" # gRPC协议配置 export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

数据持久化配置

默认情况下，otel-desktop-viewer使用内存存储。通过--db参数可以启用磁盘持久化：

# 使用磁盘存储，重启后数据不丢失 otel-desktop-viewer --db ./telemetry.duckdb # 自定义端口配置 otel-desktop-viewer --browser-port 8080 --grpc 4319 --http 4320

命令行参数详解

应用场景示例

场景一：微服务本地调试

在本地开发微服务时，通过otel-desktop-viewer可以实时查看服务间的调用链路：

追踪界面功能：

• 甘特图展示完整的调用链路
• 服务间依赖关系可视化
• 每个Span的详细元数据查看
• 错误状态和耗时分析

场景二：性能指标监控

开发过程中监控应用程序的性能指标：

指标界面特性：

• 实时指标数据可视化
• 热图展示指标分布
• 多维度聚合分析
• 时间序列图表

场景三：日志集中查看

统一查看应用程序的结构化日志：

日志界面功能：

• 结构化日志条目展示
• 按时间、服务、级别过滤
• 日志与追踪关联查看
• 完整的资源和作用域信息

场景四：Shell脚本追踪

使用otel-cli从Shell脚本发送追踪数据：

# 配置otel-cli指向本地otel-desktop-viewer export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # 执行命令并生成追踪 otel-cli exec --service my-service --name "check the archive" \ curl -s -o /dev/null https://archive.org/ # 链式Span示例 otel-cli exec --kind producer --service demo --name produce -- \ otel-cli exec --kind consumer --service demo --name consume sleep 0.2

技术实现深度解析

存储架构设计

otel-desktop-viewer采用高度规范化的数据库设计，确保查询性能和存储效率：

核心表结构：

• spans- 追踪Span记录
• events- Span事件（规范化存储）
• links- Span链接（规范化存储）
• logs- 日志记录
• metric_streams- 指标流元数据
• datapoints- 所有指标数据点
• attributes- 所有实体的属性键值对

设计亮点：

• 所有ID使用UUID格式
• 嵌套数据规范化存储，避免数组和联合类型
• 单一datapoints表存储所有类型指标
• 属性统一存储在attributes表中，支持跨实体搜索

查询优化策略

项目采用JSON-RPC over HTTP作为API传输协议，查询层直接在SQL中构建JSON响应：

-- 示例：构建追踪查询的JSON响应 SELECT json_object( 'trace_id', trace_id, 'spans', json_arrayagg( json_object( 'span_id', span_id, 'name', name, 'start_time', start_time, 'end_time', end_time ) ) ) AS trace_json FROM spans WHERE trace_id = ? GROUP BY trace_id

这种设计使得响应结构在SQL中定义，避免了Go结构体的重复定义，同时保持了前端的灵活性。

前端架构模式

前端采用现代化的技术栈和架构模式：

技术栈组成：

• 框架：Svelte 5（使用Runes：$state,$derived,$effect）
• 构建工具：Vite 7
• 路由：tinro5（历史模式）
• 样式：Tailwind CSS 4 + DaisyUI 5
• 图表：layerchart
• 搜索UI：CodeMirror 6 + 自定义Lezer语法

状态管理策略：

• 无全局状态管理库
• 使用Svelte上下文模块（.svelte.ts）
• 页面局部状态使用$state
• 实时更新通过轮询getStats实现

生态集成建议

与现有监控栈集成

虽然otel-desktop-viewer主要面向本地开发，但可以与生产环境监控栈协同工作：

1. 开发/生产环境分离：本地使用otel-desktop-viewer，生产环境使用Jaeger、Prometheus等
2. 数据导出：通过自定义导出器将本地数据同步到生产环境
3. 配置管理：使用环境变量区分不同环境的OTLP端点

扩展开发建议

项目采用模块化设计，便于功能扩展：

后端扩展：

• 在desktopexporter/internal/store/中添加新的存储模块
• 在desktopexporter/internal/server/中添加新的API端点
• 通过components.go注册新的Collector组件

前端扩展：

• 在desktopexporter/internal/frontend/src/pages/中添加新页面
• 使用现有的组件库和样式系统
• 通过services/telemetry-service.ts扩展API客户端

性能优化技巧

1. 内存管理：对于大量数据，使用--db参数启用磁盘存储
2. 查询优化：利用DuckDB的列式存储特性，优化查询性能
3. 前端性能：虚拟化长列表，使用懒加载技术

最佳实践总结

开发工作流优化

# 开发模式：前后端分离运行 make dev-go # 启动Go服务器 (:8000) make dev-ts # 启动Vite开发服务器 (:3001) # 生产模式：构建并运行 make build # 构建完整二进制文件 ./otel-desktop-viewer # 运行生产版本

调试技巧

1. 实时数据查看：启动应用后立即访问http://localhost:8000
2. 数据清理：使用UI中的清除功能或重启服务清空内存数据
3. 网络调试：使用curl测试OTLP端点连通性

故障排查指南

otel-desktop-viewer作为本地开发环境中的OpenTelemetry可视化工具，通过简化配置、统一界面和实时反馈，显著提升了开发者的观测性体验。其基于DuckDB的存储设计和现代化的前端架构，为本地开发提供了专业级的监控能力，是微服务开发和分布式系统调试的理想伴侣。

【免费下载链接】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