otel-desktop-viewer：本地OpenTelemetry可观测性可视化工具-尧图网络科技

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界面。

技术栈对比

特性	otel-desktop-viewer	传统方案
部署复杂度	单二进制，零配置	需要配置Collector、存储、UI等多个组件
存储引擎	DuckDB（内存/磁盘）	通常需要Jaeger、Prometheus、Loki等独立存储
数据持久化	可选，通过`--db`参数控制	通常需要独立数据库配置
开发体验	实时数据可视化，无需外部依赖	需要搭建完整观测栈
资源占用	轻量级，适合本地开发	资源消耗较大

实战部署：快速启动指南

多种安装方式

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

端口配置说明

端口	协议	用途	默认值
8000	HTTP	Web UI和JSON-RPC API	是
4317	gRPC	OTLP gRPC接收器	是
4318	HTTP	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

命令行参数详解

参数	类型	默认值	说明
`--browser-port`	int	8000	Web UI和JSON-RPC API端口
`--db`	string	(内存)	DuckDB文件路径，用于持久化存储
`--grpc`	int	4317	OTLP gRPC监听端口
`--http`	int	4318	OTLP HTTP监听端口
`--host`	string	localhost	所有端点的绑定地址
`--open-browser`	bool	true	启动时自动打开浏览器

应用场景示例

场景一：微服务本地调试

在本地开发微服务时，通过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主要面向本地开发，但可以与生产环境监控栈协同工作：

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

扩展开发建议

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

后端扩展：

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

前端扩展：

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

性能优化技巧

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

最佳实践总结

开发工作流优化

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

调试技巧

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

故障排查指南

问题现象	可能原因	解决方案
无法访问Web UI	端口冲突	检查端口占用，使用`--browser-port`指定其他端口
OTLP数据未显示	协议不匹配	确认SDK配置的协议与监听端口一致
内存占用过高	数据量过大	启用磁盘存储或定期清理数据
查询性能下降	数据量增长	考虑添加索引或优化查询