Agente de Java API: Instrumento que utiliza anotación

El agente de Java de New Relic proporciona varias opciones para instrumentación personalizada. Una de esas opciones es agregar las anotaciones @Trace, @TraceLambda o @TraceByReturnType del agente de Java API al código de su aplicación. Este documento describe cómo utilizar las anotaciones.

Las anotaciones están habilitadas de forma predeterminada.

De forma predeterminada, la configuración enable_custom_tracing está establecida en true en el agente de Java, que es la configuración necesaria para que funcionen las anotaciones @Trace.

Esta configuración no está incluida en newrelic.yml de forma predeterminada. Si desea desactivar las anotaciones, establezca enable_custom_tracing: false (precedido por dos espacios) en la sección common de su newrelic.yml.

@Rastro

Anotar un método con @Trace le dice al agente de Java que se deben tomar medidas para ese método.

Para agregar una llamada a un método como una traza personalizada, agregue @Trace anotaciones a su método. Asegúrese de que newrelic-api.jar aparezca en su classpath ya que contiene todas estas anotaciones.

import com.newrelic.api.agent.Trace;

...

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

Crear una nueva transacción

Si las transacciones no aparecen y desea iniciar una nueva transacción, incluya dispatcher=true con la anotación @Trace :

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

Añade detalles a tu transacción

Si su traza de la transacción muestra grandes bloques de tiempo no instrumentados y desea incluir algunos métodos más dentro de la traza, puede usar la anotación @Trace sin parámetro:

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

Convertir una transacción en una solicitud web

Para generar un informe de tarea en segundo plano como una transacción browser web con una llamada API de agente de Java : En el método anotado con @Trace(dispatcher=true), llame a:

NewRelic.setRequestAndResponse(Request request, Response response)

Los argumentos son implementaciones de las interfaces Request y Response en newrelic-api.jar.

Defina su propia clase de anotación @Trace

Si define su propia clase de anotación @Trace , no hay dependencia de newrelic-api.jar. Para definir la clase:

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

Luego, configure el agente para usar esta anotación en la sección common de newrelic.yml:

class_transformer:
  trace_annotation_class_name: com.test.Trace

Propiedades para @Trace

La anotación @Trace admite las siguientes propiedades.

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

Esta característica está deshabilitada de forma predeterminada y debe habilitarse explícitamente (p. ej. -Dnewrelic.config.instrumentation.trace_lambda.enabled=true) para que las anotaciones surtan efecto. La variable de entorno equivalente es NEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLED.

Si su traza de la transacción muestra grandes bloques de tiempo no instrumentados y desea incluir expresiones lambda dentro de la traza, puede usar la anotación @TraceLambda sin parámetro:

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

Las expresiones lambda se convierten en métodos estáticos de la clase que las contiene después de la compilación. De forma predeterminada, los métodos estáticos dentro de las clases marcadas con la anotación @TraceLambda que coincidan con el patrón de anotaciones se marcarán con la anotación @Trace .

Propiedades para @TraceLambda

La anotación @TraceLambda admite las siguientes propiedades.

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

Para incluir métodos con un tipo de retorno particular dentro de la traza, puede usar la anotación @TraceByReturnType para marcar una clase que pasa los tipos de retorno como una propiedad. Los métodos de las clases anotadas que coincidan con uno de los tipos de devolución especificados se marcarán con la anotación @Trace .

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

Propiedades de @TraceByReturnType

La anotación @TraceByReturnType admite las siguientes propiedades.

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

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

Consideraciones de rendimiento

Cuando el agente de Java está presente en la JVM, inyectará código en los métodos anotados. El impacto en el rendimiento es insignificante en operaciones pesadas, como base de datos o llamadas a servicios web, pero es notable en métodos que se llaman con frecuencia, como un descriptor de acceso llamado miles de veces por segundo.

Más funciones API

Para obtener más información sobre la API del agente de Java y su funcionalidad, consulte la introducción a la API del agente de Java.