OpenTelemetry JAVA¶

Java 애플리케이션 + OpenTelemetry Java Agent -- OTLP Trace/Metric --> DataKit --> Guance
Java 애플리케이션 -- trace_id/span_id 포함 로그 파일 --> DataKit logging --> Guance

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

[[inputs.opentelemetry]]
  # Guance에서 사용자 정의 속성을 태그로 유지하려면 여기에 화이트리스트를 추가하십시오.
  # 속성 이름의 점은 밑줄로 변환됩니다. 예: 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/'