Instrumentación Java por XML

Para su aplicación Java New Relic-monitor, un método de instrumentación personalizada es utilizar un archivo XML para especificar los métodos de su aplicación que deben instrumentarse. El agente de Java leerá el archivo XML e interpretará las clases relevantes al inicio; Los archivos XML agregados al directorioextensions después del inicio no requieren un reinicio de JVM para ser detectados.

Consulte agente de Java instrumentación personalizada para obtener una descripción de las opciones de instrumentación personalizada y los motivos para utilizarlas.

Accediendo a su archivo XML

Vaya a one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentation. Desde aquí puedes:

• Descargue un archivo XML de muestra. (Puede hacerlo desde la ventana emergente que aparece al hacer clic en Import an XML file.)
• Seleccione un archivo XML existente para editar.
• Busque en el historial de instrumentación.

Estructura de archivos XML

Su paquete de descarga del agente New Relic (newrelic_agent.zip) contiene dos plantillas para usar instrumentación XML:

• La plantilla extension.xsd es la definición del esquema XML que deben seguir todas las extensiones personalizadas.
• La plantilla extension-example.xml es un ejemplo. Este archivo instrumentó algunos de los métodos básicos de JDK. Si edita y cambia el nombre de este archivo, asegúrese de modificar el atributo name="extension-example" para que coincida con el nuevo nombre de archivo.

Para obtener más información sobre las propiedades de la plantilla extension.xsd , consulte la descripción general del formato de archivo XML.

Validación de archivos XML

Antes de iniciar su aplicación, valide su archivo XML usando la herramienta de línea de comando de New Relic. La herramienta de línea de comando solo se puede usar cuando tus clases están en un jar. Hay dos formas de validar su instrumentación XML:

$
java -Djava.ext.dirs=/path/to/jarred/classes -jar newrelic.jar instrument -file /path/to/file.xml -debug true

$
java -cp /path/to/your-app.jar:/path/to/newrelic.jar com.newrelic.bootstrap.BootstrapAgent instrument -file /path/to/file.xml -debug true

La aplicación se ejecuta con el newrelic.jar. La llamada debe contener la palabra clave instrument seguida de la marca -file con la ruta a su archivo XML. La propiedad -debug es opcional y se puede establecer en true para proporcionar más información durante la validación.

La herramienta:

• Valide la sintaxis XML.
• Compruebe que cada clase a instrumentar esté presente en la ruta de clases.
• Compruebe que cada método esté contenido en la clase adecuada.

Si el archivo XML es válido, verá una declaración de aprobación impresa en la terminal:

PASS: The extension at file.txt was successfully validated.

Si el XML no supera la validación, verá un mensaje de error impreso en el terminal:

FAIL: reason

Ubicación del archivo XML

El agente de Java lee los archivos XML en el directorio extensions al iniciar el proceso. El directorio extensions también se lee en cada ciclo de recolección. Los archivos XML agregados a este directorio durante el tiempo de ejecución se leerán en unos minutos, por lo que no requieren reiniciar la JVM.

Hay dos formas de especificar la ubicación del archivo XML:

Verificar que el archivo fue leído

Para verificar que el agente lea el archivo XML, primero configure la administración de registros en finer:

1. Edite el archivo de configuración newrelic.yml y cambie la propiedad log_level :

   log_level: finer

   Copia

2. Inicie o reinicie la aplicación.

Si la lectura fue exitosa, logs/newrelic_agent.log lo indicará en una declaración similar a:

Reading custom extension file /path/to/file.xml

Si no aparece ninguna declaración en logs/newrelic_agent.log, entonces no se encontró el archivo XML. Verifique la ubicación del archivo XML y asegúrese de que el proceso New Relic tenga acceso de lectura al archivo.

Múltiples archivos XML

Si bien se prefiere utilizar un único archivo XML, puede utilizar varios archivos XML personalizados. Todos estos archivos estarán instrumentados siempre que el nombre de la extensión en los archivos sea único.

• Si dos archivos XML personalizados contienen el mismo nombre de extensión, se implementará el que tenga la versión más alta y el otro se ignorará.
• Si los dos archivos tienen el mismo nombre y versión, se implementará el primer archivo leído por el agente y el otro se ignorará.

XML y YAML

Antes de 2.10.0, Los archivos YAML se pueden utilizar para instrumentación personalizada. Estos archivos YAML legacy todavía son compatibles. Sin embargo, el nuevo usuario debe utilizar archivos XML para instrumentación personalizada.

Legacy users: Si existen archivos YAML y XML con el mismo nombre de extensión, solo se instrumentará el archivo XML. El archivo YAML será ignorado. Si desea instrumentar los archivos YAML y XML, asigne a cada archivo un nombre de extensión diferente.

Archivo XML de ejemplo

Para ver un ejemplo de un archivo XML de instrumentación personalizada, consulte Ejemplos de Java XML.