Configuração do Arquivo DirectivasConfig.acml

Para configurar o arquivo DirectivesConfig.acml, analise o seguinte:

• Parâmetros DirectorConfig.acml
• Exemplo de DirecctionConfig.acml
• Opcional: Variáveis Avançadas para Sondagem Personalizada

Parâmetros DirectorConfig.acml

Veja aqui as informações sobre os parâmetros que você pode especificar no arquivo DirectivesConfig.acml.

Pelo menos um dos parâmetros a seguir DEVE ser especificado no arquivo 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}"
  ...

span_name, tags e logs de Variáveis

Ao especificar os parâmetros span_name, tags e logs, as seguintes variáveis podem ser usadas para obter informações adicionais:

• class_name: Nome da classe que está sendo monitorada, incluindo o pacote.
• short_class_name: Nome da classe que está sendo monitorada, excluindo o pacote.
• method_name: Nome do método que está sendo monitorado.
• method_descriptor: Formato do descritor da assinatura do método que está sendo monitorado.
• param#: Parâmetros do método que está sendo monitorado, em que param1 denota o primeiro parâmetro, param2 o segundo parâmetro, e assim por diante.
• this: Objeto que está sendo monitorado. Observe que se o method que está sendo monitorado for static, a variável this não estará disponível.
• return: Valor de retorno do método que está sendo monitorado.
  Observação
  
  A variável return só pode ser usada para o parâmetro tags e não para span_name.

DirectorConfig.acml - Exemplo

Veja um exemplo do arquivo 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}"

Com base no exemplo acima:

• com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall será monitorado, junto com suas subclasses.
• O nome do intervalo exibido no Trace Explorer será OutboundTestServlet.performHttpURLConnectionCall.
• As tags targetURL e port serão adicionadas ao intervalo e usarão os valores do primeiro e segundo parâmetros do método performHttpURLConnectionCall.

As capturas de tela a seguir são um exemplo da página de sondagem personalizada:

Sintaxe da Cadeia de Comandos

O símbolo de pipe "|" é usado para significar o encanamento do objeto inicial para o primeiro comando de cadeia e o objeto de saída de encanamento de um comando de cadeia para o próximo.

Tempo de Execução

As cadeias de comandos são executadas antes ou depois que o método monitorado da Sondagem Personalizada é chamado. Isso é especificado pelo tempo de execução, que aparece antes do SOI.

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

Nem todas as Cadeias de Comandos são compatíveis com os dois tempos de execução: quando return é usado como SOI ou como um parâmetro em um comando de método, o tempo após a execução deve ser usado. Isso ocorre porque o objeto de retorno só está disponível depois que o método monitorado é chamado. Quando outras variáveis são usadas como SOIs ou parâmetros nos comandos de método, os tempos de execução são dependentes das cadeias referenciadas.

Por exemplo, vamos definir chain1 e chain2, em que chain2 usa chain1 como SOI ou parâmetro para um comando de método. Observe que chain1 deve ser definido antes de chain2 se ambas as cadeias usarem o mesmo tempo de execução. Caso contrário, chain1 deverá ter um tempo de execução antes e chain2 deverá ter um tempo de execução depois.

Mais informações sobre o uso de SOIs e os comandos de método podem ser encontradas na seção abaixo Iniciando o Identificador de Objeto.

Identificador do Objeto Inicial

Um Identificador de Objeto Inicial (SOI) pode ser objeto associado a:

Os tempos de execução podem ser pareados com a sintaxe SOI.

Sequência do Comando de Cadeia

Uma sequência de comandos de cadeia consiste em um ou mais comandos de cadeia.

Sintaxe: <chain_command_sequence> ::= <chain_command> || <chain_command> | <chain_command_sequence>

Tipos de Comando de Cadeia

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

Comando de Método

Um comando de método é usado para chamar um método. A saída de um comando de método é o objeto de retorno desse método específico.

Um comando de método consiste na visibilidade do método, no nome do método e na sequência do parâmetro. Isso imita a assinatura do método.

A sintaxe deve se parecer com:

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

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

O valor package é usado para especificar um método ou campo de visibilidade (sem modificador) privado do pacote.

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

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

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

Exemplos de Comando de Método

Comando de Campo

Um comando de campo é usado para inspecionar valores de campo. A saída de um comando de campo é o objeto nesse campo específico.

Um comando de método consiste na visibilidade do campo e no nome do campo.

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

Exemplos de comando de campo

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

Comando do Método Estático

Um comando de método estático é usado para chamar um método estático. A saída de um comando de método estático é o objeto de retorno desse método específico.

Um comando de método consiste em uma classe inicial, visibilidade do método, nome do método e sequência de parâmetros. Isso imita a assinatura do método.

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

A classe inicial é a classe na qual o método estático é encontrado.

Comando de Campo Estático

Um comando de campo estático é usado para inspecionar valores de campo estáticos. A saída de um comando de campo estático é o objeto nesse campo específico.

Um comando de método consiste em uma classe inicial, visibilidade de campo e nome de campo.

Sintaxe:

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

Exemplos de comando de campo estático:

O exemplo abaixo pressupõe que this seja um Objeto do usuário. Aqui estamos acessando campos de várias visibilidade na classe Usuário. A saída de cada cadeia é o valor do respectivo campo.

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

O uso de outras visibilidades é o mesmo que nos exemplos de Comando de Campo.

Comando Regex

Um comando regex é usado para localizar e/ou substituir strings resultantes do SOI, retornar valores dos comandos de método ou dos valores de campo. A saída de um comando regex é uma string.

Um comando regex consiste na string regex. Opcionalmente, ele também pode consistir em uma string substituta, além de se a primeira ou todas as ocorrências devem ser substituídas.

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

Exemplos de Comando Regex

Exemplos de Variáveis Avançadas

Este é um exemplo de uma cadeia de comandos no arquivo 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) 

Revisão da Execução da Cadeia Variável exampleVar:

Resultado Final: Ao observar Dimensões desse intervalo, você vê uma tag chamada exampleVarTag com o valor "OracleThatway". Observe que a especificação de exampleVarTag: "${exampleVar}" na seção de tags foi necessária para ver essa dimensão de intervalo.

Pré-requisitos:

JDK disponível no PATH ou defina a variável de ambiente JAVA_HOME.

Localização:

O utilitário ACMLValidate está localizado no diretório oracle-apm-agent/bin.

Execute 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]
===========================================================================