面向首次接触开源 APM 的后端与 DevOps 工程师——一条 curl 命令跑起平台配置标准 OTLP 接入在 Web UI 里看到第一条分布式追踪。§1 为什么选 OTLP 标准 开源 APM告别专有 Agent 绑定用 OpenTelemetry 生态通用协议接入应用性能监控。痛点传统 APM 往往绑定自家探针换后端就要改 SDK、重采数据。OpenTelemetryOTel把 Trace / Metrics / Logs 统一成 OTLP 协议应用侧只需配置 Exporter 指向后端 Ingest 地址即可实现应用性能监控与全链路追踪。Databuff是国产开源 APM以 OTLP 为唯一接入标准。架构上只有三个核心容器Ingest接入、Doris存储、Web平台对比 SkyWalking 等多组件栈部署与运维成本显著降低。对比维度专有 Agent APMOTLP 开源 APMDatabuff接入协议厂商私有格式OTLP gRPC 4317 / HTTP 4318应用改造绑定特定 SDK任意 OTel SDK / Auto-Instrumentation部署组件Probe OAP Storage UI 等Ingest Doris Web3 容器许可商业 / 混合开源AGPL-3.0全栈开源源码中 Ingest 服务暴露的标准 OTLP 端口定义如下deploy/local/docker-compose.ymlai-apm-ingest:ports:-4317:4317# OTLP gRPC-4318:4318# OTLP HTTP入门建议HTTP 4318 端点http://host:4318/v1/traces对 curl / Demo / 多数 SDK 最友好gRPC 4317 适合高吞吐生产场景。§2 环境准备与 ai-apm-install.sh 安装Docker Compose · root 执行 · 约 5 分钟出 Web UI前置条件操作系统Linuxamd64 / arm64 均支持脚本自动识别架构下载镜像包依赖Docker、Docker Compose、curl、tar权限需 root 运行安装目录默认/opt/databuff-ai-apm内存建议 ≥ 8 GB 可用内存Doris FE/BE 三服务容器一条命令安装平台官方安装脚本ai-apm-install.sh完成 5 步全自动流程检查环境 → 下载部署包 → 加载镜像 → 清理旧版本 → 安装并启动。# 最新版一键安装curl-fsSLhttps://databuff.ai/databuff/ai-apm-install.sh|bash# 指定版本curl-fsSLhttps://databuff.ai/databuff/ai-apm-install.sh|bash-s----version0.1.1安装成功后脚本show_summary()会打印 Web UI、默认账号与 Ingest 地址Web UI http://host-ip:27403 账号 admin / Databuff123 Ingest http://host-ip:4318/v1/traces服务端口用途Web UI27403应用性能监控控制台、AI 平台入口Ingest (OTLP HTTP)4318Trace / Metrics HTTP 上报Ingest (OTLP gRPC)4317Trace / Metrics gRPC 上报Doris FE8030 / 9030存储引擎内部一般无需直连常用运维命令cd/opt/databuff-ai-apm ./start.sh# 启动./stop.sh# 停止§3 Demo 应用安装与 OTLP Exporter 配置不想先改业务代码先装 Demo 造数再对照配置自己的应用。Demo 一键造数平台装好后执行 Demo 安装脚本会持续向 Ingest 上报模拟 Trace打开 UI 即可看到服务拓扑与全链路追踪数据。curl-fsSLhttps://databuff.ai/databuff/ai-apm-demo-install.sh|bashDemo 容器通过环境变量指向 Ingest与业务应用配置方式一致ai-apm-demo:environment:OTEL_EXPORTER_OTLP_ENDPOINT:http://ai-apm-ingest:4318SEED_INTERVAL_SECONDS:30自有应用接入示例Java / Spring BootOpenTelemetry Java AgentexportOTEL_SERVICE_NAMEorder-serviceexportOTEL_EXPORTER_OTLP_ENDPOINThttp://ingest-host:4318exportOTEL_EXPORTER_OTLP_PROTOCOLhttp/protobufjava-javaagent:opentelemetry-javaagent.jar-jarorder-service.jarNode.jsopentelemetry/sdk-node核心配置constexporternewOTLPTraceExporter({url:http://ingest-host:4318/v1/traces,});// serviceName 设为可识别的服务名便于服务列表聚合验证上报是否成功安装 Demo 后等待约 30 秒SEED_INTERVAL_SECONDS刷新 Web UI 服务列表若仍为空检查防火墙是否放行 4318 端口、Exporter URL 是否带/v1/traces后缀HTTP 协议。§4 Web UI 验证服务列表 → 链路追踪登录http://host:27403按「拓扑 → 指标 → 链路」路径确认数据可见。Step 1 · 服务列表进入应用性能 → 服务可看到 Demo 产生的service-a、service-b等服务以及调用数、错误率、响应时间等指标——这是应用性能监控的入口视图。图 1 · 服务列表 — Top 图表 服务表格证明 OTLP 数据已成功入库Step 2 · 全局大盘打开全局大盘按分钟查看各服务健康时间轴与告警分布快速判断整体运行态势。图 2 · 全局大盘 — 各服务健康时间轴一览Step 3 · 链路追踪首条 Trace进入应用性能 → 链路追踪选择最近 1 小时时间范围即可看到 Trace 数量分布与响应时间散点图。点击任意 Trace 可下钻到 Span 瀑布图完成从「部署」到「看到第一条分布式追踪」的闭环。图 3 · 链路追踪 — Trace 数量与响应时间分布分布式追踪能力验证推荐排查路径全局拓扑发现异常节点 → 服务详情确认指标 → 链路追踪定位慢 Span。§5 常见问题部署与接入阶段最高频的问题问题原因 / 处理4317 / 4318 端口不通检查云安全组 / iptables 是否放行容器内用curl http://127.0.0.1:4318/health确认 Ingest 健康业务侧 Exporter 地址填宿主机 IP而非 Docker 内部 hostname跨主机上报时8 GB 内存够吗本地开发 / Demo 验证足够。Doris FE 768m BE 3G ingest/web 各 384m合计约 5 GB 容器上限生产建议 16 GB 并调大 Doris 堆内存AI 问数需要 LLM Key 吗APM 链路追踪不依赖 LLM无 Key 也能完整使用服务列表、拓扑、Trace。AI 平台需在「配置管理 → 模型配置」填入 API Key 后启用智能问数 / 巡检可选安装脚本报 Docker 不可用确认docker info正常、当前用户为 rootCompose 需 v2 及以上服务列表为空先装 Demo 或确认应用 Exporter 已指向正确 Ingest等待 1–2 分钟让分钟级聚合完成检查OTEL_SERVICE_NAME是否已设置
