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

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

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

외부 API

External API 사용하면 뉴렐릭에 외부 서비스 호출을 보고할 수 있습니다. 이 정보는 APM의 External services 페이지 에 나타납니다. HTTP 외부 활동을 보고하려면 HttpParameters 빌더를 사용하여 ExternalParameters 의 추가를 생성하고 보고하려는 트레이스 메서드에서 reportAsExternal(ExternalParameters parameters) 호출하면 됩니다.

String library = "HttpClient"; // a user-recognizable name for the library that is being used
URI uri = request.getURI();    // the URI that is being requested
String procedure = "execute";  // these are typically named after the method in the library that's being instrumented

// construct external parameters
ExternalParameters params = HttpParameters
    .library(library)
    .uri(uri)
    .procedure(procedure)
    .inboundHeaders(inboundHeaders)
    .build();

// report the current method as doing external activity
NewRelic.getAgent().getTracedMethod().reportAsExternal(params);

외부 매개변수 빌더

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

DatastoreParameters
HttpParameters
GenericParameters
MessageConsumeParameters
MessageProduceParameters

이러한 빌더는 TracedMethod 의 reportAsExternal API 호출에 대한 입력 시위, 객체를 생성합니다. 이러한 매개변수, 조치 개체는 분리 추적을 통해 HTTP 외부 호출 연결, 데이터스토어에 대한 외부 호출 추적, 추가 쿼리 쿼리 처리를 통해 데이터스토어에 대한 외부 호출 추적, 메시지 생산자와 소비자 간의 호출 추적과 같은 작업에 사용됩니다.

중요

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

분산 추적 API

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

헤더 래퍼

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

class HeadersWrapper implements Headers {
    private final HttpMessage delegate;

    public HeadersWrapper(HttpMessage request) {
        this.delegate = request;
    }

    @Override
    public void setHeader(String name, String value) {
        delegate.setHeader(name, value);
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    @Override
    public String getHeader(String name) {
        return delegate.getFirstHeader(name).getValue();
    }

    @Override
    public Collection<String> getHeaders(String name) {
        return Arrays.stream(delegate.getHeaders(name))
                .map(NameValuePair::getValue)
                .collect(Collectors.toList());
    }

    @Override
    public void addHeader(String name, String value) {
        delegate.addHeader(name, value);
    }

    @Override
    public Collection<String> getHeaderNames() {
        return Arrays.stream(delegate.getAllHeaders())
                .map(NameValuePair::getName)
                .collect(Collectors.toSet());
    }

    @Override
    public boolean containsHeader(String name) {
        return Arrays.stream(delegate.getAllHeaders())
                .map(NameValuePair::getName)
                .anyMatch(headerName -> headerName.equals(name));
    }
}

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

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

@Trace
public int makeExternalCall(URI uri) throws IOException {
    HttpUriRequest request = RequestBuilder.get().setUri(uri).build();

    // Wrap the outbound Request object
    Headers outboundHeaders = new HeadersWrapper(request);

    // Obtain a reference to the current transaction
    Transaction transaction = NewRelic.getAgent().getTransaction();
    // Add headers for outbound external request
    transaction.insertDistributedTraceHeaders(outboundHeaders);

    CloseableHttpClient connection = HttpClientBuilder.create().build();
    CloseableHttpResponse response = connection.execute(request);

    return response.getStatusLine().getStatusCode();
}

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

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

@Trace(dispatcher = true)
@Override
public Response serve(IHTTPSession request) {
    // Obtain a reference to the current Transaction
    Transaction tx = NewRelic.getAgent().getTransaction();

    // Set the name of the current transaction
    NewRelic.setTransactionName("Custom", "ExternalHTTPServer");

    // Wrap the Request object
    Headers req = new HeadersWrapper(request);

    // Set the request for the current transaction and convert it into a web transaction
    tx.acceptDistributedTraceHeaders(TransportType.HTTP, req);

    queryDB();

    return newFixedLengthResponse("<html><body><h1>SuccessfulResponse</h1>\n</body></html>\n");
}

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

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

교차 애플리케이션 추적 API

중요

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

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

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

클라이언트 래퍼

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

class OutboundWrapper implements OutboundHeaders {
    private final HttpUriRequest delegate;

    // OutboundHeaders is implemented by delegating to the library's request object
    public OutboundWrapper(HttpUriRequest request) {
        this.delegate = request;
    }

    // This allows the agent to add the correct headers to the HTTP request
    @Override
    public void setHeader(String name, String value) {
        delegate.addHeader(name, value);
    }

    // New Relic CAT specifies different header names for HTTP and MESSAGE
    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }
}

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

class InboundWrapper implements InboundHeaders {
    private final CloseableHttpResponse responseHeaders;

    // OutboundHeaders is implemented by delegating to the library's response object
    public InboundWrapper(CloseableHttpResponse responseHeaders) {
        this.responseHeaders = responseHeaders;
    }

