API do agente Java: instrumento usando anotação

O agente Java da New Relic oferece diversas opções para instrumentação personalizada. Uma dessas opções é adicionar as anotações @Trace, @TraceLambda ou @TraceByReturnType da API do agente Java ao código do seu aplicativo. Este documento descreve como usar anotações.

As anotações estão habilitadas por padrão

Por padrão, a definição de configuração enable_custom_tracing é definida como true no agente Java, que é a configuração necessária para que as anotações @Trace funcionem.

Essa configuração não está incluída em newrelic.yml por padrão. Se você deseja desativar as anotações, defina enable_custom_tracing: false (precedido por dois espaços) na seção common do seu newrelic.yml.

@Vestígio

A anotação de um método com @Trace informa ao agente Java que medições devem ser feitas para esse método.

Para adicionar uma chamada de método como um trace personalizado, adicione anotações @Trace ao seu método. Certifique-se de que newrelic-api.jar apareça no seu caminho de classe, pois contém todas essas anotações.

import com.newrelic.api.agent.Trace;

...

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

Crie uma nova transação

Caso as transações não apareçam e você queira iniciar uma nova transação, inclua dispatcher=true com a anotação @Trace :

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

Adicione detalhes à sua transação

Se o seu trace da transação mostra grandes blocos de tempo não instrumentado e você deseja incluir mais alguns métodos dentro do trace, você pode usar a anotação @Trace sem parâmetro:

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

Converter uma transação em uma solicitação da web

Para fazer um relatório de tarefa em segundo plano como uma transação do browser da web com uma chamada de API do agente Java : No método anotado com @Trace(dispatcher=true), chame:

NewRelic.setRequestAndResponse(Request request, Response response)

Os argumentos são implementações das interfaces Request e Response em newrelic-api.jar.

Defina sua própria classe de anotação @Trace

Se você definir sua própria classe de anotação @Trace , não haverá dependência do newrelic-api.jar. Para definir a classe:

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;
}

Em seguida, configure o agente para usar esta anotação na seção common do newrelic.yml:

class_transformer:
  trace_annotation_class_name: com.test.Trace

Propriedades para @Trace

A anotação @Trace oferece suporte às propriedades a seguir.

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

Este recurso está desabilitado por padrão e deve ser habilitado explicitamente (por exemplo -Dnewrelic.config.instrumentation.trace_lambda.enabled=true) para que as anotações tenham efeito. A variável de ambiente equivalente é NEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLED.

Se o seu trace da transação mostra grandes blocos de tempo não instrumentado e você deseja incluir expressões lambda dentro do trace, você pode usar a anotação @TraceLambda sem parâmetro:

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

As expressões lambda tornam-se métodos estáticos da classe que os contém após a compilação. Por padrão, os métodos estáticos nas classes marcadas com a anotação @TraceLambda que correspondem ao padrão de anotações serão marcados com a anotação @Trace .

Propriedades para @TraceLambda

A anotação @TraceLambda oferece suporte às propriedades a seguir.

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

Para incluir métodos com um tipo de retorno específico no trace, você pode usar a anotação @TraceByReturnType para marcar uma classe que transmite os tipos de retorno como uma propriedade. Os métodos em classes anotadas que correspondam a um dos tipos de retorno especificados serão marcados com a anotação @Trace .

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

Propriedades para @TraceByReturnType

A anotação @TraceByReturnType oferece suporte às propriedades a seguir.

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

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

Considerações de desempenho

Quando o agente Java estiver presente na JVM, ele injetará código nos métodos anotados. O impacto no desempenho é insignificante em operações pesadas, como chamadas de banco de dados ou de webservice, mas é perceptível em métodos chamados com frequência, como um acessador chamado milhares de vezes por segundo.

Mais funções de API

Para obter mais informações sobre a API do agente Java e sua funcionalidade, consulte Introdução à API do agente Java.