HyperDX Local：本地化OpenTelemetry观测平台部署指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00028/article/details/148441760

HyperDX Local：本地化OpenTelemetry观测平台部署指南

hyperdx Resolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors. 项目地址: https://gitcode.com/gh_mirrors/hy/hyperdx

什么是HyperDX Local

HyperDX Local是一个专为本地开发环境优化的轻量级观测平台，它基于OpenTelemetry标准，能够一站式收集、分析和可视化应用程序的日志(Logs)、指标(Metrics)和追踪(Traces)数据。与生产环境版本相比，这个本地化版本采用单容器架构设计，具有以下突出特点：

零配置快速启动：无需身份验证即可立即使用，简化了本地开发流程
资源占用优化：内存占用控制在1GB以内，适合开发机运行
全功能支持：完整保留核心观测功能，包括全文搜索、JSON解析和性能监控

核心功能解析

HyperDX Local作为观测平台的核心价值体现在：

三支柱数据统一处理：

日志：支持结构化/非结构化日志的自动解析和全文检索
指标：提供时间序列数据的实时可视化
追踪：完整展示分布式调用链路

开发者友好特性：

自动识别JSON格式日志并展开为可查询字段
内置可视化仪表板，支持自定义图表
原生OpenTelemetry协议支持，与现有监控体系无缝集成

快速入门指南

基础部署

通过Docker快速启动服务（建议至少分配1GB内存）：

docker run -p 8000:8000 -p 4318:4318 -p 4317:4317 -p 8080:8080 -p 8002:8002 docker.hyperdx.io/hyperdx/hyperdx-local

关键端口说明：

4317：OpenTelemetry gRPC接入点
4318：OpenTelemetry HTTP接入点
8080：Web可视化界面

启动后访问 http://localhost:8080 即可进入控制台。

应用接入配置

接入应用程序时需配置OpenTelemetry导出器：

# 环境变量方式配置
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# SDK初始化示例（Node.js）
const { NodeSDK } = require('@opentelemetry/sdk-node');
const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  metricExporter: new OTLPMetricExporter()
});
sdk.start();

注意：使用HyperDX专用SDK时需设置任意非空API_KEY值

高级配置技巧

自定义服务端口

如需修改默认端口，可通过环境变量调整：

# 修改API和APP端口示例
docker run \
  -e HYPERDX_APP_PORT=9080 \
  -e HYPERDX_API_PORT=9000 \
  -p 9000:8000 \
  -p 4318:4318 \
  -p 4317:4317 \
  -p 9080:8080 \
  -p 8002:8002 \
  docker.hyperdx.io/hyperdx/hyperdx-local

开发模式构建

如需自定义镜像，可执行构建脚本：

./docker/local/build.sh

版本对比与适用场景

Local版与完整版差异

| 特性 | Local版 | 完整版 | |---------------------|---------|--------| | 多用户支持 | ❌ | ✅ | | 数据持久化 | ❌ | ✅ | | 告警功能 | ❌ | ✅ | | 管理API | ❌ | ✅ | | 查询模式分析 | ❌ | ✅ |

适用场景建议：