Configuración de archivos DirectivesConfig.acml

Para configurar el archivo DirectivesConfig.acml, revise lo siguiente:

• Parámetros DirectivesConfig.acml
• Ejemplo de DirectivesConfig.acml
• Opcional: Variables avanzadas para sondeo personalizado

Parámetros DirectivesConfig.acml

A continuación se incluye información sobre los parámetros que puede especificar en el archivo DirectivesConfig.acml.

Se debe especificar al menos uno de los siguientes parámetros MUST en el archivo DirectivesConfig.acml:

• class_name
• class_name_regex
• class_annotation
• method_annotation
• class_annotation_regex
• method_annotation_regex

Test:
  ...
Test2:
  ...
Test3:
  ...

Test:  
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"

Test:
  # Monitor all classes under the com.oracle.apm.test package
  class_name_regex: "com/oracle/apm/test/.*"

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  method_name "performHttpURLConnectionCall"

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  # Monitor all methods that start with "perform"
  method_name_regex: "perform.*"

Test:
  class_annotation: "javax.jws.WebService"

Test:
  method_annotation: "javax.jws.WebMethod"

Test:
  # Monitor all Path annotations in javax
  class_annotation_regex: "Ljavax/.*/Path;"
Test2:
  # Monitor all annotations that end with "Path"
  # The L in the beginning is not required since .* includes it
  class_annotation_regex: ".*/Path;"
Test3:
  # Monitor all annotations with the javax.jws package
  # The ; at the end is not required since .* includes it
  class_annotation_regex: "Ljavax/jws/.*"

Test:
  # Monitor all Path annotations in javax
  method_annotation_regex: "Ljavax/.*/Path;"
Test2:
  # Monitor all annotations that end with "Path"
  # The L in the beginning is not required since .* includes it
  method_annotation_regex: ".*/Path;"
Test3:
  # Monitor all annotations with the javax.jws package
  # The ; at the end is not required since .* includes it
  method_annotation_regex: "Ljavax/jws/.*"

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  method_name "performHttpURLConnectionCall"
  include_sub_classes: true

Test:
  ...
  # The same name will be used every time the target class/method is invoked
  span_name: "SpecialName"
Test2:
  ...
  # Use the toString result of the first parameter passed to the monitored method
  span_name: "${param1}"

Test:
  ...
  tags:
    importantInfo: "${param1}"
    consistentTag: "AlwaysTheSame"
    returnValue: "${return}"
    #The below tag will have value of default type String since no type was specified
    defaultTagType: "${param1}"
    #The below tag will have value of type Integer
    integerTag: "${param1} | integer"
    #The below tag will have value of type String, because the actual value type String, and the specified type Double are incompatible. Therefore it will default to String.
    booleanTag: "${param2} | double"

Test:
  ...
  logs:
    importantInfoLog: "${param1}"
    consistentLog: "AlwaysTheSame"
    returnValueLog: "${return}"
  ...

Variables de span_name, etiquetas y logs

Al especificar los parámetros span_name, tags y logs, se pueden utilizar las siguientes variables para obtener información adicional:

• class_name: nombre de la clase que se está supervisando, incluyendo el paquete.
• short_class_name: nombre de la clase que se está supervisando, excluyendo el paquete.
• method_name: nombre del método que se está supervisando.
• method_descriptor: formato de descriptor de la firma del método que se está supervisando.
• param#: parámetros del método que se está supervisando, en los que param1 indica el primer parámetro, param2 el segundo parámetro, etc.
• this: objeto que se está supervisando. Tenga en cuenta que si el method que se está supervisando es static, la variable this no estará disponible.
• return: valor de devolución del método que se está supervisando.
  Nota
  
  La variable return solo se puede utilizar para el parámetro tags y no para span_name.

Ejemplo de DirectivesConfig.acml

A continuación, se muestra un ejemplo del archivo DirectivesConfig.acml:

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  method_name: "performHttpURLConnectionCall"
  include_sub_classes: true
  span_name: "${short_class_name}.${method_name}"
  tags:
    targetURL: "${param2}"
    port: "${param1}"

Según el ejemplo anterior:

• Se supervisará com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall junto con sus subclases.
• El nombre del período que se muestra en el explorador de rastreo será OutboundTestServlet.performHttpURLConnectionCall.
• Las etiquetas targetURL y port se agregarán al período y utilizarán los valores de los parámetros primero y segundo del método performHttpURLConnectionCall.

Las siguientes capturas de pantalla son un ejemplo de la página de sondeo personalizada:

Sintaxis de la cadena de comandos

El símbolo de tubería "|" se utiliza para indicar la canalización del objeto de inicio al primer comando de cadena y el objeto de salida de canalización de un comando de cadena al siguiente.

Tiempo de Ejecución

Las cadenas de comandos se ejecutan antes o después de que se llame al método supervisado del sondeo personalizado. Esto se especifica mediante el tiempo de ejecución, que aparece antes de la SOI.

<execution time> ::= [before || after]

No todas las cadenas de comandos son compatibles con ambos tiempos de ejecución: cuando se utiliza return como SOI o como parámetro en un comando de método, se debe utilizar el tiempo posterior a la ejecución. Esto se debe a que el objeto de devolución solo está disponible después de que se llame al método supervisado. Cuando se utilizan otras variables como SOI o parámetros en comandos de método, los tiempos de ejecución dependen de las cadenas a las que se hace referencia.

Por ejemplo, definamos chain1 y chain2, donde chain2 utiliza chain1 como SOI o parámetro para un comando de método. Tenga en cuenta que chain1 se debe definir antes que chain2 si ambas cadenas utilizan el mismo tiempo de ejecución. De lo contrario, chain1 debe tener tiempo de ejecución antes y chain2 debe tener tiempo de ejecución después.