    // New Relic CAT specifies different header names for HTTP and MESSAGE
    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    // this allows the agent to read the correct headers from the HTTP response
   @Override
   public String getHeader(String name) {
       return responseHeaders.getFirstHeader(name).getValue();
   }
}

서버 래퍼

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

// Extend ExtendedRequest class to create a wrapper for the Request object
class RequestWrapper extends ExtendedRequest {
    private IHTTPSession session;

    public RequestWrapper(IHTTPSession session) {
        super();
        this.session = session;
    }

    @Override
    public String getRequestURI() {
        return session.getUri();
    }

    @Override
    public String getHeader(String name) {
        return session.getHeaders().get(name);
    }

    @Override
    public String getRemoteUser() {
        return null;
    }

    @SuppressWarnings("rawtypes")
    @Override
    public Enumeration getParameterNames() {
        return Collections.enumeration(session.getParms().keySet());
    }

    @Override
    public String[] getParameterValues(String name) {
        return new String[] { session.getParms().get(name) };
    }

    @Override
    public Object getAttribute(String name) {
        return null;
    }

    @Override
    public String getCookieValue(String name) {
        return null;
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }

    @Override
    public String getMethod() {
        return session.getMethod().toString();
    }
}

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

// Implement Response interface to create a wrapper for the outgoing Response object
public class ResponseWrapper implements com.newrelic.api.agent.Response {

    private final Response httpResponse;

    public ResponseWrapper(Response httpResponse) {
        this.httpResponse = httpResponse;
    }

    @Override
    public int getStatus() throws Exception {
        return 200;
    }

    @Override
    public String getStatusMessage() throws Exception {
        return null;
    }

    @Override
    public void setHeader(String name, String value) {
        httpResponse.addHeader(name, value);
    }

    @Override
    public String getContentType() {
        return "";
    }

    @Override
    public HeaderType getHeaderType() {
        return HeaderType.HTTP;
    }
}

래퍼를 사용한 CAT 구현

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

@Trace
public int makeExternalCall(URI uri) throws IOException {
    String library = "HTTPClient";
    String procedure = "Execute";
    HttpUriRequest request = RequestBuilder.get().setUri(uri).build();

    // Wrap the outbound Request object
    OutboundWrapper outboundHeaders = new OutboundWrapper(request);
    // Obtain a reference to the method currently being traced
    TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
    // Add headers for outbound external request
    tracedMethod.addOutboundRequestHeaders(outboundHeaders);

    CloseableHttpClient connection = HttpClientBuilder.create().build();
    CloseableHttpResponse response = connection.execute(request);

    // Wrap the incoming Response object
    InboundWrapper inboundHeaders = new InboundWrapper(response);
    // Create an input parameter object for a call to an external HTTP service
    ExternalParameters params = HttpParameters
            .library(library)
            .uri(uri)
            .procedure(procedure)
            .inboundHeaders(inboundHeaders)
            .build();

    // Report a call to an external HTTP service
    tracedMethod.reportAsExternal(params);

    return response.getStatusLine().getStatusCode();
}

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

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

@Trace(dispatcher = true)
@Override
public Response serve(IHTTPSession session) {
    // Obtain a reference to the current Transaction
    Transaction tx = NewRelic.getAgent().getTransaction();

    // Set the name of the current transaction
    NewRelic.setTransactionName("Custom", "ExternalHTTPServer");

    // Wrap the Request object
    ExtendedRequest req = new RequestWrapper(session);

    // Set the request for the current transaction and convert it into a web transaction
    tx.setWebRequest(req);

    queryDB();
    Response res = newFixedLengthResponse("<html><body><h1>SuccessfulResponse</h1>\n</body></html>\n");

    // Set the response for the current transaction and convert it into a web transaction
    tx.setWebResponse(new ResponseWrapper(res));

    // Instruct the transaction to write the outbound response headers
    tx.addOutboundResponseHeaders();

    // Mark the time when the response left the server
    tx.markResponseSent();

    return res;
}

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

서버에서 프레임워크 클래스를 사용하여 Response 을 구현하고 ExtendedRequest 클래스를 확장합니다.
setWebRequest(ExtendedRequest request) 및 setWebResponse(Response response) 을 사용하여 트랜잭션을 웹 트랜잭션으로 변환하고 에이전트에 인바운드 요청 헤더와 아웃바운드 헤더를 기록할 장소를 함께 제공합니다.
트랜잭션 이름은 요청 객체에 의존하고 응답 코드는 응답 객체에 의존하기 때문에 setWebRequest(ExtendedRequest request) 과 setWebResponse(Response response) 을 함께 사용하는 것이 중요합니다.
에이전트가 아웃바운드 응답에 적절한 헤더를 추가하도록 하려면 addOutboundResponseHeaders() 을 사용합니다.
markResponseSent() 에 대한 호출로 응답의 끝을 표시합니다.

메시징 API

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

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

중요

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

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

