如何学习 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仓库

三、使用方法

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

json 复制代码

{
  "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": ""
  }
}