实用指南：如何学习 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 的 “数据传输通用语言”

OTel 生态的标准数据传输协议，用于在 Agent（采集端）和 Collector（接收端）之间传递 Trace、Log、Metrics 数据。其支撑两种传输方式：就是OTLP（OpenTelemetry Protocol）
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": ""
}
}