Configuration du fichier DirectivesConfig.acml

Pour configurer le fichier DirectivesConfig.acml, vérifiez les éléments suivants :

• Paramètres DirectivesConfig.acml
• Exemple DirectivesConfig.acml
• Facultatif : Variables avancées pour le sondage personnalisé

Paramètres DirectivesConfig.acml

Voici des informations sur les paramètres que vous pouvez spécifier dans le fichier DirectivesConfig.acml.

Au moins un des paramètres suivants, MUST, doit être spécifié dans le fichier 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, variables de balises et de journaux

Lorsque vous spécifiez les paramètres span_name, tags et logs, vous pouvez utiliser les variables suivantes pour obtenir des informations supplémentaires :

• class_name : nom de la classe surveillée, en incluant le package.
• short_class_name : nom de la classe surveillée, en excluant le package.
• method_name : nom de la méthode surveillée.
• method_descriptor : format du descripteur de la signature de la méthode surveillée.
• param# : paramètres de la méthode surveillée, où param1 désigne le premier paramètre, param2 le deuxième paramètre, etc.
• this : objet surveillé. Si l'élément method surveillé est de type static, la variable this n'est pas disponible.
• return : valeur renvoyée de la méthode surveillée.
  Remarque
  
  La variable return peut uniquement être utilisée pour le paramètre tags et non pour le paramètre span_name.

Exemple DirectivesConfig.acml

Voici un exemple de fichier 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}"

En fonction de l'exemple ci-dessus :

• La classe com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall et ses sous-classes sont surveillées.
• Le nom de l'étendue affiché dans l'explorateur de traces est OutboundTestServlet.performHttpURLConnectionCall.
• Les balises targetURL et port sont ajoutées à l'étendue et utilisent les valeurs des premier et second paramètres de la méthode performHttpURLConnectionCall.

Les captures d'écran suivantes donnent un exemple de page de sonde personnalisée :

Syntaxe de chaîne de commande

Le symbole de barre verticale "|" est utilisé pour indiquer la canalisation de l'objet de départ vers la première commande de chaîne et la canalisation de l'objet de sortie d'une commande de chaîne vers la suivante.

Heure d'exécution

Les chaînes de commandes sont exécutées avant ou après l'appel de la méthode surveillée de la sonde personnalisée. Cette valeur est spécifiée par l'heure d'exécution, qui apparaît avant le SOI.

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

Les chaînes de commande ne sont pas toutes compatibles avec les deux temps d'exécution : lorsque return est utilisé en tant que SOI ou en tant que paramètre dans une commande de méthode, le temps d'exécution suivant doit être utilisé. En effet, l'objet renvoyé n'est disponible qu'après l'appel de la méthode surveillée. Lorsque d'autres variables sont utilisées en tant que SOI ou paramètres dans les commandes de méthode, les temps d'exécution dépendent des chaînes référencées.

Par exemple, définissez chain1 et chain2, où chain2 utilise chain1 comme SOI ou paramètre pour une commande de méthode. chain1 doit être défini avant chain2 si les deux chaînes utilisent la même durée d'exécution. Sinon, chain1 doit avoir une durée d'exécution antérieure et chain2 doit avoir une durée d'exécution postérieure.

Pour plus d'informations sur l'utilisation des SOI et des commandes de méthode, reportez-vous à la section Identifiant de l'objet de début ci-dessous.

Identifiant de l'objet de début

Un identifiant d'objet de début (SOI) peut être des objets associés à :

Les durées d'exécution peuvent être associées à la syntaxe SOI.

Séquence de commande de chaîne

Une séquence de commandes de chaîne se compose d'une ou de plusieurs commandes de chaîne.

Syntaxe : <chain_command_sequence> ::= <chain_command> || <chain_command> | <chain_command_sequence>

Types de commande de chaîne

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

Commande de méthode

Une commande de méthode est utilisée pour appeler une méthode. La sortie d'une commande de méthode est l'objet de retour de cette méthode spécifique.

Une commande de méthode consiste en une visibilité de méthode, un nom de méthode et une séquence de paramètres. Cette opération imite la signature de méthode.

La syntaxe doit ressembler à ce qui suit :

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

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

La valeur package permet d'indiquer une méthode ou un champ de visibilité privé (sans modificateur) de package.

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

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

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

Exemples de commandes de méthode

Commande de champ

Une commande de champ est utilisée pour inspecter les valeurs de champ. La sortie d'une commande de champ est l'objet dans ce champ spécifique.

Une commande de méthode consiste en la visibilité des champs et le nom des champs.

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

Exemples de commandes sur site

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

Commande de méthode statique

Une commande de méthode statique est utilisée pour appeler une méthode statique. Le résultat d'une commande de méthode statique est l'objet de retour de cette méthode spécifique.

Une commande de méthode se compose d'une classe de début, d'une visibilité de méthode, d'un nom de méthode et d'une séquence de paramètres. Cela imite la signature de la méthode.

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

La classe de départ est la classe dans laquelle se trouve la méthode statique.

Commande de champ statique

Une commande de champ statique est utilisée pour inspecter les valeurs de champ statique. La sortie d'une commande de champ statique est l'objet de ce champ spécifique.

Une commande de méthode se compose d'une classe de début, d'une visibilité de champ et d'un nom de champ.

Syntaxe :

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

Exemples de commandes de champ statique :

L'exemple ci-dessous suppose que this est un objet utilisateur. Nous accédons ici aux champs de visibilité variée dans la classe User. La sortie de chaque chaîne est la valeur du champ respectif.

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

L'utilisation d'autres visibilités est la même que dans les exemples de commande sur le terrain.

Commande Regex

Une commande regex est utilisée pour rechercher et/ou remplacer les chaînes résultant du SOI, les valeurs renvoyées par les commandes de méthode ou les valeurs de champ. La sortie d'une commande regex est une chaîne.

Une commande regex se compose de la chaîne regex. Le cas échéant, il peut également s'agir d'une chaîne de remplacement et indiquer si toutes les occurrences doivent être remplacées.

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

Exemples de commandes Regex

Exemples de variables avancées

Voici un exemple de chaîne de commandes dans le fichier 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) 

Vérification de l'exécution de la chaîne de variables exampleVar :

Résultat final : lorsque vous examinez les dimensions de cette étendue, vous voyez une balise appelée exampleVarTag avec la valeur "OracleThatway". La spécification de exampleVarTag: "${exampleVar}" dans la section Balises était nécessaire pour visualiser cette dimension d'étendue.

Conditions préalables :

JDK disponible dans PATH ou définissez la variable d'environnement JAVA_HOME.

Emplacement:

L'utilitaire ACMLValidate se trouve sous le répertoire oracle-apm-agent/bin.

Exécutez 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]
===========================================================================