Java Custom Instrumentation using the OpenTelemetry API

이 페이지는 아직 영어로 제공되지 않습니다. 번역 작업 중입니다.
현재 번역 프로젝트에 대한 질문이나 피드백이 있으신 경우 언제든지 연락주시기 바랍니다.
Datadog과 함께 OpenTelemetry를 언제 사용해야 하는지 OpenTelemetry API를 사용한 커스텀 계측에서 확인해 보세요.

개요

다음의 경우 OpenTelemetry API를 사용해 애플리케이션을 수동으로 계측해야 합니다.

  • Datadog이 지원하는 라이브러리 계측을 사용하고 있지 않습니다.
  • ddtrace 라이브러리의 기능을 확장하고 싶습니다.
  • 애플리케이션 계측을 보다 세밀하게 제어해야 합니다.

ddtrace 라이브러리는 이러한 목표를 달성하는 데 도움이 됩니다. 다음 섹션에서는 커스텀 계측을 위해 Datadog과 OpenTelemetry API를 함께 사용하는 방법을 다룹니다.

설정

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