Configurazione file DirectivesConfig.acml

Per configurare il file DirectivesConfig.acml, vedere:

• Parametri DirectivesConfig.acml
• DirectivesConfig.acml Esempio
• Facoltativo: Variabili avanzate per il test personalizzato

Parametri DirectivesConfig.acml

Di seguito sono riportate informazioni sui parametri che è possibile specificare nel file DirectivesConfig.acml.

Nel file DirectivesConfig.acml è necessario specificare almeno uno dei seguenti parametri:

• 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, tag e log Variabili

Quando si specificano i parametri span_name, tags e logs, è possibile utilizzare le seguenti variabili per acquisire ulteriori informazioni:

• class_name: nome della classe monitorata, incluso il pacchetto.
• short_class_name: nome della classe monitorata, escluso il pacchetto.
• method_name: nome del metodo monitorato.
• method_descriptor: formato descrittore della firma del metodo monitorata.
• param#: parametri del metodo monitorato, in cui param1 indica il primo parametro, param2 il secondo parametro e così via.
• this: oggetto monitorato. Tenere presente che se la variabile method monitorata è static, la variabile this non sarà disponibile.
• return: restituisce il valore del metodo monitorato.
  Nota
  
  La variabile return può essere utilizzata solo per il parametro tags e non per span_name.

DirectivesConfig.acml Esempio

Di seguito è riportato un esempio del file 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}"

In base all'esempio precedente:

• Verrà monitorato com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall insieme alle relative sottoclassi.
• Il nome dell'intervallo visualizzato in Trace Explorer sarà OutboundTestServlet.performHttpURLConnectionCall.
• Le tag targetURL e port verranno aggiunte all'intervallo e utilizzeranno i valori del primo e del secondo parametro del metodo performHttpURLConnectionCall.

Di seguito sono riportati un esempio di pagina non operativa personalizzata.

Sintassi della catena di comandi

Il simbolo di pipe "|" viene utilizzato per indicare la tubazione dell'oggetto iniziale al primo comando di catena e l'oggetto di uscita di tubazione di un comando di catena al successivo.

Tempo di esecuzione

Le catene di comandi vengono eseguite prima o dopo che viene richiamato il metodo monitorato della sonda personalizzata. Ciò è specificato dal tempo di esecuzione, che viene visualizzato prima dell'indice di disponibilità.

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

Non tutte le catene di comandi sono compatibili con entrambi i tempi di esecuzione: quando return viene utilizzato come SOI o come parametro in un comando di metodo, è necessario utilizzare il tempo di esecuzione successivo. Questo perché l'oggetto restituito è disponibile solo dopo il richiamo del metodo monitorato. Quando altre variabili vengono utilizzate come SOI o parametri nei comandi del metodo, i tempi di esecuzione dipendono dalle catene di riferimento.

Ad esempio, definire chain1 e chain2, dove chain2 utilizza chain1 come SOI o parametro per un comando di metodo. Si noti che chain1 deve essere definito prima di chain2 se entrambe le catene utilizzano lo stesso tempo di esecuzione. In caso contrario, chain1 deve avere un tempo di esecuzione precedente e chain2 deve avere un tempo di esecuzione successivo.

Per ulteriori informazioni sull'uso delle interfacce SOI e dei comandi del metodo, vedere la sezione Identificativo oggetto iniziale riportata di seguito.

Identificativo oggetto iniziale

Un SOA (Start Object Identifier) può essere un oggetto associato a:

I tempi di esecuzione possono essere associati alla sintassi SOI.

Sequenza di comandi catena

Una sequenza di comandi catena è costituita da uno o più comandi catena.

Sintassi: <chain_command_sequence> ::= <chain_command> || <chain_command> | <chain_command_sequence>

Tipi di comando catena

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

Comando metodo

Un comando di metodo viene utilizzato per richiamare un metodo. L'output di un comando di metodo è l'oggetto restituito di quel metodo specifico.

Un comando metodo è costituito da visibilità del metodo, nome del metodo e sequenza dei parametri. Questo imita la firma del metodo.

La sintassi dovrebbe essere la seguente:

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

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

Il valore package viene utilizzato per specificare un metodo o un campo di visibilità pacchetto-privato (senza modificatore).

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

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

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

Esempi di comandi del metodo

Comando campo

Un comando di campo viene utilizzato per ispezionare i valori dei campi. L'output di un comando di campo è l'oggetto in quel campo specifico.

Un comando metodo è costituito da visibilità campo e nome campo.

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

Esempi di comandi di campo

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

Comando del metodo statico

Un comando di metodo statico viene utilizzato per richiamare un metodo statico. L'output di un comando di metodo statico è l'oggetto restituito di quel metodo specifico.

Un comando metodo è costituito da una classe iniziale, visibilità del metodo, nome del metodo e sequenza dei parametri. Questo imita la firma del metodo.

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

La classe iniziale è la classe in cui viene trovato il metodo statico.

Comando campo statico

Un comando di campo statico viene utilizzato per ispezionare i valori dei campi statici. L'output di un comando di campo statico è l'oggetto in quel campo specifico.

Un comando metodo è costituito da una classe iniziale, una visibilità campo e un nome campo.

Sintassi:

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

Esempi di comandi di campo statico:

Nell'esempio seguente si presume che this sia un oggetto utente. Qui stiamo accedendo a campi di varia visibilità nella classe Utente. L'output di ogni catena è il valore del rispettivo campo.

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

L'uso di altre visibilità è lo stesso degli esempi per Comando campo.

Comando Regex

Un comando regex viene utilizzato per trovare e/o sostituire le stringhe risultanti dal SOI, restituire i valori dei comandi del metodo o i valori dei campi. L'output di un comando regex è una stringa.

Un comando regex è costituito dalla stringa regex. Facoltativamente può anche consistere in una stringa di sostituzione, insieme all'eventuale sostituzione della prima o di tutte le occorrenze.

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

Esempi di comandi Regex

Esempi di variabili avanzate

Di seguito è riportato un esempio di catena di comandi nel file 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) 

Revisione dell'esecuzione della catena di variabili exampleVar:

Risultato finale: quando si esaminano le dimensioni di questo intervallo, viene visualizzata una tag denominata exampleVarTag con il valore "OracleThatway". Per visualizzare questa dimensione di intervallo è necessario specificare exampleVarTag: "${exampleVar}" nella sezione Tag.

Requisito:

JDK disponibile nel file PATH o definire la variabile di ambiente JAVA_HOME.

Posizione:

La utility ACMLValidate si trova nella directory oracle-apm-agent/bin.

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