Java 에이전트 API: 주석을 사용하는 계측

New Relic의 Java 에이전트는 사용자 정의 계측 을 위한 여러 옵션을 제공합니다. 이러한 옵션 중 하나는 애플리케이션 코드에 Java 에이전트 API의 @Trace , @TraceLambda 또는 @TraceByReturnType 주석을 추가하는 것입니다. 이 문서에서는 주석을 사용하는 방법을 설명합니다.

주석은 기본적으로 활성화되어 있습니다.

기본적으로 구성 설정 enable_custom_tracing 은 Java 에이전트에서 true 로 설정되며 이는 @Trace 주석이 작동하는 데 필요한 설정입니다.

이 설정은 기본적으로 newrelic.yml 에 포함되지 않습니다 . 주석을 비활성화하려면 newrelic.yml 의 common 섹션에 enable_custom_tracing: false (앞에 공백 2개 추가)을 설정하세요.

@추적하다

메소드에 @Trace 주석을 추가하면 해당 메소드에 대해 측정을 수행해야 함을 Java 에이전트에 알립니다.

메서드 호출을 사용자 지정 추적으로 추가하려면 메서드에 @Trace 주석을 추가하세요. 이러한 주석이 모두 포함되어 있으므로 클래스 경로에 newrelic-api.jar 가 나타나는지 확인하십시오.

import com.newrelic.api.agent.Trace;

...

  @Trace
  public void run() {
    // background task
  }

새 트랜잭션 만들기

트랜잭션이 표시되지 않고 새 트랜잭션을 시작하려면 @Trace 주석과 함께 dispatcher=true 을 포함합니다.

@Trace (dispatcher=true)
public void run() {
  // background task
}

거래에 세부 정보 추가

트랜잭션 추적에 계측되지 않은 시간의 큰 블록이 표시되고 추적 내에 메서드를 더 포함하려는 경우 매개변수 없이 @Trace 주석을 사용할 수 있습니다.

@Trace
protected void methodWithinTransaction() {
  // work
}

트랜잭션을 웹 요청으로 변환

백그라운드 작업 보고서를 Java 에이전트 API 호출로 웹 브라우저 트랜잭션으로 만들려면 다음을 수행합니다. @Trace(dispatcher=true) 주석이 달린 메서드에서 다음을 호출합니다.

NewRelic.setRequestAndResponse(Request request, Response response)

인수는 newrelic-api.jar 의 Request 및 Response 인터페이스 구현입니다.

고유한 @Trace 주석 클래스 정의

고유한 @Trace 주석 클래스를 정의하는 경우 newrelic-api.jar 에 대한 종속성이 없습니다. 클래스를 정의하려면:

package com.test;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)

public @interface Trace {
  public static final String NULL = "";
  String metricName() default NULL;
  boolean dispatcher() default false;
  String tracerFactoryName() default NULL;
}

그런 다음 newrelic.yml 의 common 섹션에서 이 주석을 사용하도록 에이전트를 구성합니다.

class_transformer:
  trace_annotation_class_name: com.test.Trace

@Trace의 속성

@Trace 주석은 다음 속성을 지원합니다.

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

이 기능은 기본적으로 비활성화되어 있으며 명시적으로 활성화해야 합니다(예: -Dnewrelic.config.instrumentation.trace_lambda.enabled=true) 주석이 적용됩니다. 동등한 환경 변수는 NEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLED 입니다.

트랜잭션 추적에 계측되지 않은 시간의 큰 블록이 표시되고 추적 내에 람다 표현식을 포함하려는 경우 매개변수 없이 @TraceLambda 주석을 사용할 수 있습니다.

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

람다 식은 컴파일 후에 포함하는 클래스의 정적 메서드가 됩니다. 기본적으로 주석 패턴과 일치하는 @TraceLambda 주석으로 표시된 클래스 내의 정적 메서드는 @Trace 주석으로 표시됩니다.

@TraceLambda 속성

@TraceLambda 주석은 다음 속성을 지원합니다.

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

추적 내에 특정 반환 유형이 있는 메서드를 포함하려면 @TraceByReturnType 주석을 사용하여 반환 유형을 속성으로 전달하는 클래스를 표시할 수 있습니다. 지정된 반환 유형 중 하나와 일치하는 주석이 있는 클래스의 메서드는 @Trace 주석으로 표시됩니다.

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  // ...
}

@TraceByReturnType 속성

@TraceByReturnType 주석은 다음 속성을 지원합니다.

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  public String doSomething() { // matches
    // ...
  }

  public Long somethingElse() { // does not match
    // ...
  }
}

성능 고려 사항

Java 에이전트가 JVM에 있는 경우 주석이 있는 메서드에 코드를 삽입합니다. 데이터베이스 또는 웹 서비스 호출과 같은 대규모 작업에서는 성능 저하가 무시할 수 있지만 초당 수천 번 호출되는 접근자와 같이 자주 호출되는 메서드에서는 눈에 띄게 나타납니다.

더 많은 API 기능

Java 에이전트 API 및 해당 기능에 대한 자세한 내용은 Java 에이전트 API 소개 를 참조하십시오.