OpenTelemetry API를 사용한 자바(Java) 커스텀 계측

Unsure when to use OpenTelemetry with Datadog? Start with Custom Instrumentation with the OpenTelemetry API to learn more.

Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

  • You are not using Datadog supported library instrumentation.
  • You want to extend the ddtrace library’s functionality.
  • You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

설정

OpenTelemetry는 자바 버전 1.24.0 이후 이상에서 지원됩니다.

OpenTelemetry를 설정하여 Datadog 트레이스 공급자를 사용하려면,

  1. 자동-계측 및 설정에 대한 지침을 아직 읽지 않았다면 자바 설정 지침부터 시작하세요.

  2. OpenTelemetry SDK가 아닌 OpenTelemetry API만 사용하는 것을 기억하세요.

  3. dd.trace.otel.enabled 시스템 속성 또는 DD_TRACE_OTEL_ENABLED 환경 변수를 true로 설정합니다.

스팬(span) 태그 추가하기

커스텀 스팬(span) 태그 추가

애플리케이션 코드 내의 동적 값(예: customer.id)에 해당하는 스팬(span)에 커스텀 태그를 추가합니다.

import io.opentelemetry.api.trace.Span;

public void doSomething() {
  Span span = Span.current();
  span.setAttribute("user-name", "Some User");
}

모든 스팬(span)에 글로벌 태그 추가

dd.tags 속성을 사용하면 애플리케이션에 대해 생성된 모든 스팬(span)에 태그를 설정할 수 있습니다. 애플리케이션, 데이터 센터 또는 Datadog에서 확인히려는 다른 태그의 통계를 그룹화하는 데 유용합니다.

java -javaagent:<DD-JAVA-AGENT-PATH>.jar \
    -Ddd.tags=datacenter:njc,<TAG_KEY>:<TAG_VALUE> \
    -jar <YOUR_APPLICATION_PATH>.jar

하위 스팬에서 루트 스팬의 오류 설정하기

하위 스팬에서 루트 스팬의 오류를 설정하려면 이와 같이 현재 스팬에서 setStatus 메서드를 사용할 수 있습니다.

import static io.opentelemetry.api.trace.StatusCode.ERROR;
import io.opentelemetry.api.trace.Span;

public void doSomething() {
  Span span = Span.current();
  span.setStatus(ERROR, "Some error details...");
}

하위 스팬에서 루트 스팬에 태그와 오류 설정하기

이 예는 하위 스팬에서 루트 스팬에 태그와 오류를 설정하는 방법을 보여줍니다.

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.ContextKey;
import io.opentelemetry.context.Scope;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.ResourceAttributes;
import java.util.concurrent.TimeUnit;

public class Example {

  private final static ContextKey<Span> CONTEXT_KEY =
    ContextKey.named("opentelemetry-traces-local-root-span");

  public void begin() {
    tracer = GlobalOpenTelemetry.getTracer("my-scope", "0.1.0");
    Span parentSpan = tracer.spanBuilder("begin").startSpan();
    try (Scope scope = parentSpan.makeCurrent()) {
      createChildSpan();
    } finally {
      parentSpan.end();
    }
  }

  private void createChildSpan() {
    Span childSpan = tracer.spanBuilder("child-span").startSpan();
    try {
      Span rootSpan = Context.current().get(CONTEXT_KEY);
        if (null != rootSpan) {
          rootSpan.setAttribute("my-attribute", "my-attribute-value");
          rootSpan.setStatus(StatusCode.ERROR, "Some error details...");
        } 
    } finally {
      childSpan.end();
    }
  }

}

스팬(span) 추가

지원되는 프레임워크 계측를 사용하지 않거나 애플리케이션의 트레이스에 깊이를 더하고 싶은 경우, 코드에 커스텀 계측을 추가하여 완전한 불꽃 그래프를 보거나 코드 조각들의 실행 시간을 측정할 수 있습니다.

애플리케이션 코드를 수정할 수 없는 경우 환경 변수 dd.trace 메서드를 사용하여 이러한 메서드를 구체화합니다.

기존 @트레이스 또는 이와 유사한 주석이 있는 경우나 주석을 사용하여 Datadog 내에서 불완전한 트레이스를 완성하려는 경우, 트레이스 주석을 사용하세요.

트레이스는 또한 트레이스 주석에서 설명된 대로 OpenTelemetry @WithSpan 주석을 사용하여 생성할 수도 있습니다.

트레이스 주석

메서드에 @WithSpan 을 추가하여 OpenTelemetry 및 dd-java-agent.jar을 실행할 때 추적하도록 합니다. 에이전트가 첨부되지 않은 경우 이 주석은 애플리케이션에 영향을 미치지 않습니다. OpenTelemetry의 @WithSpan 주석은 opentelemetry-instrumentation-annotations 종속성으로 제공됩니다.

import io.opentelemetry.instrumentation.annotations.WithSpan;

public class SessionManager {

  @WithSpan
  public static void saveSession() {
    // your method implementation here
  }
}

신규 스팬(span) 수동 생성

현재 트레이스 컨텍스트 내에서 새로운 스팬을 수동으로 생성하려면 다음을 수행하세요.

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.ResourceAttributes;
import java.util.concurrent.TimeUnit;

public class Example {

  public void doSomething() {
    Tracer tracer = GlobalOpenTelemetry.getTracer("my-scope", "0.1.0");
    Span span = tracer.spanBuilder("my-resource").startSpan();
    try (Scope scope = span.makeCurrent()) {
      // do some work
    } catch (Throwable t) {
      span.recordException(t);
      throw t;
    } finally {
      span.end();
    }
  }

}

트레이스 클라이언트 및 에이전트 설정

추적 클라이언트 및 Datadog 에이전트 모두 컨텍스트 전파를 위한 추가 설정 옵션을 제공합니다. 상태 점검과 관련된 트레이스 등 트레이스가 산출된 메트릭에 포함되지 않도록 하려면, 특정 리소스를 제외하여 트레이스를 Datadog에 전송하지 않을 수도 있습니다.

헤더를 추출 및 삽입하여 컨텍스트 전파

헤더를 삽입하고 추출하여 분산된 트레이스 컨텍스트 전파를 설정할 수 있습니다. 자세한 내용은 트레이스 컨텍스트 전파를 참조하세요.

리소스 필터링

트레이스는 리소스 이름을 기준으로 제외할 수 있습니다. 이를 통해 상태 점검과 같은 신서틱(Synthetic) 트래픽을 제거하여 Datadog에 트레이스를 보고하지 않도록 할 수 있습니다. 이와 더불어 보안 및 설정 조정은 보안 또는 원치 않는 리소스 무시를 참조할 수 있습니다.

참고 자료

추가 유용한 문서, 링크 및 기사:

서비스, 리소스, 트레이스 탐색설명서 more more OpenTelemetry API 상호 운용성 및 Datadog의 계측된 트레이스설명서 more more
PREVIEWING: may/unit-testing