• 로그인

사용자의 편의를 위해 제공되는 기계 번역입니다.

영문본과 번역본이 일치하지 않는 경우 영문본이 우선합니다. 보다 자세한 내용은 이 페이지를 방문하시기 바랍니다.

문제 신고

Java 에이전트 API: 외부 호출, 메시징, 데이터 저장소, 웹 프레임워크 계측

New Relic의 Java 에이전트는 백그라운드 작업과 같은 웹 트랜잭션웹이 아닌 트랜잭션에 대한 정보를 수집하고 보고합니다. 에이전트는 애플리케이션 코드를 수정할 필요 없이 지원되는 프레임워크를 자동으로 계측해야 합니다. 그러나 Java 에이전트 설명서에 대한 호환성 및 요구 사항에 나열되지 않은 사용자 지정 코드 및 프레임워크 또는 기술 외에도 지원되는 프레임워크의 일부 구현에는 사용자 지정 계측 이 필요할 수 있습니다.

이 문서에서는 Java 에이전트 API 를 사용하여 외부 호출, 메시징 프레임워크, CAT( 교차 애플리케이션 추적 ), 데이터 저장소 및 웹 프레임워크를 계측하는 방법을 설명합니다. API를 사용할 때 최상의 결과를 얻으려면 최신 Java 에이전트 릴리스 가 있는지 확인하십시오. 예제에 사용된 여러 API에는 Java 에이전트 3.36.0 이상이 필요합니다.

외부 API

외부 API를 사용하면 애플리케이션에서 New Relic에 대한 외부 서비스 호출을 보고할 수 있습니다. 이 정보는 APM의 외부 서비스 페이지 에 나타납니다. HTTP 외부 활동을 보고하려면 HttpParameters 빌더를 사용하여 ExternalParameters 의 인스턴스를 만들고 보고하려는 추적된 메서드에서 reportAsExternal(ExternalParameters parameters) 를 호출하기만 하면 됩니다.

외부 매개변수 빌더

ExternalParameters 을(를) 생성할 여러 빌더가 있습니다.

  • DatastoreParameters
  • HttpParameters
  • GenericParameters
  • MessageConsumeParameters
  • MessageProduceParameters

이러한 빌더는TracedMethod reportAsExternal API 호출에 대한 입력 매개변수 객체를 생성합니다. 이러한 매개변수 개체는 애플리케이션 간 추적을 통한 HTTP 외부 호출 연결, 데이터 저장소에 대한 외부 호출 추적, 추가 느린 쿼리 처리로 데이터 저장소에 대한 외부 호출 추적, 메시지 생성자와 소비자 간의 호출 추적과 같은 작업에 사용됩니다.

중요

이 클래스의 모든 메서드는 민감한 개인 정보를 노출할 가능성이 있습니다. URI 및 문자열 값에 특히 주의하여 인수를 생성할 때 주의하십시오.

분산 추적 API

분산 추적 API를 사용하면 New Relic Java 에이전트가 New Relic Java 에이전트 또는 다른 개방형 계측 표준 도구에 의해 계측되는 애플리케이션 간에 트랜잭션을 연결할 수 있습니다. 에이전트가 요청에 대한 헤더를 읽고 쓸 수 있도록 래퍼를 사용합니다.

헤더 래퍼

에이전트는 Headers 인터페이스를 사용하여 요청에 대한 헤더를 읽고 씁니다. 클라이언트와 서버 모두 통신 프레임워크의 클래스를 사용하여 이 인터페이스를 구현해야 합니다. 예를 들어:

래퍼를 사용한 분산 추적 구현

이전 섹션에서 설명한 래퍼 개체를 사용하여 Java 에이전트가 클라이언트 및 서버 측에서 추적을 보고하도록 할 수 있습니다. 예를 들어:

이 샘플 코드에서 에이전트는 요청을 시작하는 클라이언트에서 분산 추적을 사용하여 외부 호출을 보고하도록 구성되어 있습니다. 이러한 단계는 다음과 같이 요약할 수 있습니다.

  1. 클라이언트에서 프레임워크 클래스를 사용하여 Headers 를 구현합니다.
  2. 에이전트가 아웃바운드 요청에 적절한 헤더를 추가하도록 하려면 insertDistributedTraceHeaders(Headers headers) 을 사용합니다.

