OpenTelemetry JAVA¶

Java 应用 + OpenTelemetry Java Agent -- OTLP Trace/Metric --> DataKit --> 观测云
Java 应用 -- 含 trace_id/span_id 的日志文件 --> DataKit logging --> 观测云

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

[[inputs.opentelemetry]]
  # 如需在观测云中将自定义属性作为标签保留，请在此加入白名单。
  # 属性名中的点会被转换为下划线，例如 team.name -> team_name。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

sudo datakit service restart

curl http://127.0.0.1:9529/v1/ping

sudo mkdir -p /opt/opentelemetry
sudo curl -fL \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar \
  -o /opt/opentelemetry/opentelemetry-javaagent.jar

export JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"

java -jar app.jar

java -javaagent:/opt/opentelemetry/opentelemetry-javaagent.jar \
  -Dotel.service.name=order-service \
  -Dotel.resource.attributes=env=prod,version=1.0.0,team=backend \
  -Dotel.traces.exporter=otlp \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=none \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.endpoint=http://127.0.0.1:9529/otel \
  -Dotel.propagators=tracecontext,baggage \
  -jar app.jar

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/opentelemetry/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"

只有在有效 Span 的上下文中产生的日志才会包含链路字段。应用启动日志、定时任务日志或未被插桩覆盖的异步任务日志可能没有 `trace_id` 和 `span_id`，这属于正常情况。字段名必须使用 Java Agent 注入的 `trace_id`、`span_id` 和 `trace_flags`，不要改成 `traceId` 或手动生成 ID。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <property name="LOG_DIR" value="/opt/order-service/logs"/>
    <property name="LOG_PATTERN"
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags}] - %msg%n"/>

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_DIR}/application.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/application.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>7</maxHistory>
            <totalSizeCap>5GB</totalSizeCap>
        </rollingPolicy>
        <encoder>
            <pattern>${LOG_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="FILE"/>
    </root>
</configuration>

logging.file.name=/opt/order-service/logs/application.log
logging.pattern.file=%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags}] - %msg%n

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Properties>
        <Property name="LOG_DIR">/opt/order-service/logs</Property>
        <Property name="LOG_PATTERN">%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5p %c{36} [trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags}] - %m%n%throwable</Property>
    </Properties>

    <Appenders>
        <RollingFile name="FILE"
                     fileName="${LOG_DIR}/application.log"
                     filePattern="${LOG_DIR}/application.%d{yyyy-MM-dd}.%i.log.gz">
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <SizeBasedTriggeringPolicy size="100 MB"/>
            </Policies>
            <DefaultRolloverStrategy max="7"/>
        </RollingFile>
    </Appenders>

    <Loggers>
        <Root level="info">
            <AppenderRef ref="FILE"/>
        </Root>
    </Loggers>
</Configuration>

2026-08-12 10:20:30.123 [http-nio-8080-exec-1] INFO  c.e.OrderController [trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7 trace_flags=01] - order created

[[inputs.logging]]
  logfiles = ["/opt/order-service/logs/*.log"]
  source = "java"
  service = "order-service"
  pipeline = "java_otel.p"
  character_encoding = "utf-8"

  # 将 Java 异常堆栈合并到对应日志；以日期开头的行视为一条新日志。
  enable_multiline = true
  multiline_match = '''^\d{4}-\d{2}-\d{2}'''

  remove_ansi_escape_codes = true
  from_beginning = false

  [inputs.logging.tags]
    env = "prod"
    version = "1.0.0"

grok(_, "%{TIMESTAMP_ISO8601:time} \\[%{DATA:thread_name}\\] %{LOGLEVEL:status}%{SPACE}%{NOTSPACE:class_name} \\[trace_id=%{DATA:trace_id} span_id=%{DATA:span_id} trace_flags=%{DATA:trace_flags}\\] - %{GREEDYDATA:msg}")
default_time(time)

sudo datakit service restart

tail -f /opt/order-service/logs/application.log

sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'