Java 语言快速开始

一、使用探针快速接入

Opentelemetry官方推荐Java语言无代码入侵的接入方案，提供了Java探针JAR包形式在Java 8及以上版本的应用程序下挂载到启动进程，能够动态地注入字节码生成埋点，支持对多款主流插件框架自动生成监控数据。通常情况下，快速接入推荐下载使用官方包，通过官方版本发布文档可以下载到最新版本探针包，下载完成后的JAR包中包含了所有数据采集需要的库，以及数据上报的exporters

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

探针包下载完成后，可以通过设置变量的形式指定探针包挂载路径以及监控数据上报方式，默认情况下Java探针使用OTLP exporter 将数据上报至本地OTLP Collector。在并未搭建OTLP Collector的体验环境下，可以将exporter数据导出设置为本地日志打印，如下展示设置的bash shell指令

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
  OTEL_TRACES_EXPORTER=logging \
  OTEL_METRICS_EXPORTER=logging \
  OTEL_LOGS_EXPORTER=logging \
  OTEL_METRIC_EXPORT_INTERVAL=15000

探针挂载路径中的PATH/TO需要替换为实际的JAR文件下载保存路径，快速体验过程中，可以将<font style="color:rgb(51, 51, 51);background-color:rgb(247, 249, 253);">OTEL_METRIC_EXPORT_INTERVAL</font>设置为远低于默认的值，以确保能够更快地生成正确的指标。设置完毕后，需要运行启动应用程序

java -jar myapp.jar

在应用进程的启动标准输出中，通过观察otel.javaagent相关的输出，可以确认Java探针的挂载情况。进程启动后，通过对应用程序进行访问，Java探针会自动生成trace以及metrics数据。在日志输出模式下，相关trace数据可以在客户端和服务端的标准日志中观察到如下的类似信息

[otel.javaagent 2023-04-24 17:33:54:567 +0200] [http-nio-8080-exec-1] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter - 'RollController.index' :
 70c2f04ec863a956e9af975ba0d983ee 7fd145f5cda13625 INTERNAL [tracer:
 io.opentelemetry.spring-webmvc-6.0:1.25.0-alpha] AttributesMap{data=
 {thread.id=39, thread.name=http-nio-8080-exec-1}, capacity=128,
 totalAddedValues=2}
[otel.javaagent 2023-04-24 17:33:54:568 +0200] [http-nio-8080-exec-1] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter - 'GET /rolldice' :
70c2f04ec863a956e9af975ba0d983ee 647ad186ad53eccf SERVER [tracer:
io.opentelemetry.tomcat-10.0:1.25.0-alpha] AttributesMap{
  data={user_agent.original=curl/7.87.0, net.host.name=localhost,
  net.transport=ip_tcp, http.target=/rolldice, net.sock.peer.addr=127.0.0.1,
  thread.name=http-nio-8080-exec-1, net.sock.peer.port=53422,
  http.route=/rolldice, net.sock.host.addr=127.0.0.1, thread.id=39,
  net.protocol.name=http, http.status_code=200, http.scheme=http,
  net.protocol.version=1.1, http.response_content_length=1,
  net.host.port=8080, http.method=GET}, capacity=128, totalAddedValues=17}

接下来，可以停止应用服务，停止后可以在标准日志中观察到进程中采集到的所有metrics指标的输出

[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
io.opentelemetry.exporter.logging.LoggingMetricExporter - Received a collection
 of 19 metrics for export.
[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
io.opentelemetry.exporter.logging.LoggingMetricExporter - metric:
ImmutableMetricData{resource=Resource{schemaUrl=
https://opentelemetry.io/schemas/1.19.0, attributes={host.arch="aarch64",
host.name="OPENTELEMETRY", os.description="Mac OS X 13.3.1", os.type="darwin",
process.command_args=[/bin/java, -jar, java-simple.jar],
process.executable.path="/bin/java", process.pid=64497,
process.runtime.description="Homebrew OpenJDK 64-Bit Server VM 20",
process.runtime.name="OpenJDK Runtime Environment",
process.runtime.version="20", service.name="java-simple",
telemetry.auto.version="1.25.0", telemetry.sdk.language="java",
telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.25.0"}},
instrumentationScopeInfo=InstrumentationScopeInfo{name=io.opentelemetry.runtime-metrics,
version=1.25.0, schemaUrl=null, attributes={}},
name=process.runtime.jvm.buffer.limit, description=Total capacity of the buffers
in this pool, unit=By, type=LONG_SUM, data=ImmutableSumData{points=
[ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes=
{pool="mapped - 'non-volatile memory'"}, value=0, exemplars=[]},
ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes={pool="mapped"},
value=0, exemplars=[]},
ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes={pool="direct"},
value=8192, exemplars=[]}], monotonic=false, aggregationTemporality=CUMULATIVE}}
...

二、将数据上报至collector

Java探针支持通过配置项形式选择不同的扩展库以及数据上报模式，可以通过环境变量或者启动参数的形式进行配置，有多种配置项扩展支持，可以指定不同的数据源、上报端点、以及采集配置。诸多开源以及厂商的监控数据处理工具都支持Opentelemetry协议，可以为Opentelemetry的使用提供多种选择，默认情况下Java探针使用OTLP exporter。

在实际生产环境中，使用OTLP Collector是官方推荐的最佳实践。在Java探针支持的所有exporters中，OTLP exporter是遵循Opentelemetry数据模型设计的，其发送的数据结构可以无损的与接Collector进行对接，实现无损发送OTel监控数据。在容器环境下，可以按照以下步骤创建OTLP Collector。

选择任意一个空白的文件夹路径，创建一个文件命名为collector-config.yaml，yaml文件内容为

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

使用如下指令通过docker容器运行Collector

docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector

Collector成功运行后即可以接收OTLP格式的监控数据，同时通过Collector也可以将监控数据投递到观测服务后端，将监控数据进行可视化展示。

三、数据可视化展示

Jaeger天然支持接收OTLP格式的trace数据，在docker容器环境下可以运行Jaeger监听16686端口，并且分别监听4317及4318端口启用OTLP数据接收，进行可视化UI展示。

使用如下指令，在docker容器环境运行Jaeger服务

docker run --rm \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

启动成功后，可以通过UI界面观察展示接收到的监控数据

trace数据展示界面

Prometheus支持接收OTLP格式的metric数据，启用Prometheus OTLP Receiver之后，Java探针通过MetricsReader会采集metrics数据并以Promethues格式发送。在docker容器环境启动Promethues实例，需要监听9090端口，按照如下格式创建prometheus.yml文件

scrape_configs:
  - job_name: dice-service
    scrape_interval: 5s
    static_configs:
      - targets: [host.docker.internal:9464]

在docker容器环境下运行Prometheus，可以通过9090端口访问

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --enable-feature=otlp-write-receive

应用启动成功后，可以通过UI界面观察展示接收到的监控数据