이 샘플 코드에서 에이전트는 요청에서 헤더를 읽도록 구성됩니다. 이러한 단계는 다음과 같이 요약할 수 있습니다.

  1. 서버에서 프레임워크 클래스를 사용하여 Headers 을 구현합니다.
  2. acceptDistributedTraceHeaders(TransportType transportType, Headers headers) 을 사용하여 이 트랜잭션을 호출한 트랜잭션에 연결합니다.

교차 애플리케이션 추적 API

중요

교차 애플리케이션 추적은 에이전트 버전 7.4.0부터 더 이상 사용되지 않으며 향후 에이전트 버전에서 제거될 예정입니다.

교차 애플리케이션 추적을 사용하는 대신 분산 추적 기능을 사용하는 것이 좋습니다. 분산 추적은 애플리케이션 간 추적 기능을 개선한 것으로 대규모 분산 시스템에 권장됩니다.

CAT( 크로스 애플리케이션 추적 ) API를 사용하면 New Relic Java 에이전트가 New Relic에서 모니터링하는 애플리케이션 간에 트랜잭션을 연결할 수 있습니다. API는 에이전트가 요청에서 헤더를 읽고 응답에 헤더를 추가할 수 있도록 하는 클라이언트 및 서버 래퍼를 사용합니다.

Docs site

클라이언트 래퍼

에이전트가 요청을 시작하는 클라이언트에서 아웃바운드 요청 헤더를 작성하려면 OutboundHeaders 인터페이스를 사용합니다. 예를 들어:

에이전트가 응답을 수신하는 클라이언트에서 인바운드 응답 헤더를 읽으려면 InboundHeaders 을 구현합니다. 예를 들어:

서버 래퍼

에이전트가 웹 요청 헤더를 가져오려면 ExtendedRequest 클래스를 확장해야 합니다.

에이전트가 웹 응답 헤더를 설정하려면 Response 인터페이스를 구현합니다.

래퍼를 사용한 CAT 구현

이전 섹션에서 설명한 래퍼 개체를 사용하여 Java 에이전트가 클라이언트 및 서버 측에서 CAT(Cross Application Tracing)을 수행하도록 할 수 있습니다. 예를 들어:

이 샘플 코드에서 에이전트는 요청을 시작하는 클라이언트에서 CAT를 사용하여 외부 호출을 보고하도록 구성되어 있습니다. 이러한 단계는 다음과 같이 요약할 수 있습니다.

  1. 클라이언트에서 프레임워크 클래스를 사용하여 OutboundHeadersInboundHeaders 을 구현합니다.
  2. 에이전트가 아웃바운드 요청에 적절한 헤더를 추가하도록 하려면 addOutboundRequestHeaders(OutboundHeaders outboundHeaders) 을 사용합니다.
  3. HttpParameters 빌더를 사용하여 ExternalParameters 객체를 만들고 인바운드 응답 헤더를 제공합니다.
  4. reportAsExternal(ExternalParameters params) 을 사용하여 외부 요청으로 보고합니다.

이 샘플 코드에서 에이전트는 요청에 응답하는 서버에서 CAT를 사용하여 외부 호출을 보고하도록 구성되어 있습니다. 이러한 단계는 다음과 같이 요약할 수 있습니다.

  1. 서버에서 프레임워크 클래스를 사용하여 Response 을 구현하고 ExtendedRequest 클래스를 확장합니다.

  2. setWebRequest(ExtendedRequest request)setWebResponse(Response response) 을 사용하여 트랜잭션을 웹 트랜잭션으로 변환하고 에이전트에 인바운드 요청 헤더와 아웃바운드 헤더를 기록할 장소를 함께 제공합니다.

    트랜잭션 이름은 요청 객체에 의존하고 응답 코드는 응답 객체에 의존하기 때문에 setWebRequest(ExtendedRequest request)setWebResponse(Response response) 을 함께 사용하는 것이 중요합니다.

  3. 에이전트가 아웃바운드 응답에 적절한 헤더를 추가하도록 하려면 addOutboundResponseHeaders() 을 사용합니다.

  4. markResponseSent() 에 대한 호출로 응답의 끝을 표시합니다.