Puede encontrar más información sobre el uso de las SOI y los comandos del método en la sección siguiente Identificador de objeto de inicio.

Identificador de objeto inicial

Un identificador de objeto de inicio (SOI) puede ser objetos asociados con:

Los tiempos de ejecución se pueden emparejar con la sintaxis de SOI.

Secuencia de comandos de cadena

Una secuencia de comandos de cadena consta de uno o más comandos de cadena.

Sintaxis: <chain_command_sequence> ::= <chain_command> || <chain_command> | <chain_command_sequence>

Tipos de comandos de cadena

Sintaxis: <chain_command> ::= <method_command> || <field_command> || <regex_command>

Comando de método

Se utiliza un comando method para llamar a un método. La salida de un comando method es el objeto de retorno de ese método específico.

Un comando de método consta de visibilidad de método, nombre de método y secuencia de parámetros. Esto imita la firma del método.

La sintaxis debe ser similar a la siguiente:

<method_command> ::= method(<visibility> <java_identifier> (<parameter_sequence>))

<visibility> ::= private || public || protected || package

El valor package se utiliza para especificar un campo o método de visibilidad de paquete privado (sin modificador).

<scalar_parameter_type> ::= int || double || float || String

<parameter> ::=<scalar_parameter_type> value || this || return || param<index> || variable-key

<parameter_sequence> ::= <parameter> || <parameter> , <parameter_sequence>

Ejemplos de comandos de método

Comando de campo

Se utiliza un comando de campo para inspeccionar los valores de campo. La salida de un comando de campo es el objeto de ese campo específico.

Un comando de método consta de visibilidad de campo y nombre de campo.

Sintaxis: <field_command> ::= field (<visibility> <java_identifier>)

Ejemplos de comandos de campo

fieldPublic: this | field(public firstName)
fieldProtected: this | field (protected lastName) 
fieldPackagePrivate: this | field (package middleName)
fieldPrivate: this | field (private maidenName)

Comando de Método Estático

Se utiliza un comando de método estático para llamar a un método estático. La salida de un comando de método estático es el objeto de retorno de ese método específico.

Un comando de método consta de una clase inicial, visibilidad de método, nombre de método y secuencia de parámetros. Esto imita la firma del método.

<static_method_command> ::= static method((<starting_class>)(<visibility> <java_identifier> (<parameter_sequence>)))

La clase inicial es la clase en la que se encuentra el método estático.

Comando de campo estático

Se utiliza un comando de campo estático para inspeccionar los valores de campo estático. La salida de un comando de campo estático es el objeto de ese campo específico.

Un comando de método consta de una clase inicial, visibilidad de campo y nombre de campo.

Sintaxis:

<static_field_command> ::= static field ((<starting_class>)(<visibility> <java_identifier>))

Ejemplos de comandos de campo estático:

En el ejemplo siguiente se asume que this es un objeto de usuario. Aquí estamos accediendo a campos de diversa visibilidad en la clase User. La salida de cada cadena es el valor del campo correspondiente.

staticFieldPublic: static field((com.test.beans.Employee)(public role))

El uso de otras visibilidades es el mismo que en los ejemplos de comando de campo.

Comando Regex

Se utiliza un comando regex para buscar y/o sustituir cadenas resultantes de la SOI, los valores de retorno de los comandos de método o los valores de campo. La salida de un comando regex es una cadena.

Un comando regex consta de la cadena regex. Opcionalmente, también puede consistir en una cadena de sustitución, junto con si se deben sustituir la primera o todas las incidencias.

Sintaxis: <regex_command> ::=regex (string [,<replace-string> [, first || all]])

Ejemplos de comandos Regex

Ejemplos de variables avanzadas

A continuación, se muestra un ejemplo de una cadena de comandos en el archivo DirectivesConfig.acml.

test:  class_name: "com.test.beans.User"
  method_name: "incAge"
  span_name: "${short_class_name}.${method_name}"
  tags:
    t: "${this}"
    params: "${param1}"
    r: "${return}"
    exampleVarTag: "${exampleVar}"
  variables:
    exampleVar:  before this | method (public getAddress ()) | field(private street) |  regex(Pk,This, all) | regex(This, That, first) 

Revisión de la ejecución de la cadena de variables exampleVar:

Resultado final: al consultar las dimensiones de este período, verá una etiqueta denominada exampleVarTag con el valor "OracleThatway". Tenga en cuenta que la especificación de exampleVarTag: "${exampleVar}" en la sección de etiquetas era necesaria para ver esta dimensión de período.

Requisito:

JDK disponible en PATH o defina la variable de entorno JAVA_HOME.

Ubicación:

La utilidad ACMLValidate se encuentra en el directorio oracle-apm-agent/bin.

Ejecute ACMLValidate:

ACMLValidate.[bat|sh] <path to the acml file>

oracle-apm-agent/bin % sh ACMLvalidate.sh  ../config/1.16.0.560/ProbeConfig.acml

===============================================================================
Testing file: ../config/1.16.0.560/ProbeConfig.acml
ACML Validation Result: PASSED
===============================================================================

oracle-apm-agent/bin % sh ACMLvalidate.sh ../config/1.16.0.560/ProbeConfig.acml  

===========================================================================
Testing file: ../config/1.16.0.560/ProbeConfig.acml
ACML Validation Result: FAILED
Exception: Failed to parse line [5][  SERVLET: true]
Caused by: Tab detected in the following line.  Please replace '\t' with spaces: [  \tSERVLET: true]
===========================================================================