如何学习 OpenTelemetry-Java-Agent（一）：自定义 OTLP-HTTP-Collector 实现数据接收与格式化输出

在 OpenTelemetry（简称 OTel）生态中，Java Agent 是实现 “无侵入式” 数据采集的核心组件，而 Collector 则负责接收、处理 Agent 上报的 Trace、Log、Metrics 数据。本文作为系列第一篇，将聚焦 “自定义 OTLP-HTTP Collector” 的开发，带你从零实现一个能接收 Agent 数据、并格式化打印 OTLP 内容的服务，为后续深入学习 Java Agent 打下基础。

一、前置知识：OTLP 协议与 Collector 核心角色

在动手前，需先明确两个核心概念，避免开发中 “知其然不知其所以然”：

1. OTLP 协议：OpenTelemetry 的 “数据传输通用语言”

OTLP（OpenTelemetry Protocol）是 OTel 生态的标准数据传输协议，用于在 Agent（采集端）和 Collector（接收端）之间传递 Trace、Log、Metrics 数据。其支持两种传输方式：
gRPC：默认方式，适合高吞吐、低延迟场景；
HTTP/JSON：更易调试，适合初期学习和简单场景（本文选用此方式，降低理解门槛）。
OTLP 数据格式基于 Protobuf 定义，无论是 Trace、Log 还是 Metrics，都有对应的 Protobuf 模型（如 ExportTraceServiceRequest 对应 Trace 数据），这是我们后续解析数据的关键。

2. 自定义 Collector 的定位

官方 Collector（otelcol-contrib）功能强大但配置复杂，对于学习阶段而言，“从零写一个极简 Collector” 能更直观地理解数据流转过程。本文的自定义 Collector 核心职责：
启动 HTTP 服务，暴露 /v1/traces、/v1/logs、/v1/metrics 三个接口（OTLP-HTTP 标准接口路径）；
接收 Java Agent 上报的 Protobuf 格式数据；
解析数据并以 “人类可读” 的格式打印（如 JSON），方便观察数据结构。

二、项目结构与工程地址

1. 技术栈选择

开发语言：Java 11+（与 OTel Java 生态版本兼容）；
构建工具：Maven；
核心依赖：

• OTel Protobuf 模型：解析 OTLP 数据；
• Spring Boot Web：快速搭建 HTTP 服务（降低手动处理 HTTP 请求的复杂度）；
• Jackson：将解析后的 OTLP 数据转为 JSON 格式；
• Protobuf-Java：处理 Protobuf 序列化 / 反序列化。

2. 工程地址

自定义OTLP-HTTP Collector仓库

三、使用方法

1. 运行自定义工程的启动函数，默认会监听4318端口
2. 业务应用使用jvm参数接入opentememetry-java-instrumentation(Agent)，无需任何参数，采集的trace，logs，metrics都会发送到自定义的collector上，会格式化输出，比如格式化后的trace数据：

{"traceId": "D65A5A7636404416DDEC45BB89C7412E","spanId": "E1590E847DDF35D7","kind": "SPAN_KIND_CLIENT","name": "INSERT jjb.m_user","startTimeMs": 1759135610382,"attributes": {"server.address": "localhost","db.connection_string": "mysql://localhost:3306","db.user": "root","db.statement": "INSERT INTO m_user(id, name, age) VALUES(?, ?, ?)","db.system": "mysql","server.port": 3306,"db.sql.table": "m_user","db.operation": "INSERT","thread.name": "main","db.name": "jjb","thread.id": 1},"endTimeMs": 1759135610384,"parentSpanId": "","durationMs": 2,"events": {},"status": {"code": "STATUS_CODE_UNSET","message": ""}
}