메시징 API

메시징 API를 사용하면 애플리케이션이 메시지 대기열 브로커와의 상호 작용을 보고할 수 있습니다. MessageConsumerParametersMessageMessageConsumerParameters 을 제공하여 외부 API를 기반으로 빌드됩니다.

이 API는 메시지 브로커 상호 작용을 식별하는 데 필요한 메트릭을 생성합니다. UI는 이러한 메트릭을 사용하여 적절한 작업 및 개수(메시지 넣기 또는 메시지 가져오기)가 있는 트랜잭션의 세그먼트, 트랜잭션 추적의 전용 메시지 탭 등을 포함하는 메시징 데이터를 표시합니다. API에 인바운드 및 아웃바운드 헤더를 제공하면 에이전트가 CAT 헤더를 추가하고 CAT 메트릭을 기록할 수 있으므로 UI가 애플리케이션 간의 연결을 표시하는 서비스 맵 을 그릴 수 있습니다.

중요

메시징 API는 생산자와 소비자 간의 양방향 통신에 의존합니다. 생성자가 소비자로부터 승인을 받지 못한 경우(예: fire-and-forget 패턴) 메시징 API는 메시지 대기열 브로커와의 상호 작용을 정확하게 반영하지 않습니다.

다음 예는 가상의 JMS 라이브러리를 계측하는 방법을 보여줍니다.

단순화하기 위해 에이전트는 sendMessageToQueue 이 항상 메시지를 명명된 대기열에 넣는다고 가정합니다. 실제로 메시지는 명명된 대기열, 임시 대기열, 주제 및 임시 주제를 비롯한 다양한 대상 유형으로 전송될 수 있습니다. API는 다양한 대상 유형 NAMED_QUEUE , TEMP_QUEUE , NAMED_TOPIC , TEMP_TOPIC )에 메시지를 보고하는 열거형을 제공합니다. UI가 명명된 대기열 및 명명된 주제의 이름을 표시하고 임시 대기열 및 임시 주제의 이름을 생략하기 때문에 적절한 대상 유형을 지정하는 것이 중요합니다.

라이브러리가 CAT 헤더를 전송할 수 있는 경우 에이전트가 CAT 헤더를 추가할 수 있도록 OutboundHeaders 객체가 API에 제공됩니다.

데이터 저장소 API

추적된 메서드가 외부 데이터 저장소 호출로 보고되면 호출이 APM 데이터베이스 페이지에 표시됩니다. 데이터 저장소는 실행 중인 애플리케이션의 외부에 있으므로 이 메서드는 reportAsExternal(ExternalParameters params) 메서드를 사용하여 데이터 저장소 활동으로 보고됩니다. 유일한 차이점은 다른 빌더 DatastoreParameters 가 적절한 ExternalParameters 객체를 생성하는 데 사용된다는 것입니다.

Datastore API: 느린 쿼리

이 API 호출은 Datastore API 호출 과 동일한 동작을 제공하고 느린 쿼리 정보를 추적할 수 있도록 확장합니다. 동일한 reportAsExternal(ExternalParameters params) 메소드 및 빌더가 사용되지만 추가 빌더 메소드가 있습니다.

웹프레임웍스 API

WebFrameworks API를 사용하면 에이전트가 애플리케이션에 대한 추가 식별 정보를 보고할 수 있습니다.

// Set the dispatcher name and version which is reported to APM.
// The dispatcherName is intended to represent the type of server that this
// application is running on such as: Tomcat, Jetty, Netty, etc.
NewRelic.setServerInfo(String dispatcherName, String version)
// Set the app server port which is reported to APM.
NewRelic.setAppServerPort(int port)
// Set the instance name in the environment.
// A single host:port may support multiple JVM instances.
// The instance name is intended to help identify a specific JVM instance.
NewRelic.setInstanceName(String instanceName)

이 값은 한 번만 설정할 수 있습니다. 후속 호출은 영향을 미치지 않습니다.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.