Configuration des fichiers DirectivesConfig.acml

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

• Paramètres DirectivesConfig.acml
• Exemple de fichier DirectivesConfig.acml
• Facultatif : Variables avancées pour les sondages personnalisés

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 DOIT suivants est 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, marqueurs et variables de journaux

Lors de la spécification des paramètres span_name, tags et logs, les variables suivantes permettent d'obtenir des informations supplémentaires :

• class_name : Nom de la classe surveillée, y compris le paquetage.
• short_class_name : Nom de la classe surveillée, à l'exclusion du paquetage.
• method_name : Nom de la méthode surveillée.
• method_descriptor : Format de descripteur de la signature de la méthode surveillée.
• param# : Paramètres de la méthode surveillée, où param1 indique le premier paramètre, param2 le deuxième paramètre, etc.
• this : Objet surveillé. Notez que si la méthode (method) surveillée est static, la variable this ne sera pas disponible.
• return : Valeur retournée pour la méthode surveillée.
  Note
  
  La variable return ne peut être utilisée que pour le paramètre tags et non pour span_name.

Exemple de fichier DirectivesConfig.acml

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

Selon l'exemple ci-dessus :

• com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall sera surveillé, ainsi que ses sous-classes.
• Le nom de l'intervalle affiché dans l'explorateur de trace sera OutboundTestServlet.performHttpURLConnectionCall.
• Les marqueurs targetURL et port seront ajoutés à l'intervalle et utiliseront les valeurs des premier et deuxième paramètres de la méthode performHttpURLConnectionCall.

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

Syntaxe de la chaîne de commande

Le symbole de tuyau "|" est utilisé pour signifier la tuyauterie de l'objet de départ vers la première commande de chaîne et l'objet de sortie de tuyauterie d'une commande de chaîne à la suivante.

Durée 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 définie par la durée dexécution, qui apparaît avant larchitecture SOI.

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

Toutes les chaînes de commande ne sont pas compatibles avec les deux temps d'exécution : Lorsque return est utilisé en tant qu'interface de ligne de commande 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 de retour n'est disponible qu'après l'appel de la méthode surveillée. Lorsque d'autres variables sont utilisées comme SOI ou paramètres dans des 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. Notez que 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 un temps d'exécution avant et chain2 doit avoir un temps d'exécution après.

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

Identificateur de l'objet de départ

Un identificateur d'objet de départ (SOI) peut être un objet associé à :

Les temps d'exécution peuvent être associés à la syntaxe SOI.

Séquence de commande de chaîne

Une séquence de commandes de chaîne consiste en une ou 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 se compose de la visibilité de la méthode, du nom de la méthode et de la séquence de paramètres. Ceci imite la signature de la méthode.

La syntaxe doit se présenter comme suit :

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

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

La valeur package est utilisée pour spécifier une méthode de visibilité ou un champ privé (sans modificateur).

<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 de 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 de champ

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. La sortie d'une commande de méthode statique est l'objet de retour de cette méthode spécifique.

Une commande de méthode consiste en une classe de début, une visibilité de méthode, un nom de méthode et 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 la méthode statique est trouvée.

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 dans ce champ spécifique.

Une commande de méthode consiste en une classe de début, une visibilité de champ et 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. Ici, nous accédons à des champs de visibilité différente dans la classe Utilisateur. 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 pour Field Command.

Commande Regex

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

Une commande regex est constituée de la chaîne regex. Facultativement, il peut également s'agir d'une chaîne de remplacement, ainsi que d'une première ou de toutes les occurrences à remplacer.

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 cet intervalle, vous voyez une balise nommée exampleVarTag avec la valeur "OracleThatway". Notez que la spécification de exampleVarTag: "${exampleVar}" dans la section Marqueurs était nécessaire pour voir cette dimension d'intervalle.

Conditions requises :

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