public class MessageProducer {
    // instrument the method that puts messages on a queue
    @Trace
    public void sendMessageToQueue(Message message) {
        ExternalParameters messageProduceParameters = MessageProduceParameters.library("JMS")
                .destinationType(DestinationType.NAMED_QUEUE)
                .destinationName(message.getJMSDestination())
                .outboundHeaders(new OutboundWrapper(message))
                .build();

        NewRelic.getAgent().getTracedMethod().reportAsExternal(messageProduceParameters);
    }
}

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

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

public class MessageConsumer {
    @Trace
    public Message messageReceive() {
        ExternalParameters messageConsumeParameters = MessageConsumeParameters.library("JMS")
                .destinationType(DestinationType.NAMED_QUEUE)
                .destinationName(message.getJMSDestination())
                .inboundHeaders(new InboundWrapper(message))
                .build();

        NewRelic.getAgent().getTracedMethod().reportAsExternal(messageConsumeParameters);

        return message;
    }
}

데이터 저장소 API

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

TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
    tracedMethod.reportAsExternal(
        DatastoreParameters
        .product("sqlite") // the datastore vendor
        .collection("test.db") // the name of the collection (or table for SQL databases)
        .operation("select") // the operation being performed, for example "SELECT" or "UPDATE" for SQL databases
        .instance("localhost", 8080) // the datastore instance information - generally can be found as part of the connection
        .databaseName("test.db") // may be null, indicating no keyspace for the command
        .build());

Datastore API: 느린 쿼리

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

적절한 ExternalParameters 객체를 만드는 방법은 다음과 같습니다.

// Reporting a method as doing datastore activity
TracedMethod tracedMethod = NewRelic.getAgent().getTracedMethod();
tracedMethod.reportAsExternal(
    DatastoreParameters
        .product("sqlite")           // the datastore vendor
        .collection("test.db")       // the name of the collection (or table for SQL databases)
        .operation("select")         // the operation being performed, for example "SELECT" or "UPDATE" for SQL databases
        .instance("localhost", 8080) // the datastore instance information - generally can be found as part of the connection
        .databaseName("test.db")     // may be null, indicating no keyspace for the command
        .slowQuery(rawQuery, QUERY_CONVERTER)
        .build());

private static QueryConverter<String> QUERY_CONVERTER = new QueryConverter<String>() {

    @Override
    public String toRawQueryString(String statement) {
        // Do work to transform raw query object to string
        return statement;
    }

    @Override
    public String toObfuscatedQueryString(String statement) {
        // Do work to remove any sensitive information here
        return obfuscateQuery(statement);
    }
};

웹프레임웍스 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)

팁

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

public NewRelicApiClient() throws IOException, URISyntaxException {
    super(8080);

    // Set Dispatcher name and version.
    NewRelic.setServerInfo("NanoHttp", "2.3.1");

    // Set Appserver port for jvm identification
    NewRelic.setAppServerPort(8080);

    // Set JVM instance name
    NewRelic.setInstanceName("Client:8080");

    start(NanoHTTPD.SOCKET_READ_TIMEOUT, false);
    System.out.println("\nRunning on http://localhost:8080/ \n");
}

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

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

외부 API

외부 API

외부 매개변수 빌더

중요

분산 추적 API

헤더 래퍼

헤더 구현

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

분산 추적: 클라이언트 측

분산 추적: 서버 측

교차 애플리케이션 추적 API

중요

클라이언트 래퍼

OutbounderHeaders 구현

InboundHeaders 구현

서버 래퍼

ExtendedRequest 클래스 확장

응답 인터페이스 구현

래퍼를 사용한 CAT 구현

교차 애플리케이션 추적: 클라이언트 측

교차 애플리케이션 추적: 서버 측

메시징 API

중요

메시징 API 구현

CAT 헤더 구현이 있는 메시지

데이터 저장소 API

데이터 저장소 API 구현

Datastore API: 느린 쿼리

쿼리 구현이 느린 데이터 저장소

웹프레임웍스 API

팁

WebFrameworks API 구현

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

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

외부 API .css-21sua1{background:none;border:none;width:0;padding:0;}

외부 매개변수 빌더

중요

분산 추적 API

헤더 래퍼

헤더 구현

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

분산 추적: 클라이언트 측

분산 추적: 서버 측

교차 애플리케이션 추적 API

중요

클라이언트 래퍼

OutbounderHeaders 구현

InboundHeaders 구현

서버 래퍼

ExtendedRequest 클래스 확장

응답 인터페이스 구현

래퍼를 사용한 CAT 구현

교차 애플리케이션 추적: 클라이언트 측

교차 애플리케이션 추적: 서버 측

메시징 API

중요

메시징 API 구현

CAT 헤더 구현이 있는 메시지

데이터 저장소 API

데이터 저장소 API 구현

Datastore API: 느린 쿼리

쿼리 구현이 느린 데이터 저장소

웹프레임웍스 API

팁

WebFrameworks API 구현

외부 API