DirectivesConfig.acml-Dateikonfiguration

Um die Datei DirectivesConfig.acml zu konfigurieren, prüfen Sie Folgendes:

• DirectivesConfig.acml-Parameter
• DirectivesConfig.acml - Beispiel
• Optional: Erweiterte Variablen für benutzerdefiniertes Probing

DirectivesConfig.acml-Parameter

Nachfolgend finden Sie Informationen zu den Parametern, die Sie in der Datei DirectivesConfig.acml angeben können.

Mindestens einer der folgenden Parameter MUST wird in der Datei DirectivesConfig.acml angegeben:

• 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 und Logvariablen

Wenn Sie die Parameter span_name, tags und logs angeben, können Sie mit den folgenden Variablen zusätzliche Informationen abrufen:

• class_name: Name der überwachten Klasse, einschließlich Package.
• short_class_name: Name der überwachten Klasse ohne Package.
• method_name: Name der überwachten Methode.
• method_descriptor: Deskriptorformat der Signatur der überwachten Methode.
• param#: Parameter der überwachten Methode, wobei param1 den ersten Parameter, param2 den zweiten Parameter usw. angibt.
• this: Das überwachte Objekt. Wenn die überwachte method static ist, ist die Variable this nicht verfügbar.
• return: Rückgabewert der überwachten Methode.
  Hinweis
  
  Die Variable return kann nur für den Parameter tags und nicht für span_name verwendet werden.

DirectivesConfig.acml - Beispiel

Beispiel für die Datei 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}"

Basierend auf dem obigen Beispiel:

• com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall wird zusammen mit den Unterklassen überwacht.
• Der im Trace-Explorer angezeigte Name des Spans lautet OutboundTestServlet.performHttpURLConnectionCall.
• Die Tags targetURL und port werden dem Span hinzugefügt und verwenden die Werte des ersten und zweiten Parameters der Methode performHttpURLConnectionCall.

Die folgenden Screenshots zeigen ein Beispiel für die Seite der benutzerdefinierten Probe:

Befehlskettensyntax

Mit dem Pipe-Symbol "|" wird das Piping des Startobjekts an den ersten Kettenbefehl und das Piping-Ausgabeobjekt eines Kettenbefehls an den nächsten bezeichnet.

Ausführungszeit

Die Befehlsketten werden vor oder nach dem Aufrufen der überwachten Methode der benutzerdefinierten Probe ausgeführt. Dies wird durch die Ausführungszeit angegeben, die vor der SOI angezeigt wird.

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

Nicht alle Befehlsketten sind mit beiden Ausführungszeiten kompatibel: Wenn return als SOI oder als Parameter in einem Methodenbefehl verwendet wird, muss die Nachlaufzeit verwendet werden. Dies liegt daran, dass das Rückgabeobjekt erst nach dem Aufruf der überwachten Methode verfügbar ist. Wenn andere Variablen als SOIs oder Parameter in Methodenbefehlen verwendet werden, hängen Ausführungszeiten von den referenzierten Ketten ab.

Beispiel: Definieren Sie chain1 und chain2, wobei chain2 chain1 als SOI oder Parameter für einen Methodenbefehl verwendet. Beachten Sie, dass chain1 vor chain2 definiert werden muss, wenn beide Ketten dieselbe Ausführungszeit verwenden. Andernfalls muss chain1 vorher Ausführungszeit haben, und chain2 muss danach Ausführungszeit haben.

Weitere Informationen zur Verwendung von SOIs und den Methodenbefehlen finden Sie im folgenden Abschnitt Objekt-ID starten.

Startobjekt-ID

Eine Startobjekt-ID (SOI) kann Objekte sein, die folgenden Objekten zugeordnet sind:

Ausführungszeiten können mit SOI-Syntax gepaart werden.

Kettenbefehlsfolge

Eine Chain-Befehlsfolge besteht aus einem oder mehreren Chain-Befehlen.

Syntax: <chain_command_sequence> ::= <chain_command> || <chain_command> | <chain_command_sequence>

Kettenbefehlstypen

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

Methodenbefehl

Mit einem Methodenbefehl wird eine Methode aufgerufen. Die Ausgabe eines Methodenbefehls ist das Rückgabeobjekt dieser spezifischen Methode.

Ein Methodenbefehl besteht aus der Methodensichtbarkeit, dem Methodennamen und der Parameterfolge. Dies entspricht der Methodensignatur.

Die Syntax sollte wie folgt aussehen:

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

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

Mit dem Wert package wird eine Package-private (no-modifier)-Sichtbarkeitsmethode oder ein Feld angegeben.

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

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

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

Methodenbefehlsbeispiele

Feldbefehl

Mit einem Feldbefehl werden Feldwerte geprüft. Die Ausgabe eines Feldbefehls ist das Objekt in diesem spezifischen Feld.

Ein Methodenbefehl besteht aus Feldsichtbarkeit und Feldname.

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

Beispiele für Feldbefehle

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

Static-Methodenbefehl

Mit einem statischen Methodenbefehl wird eine statische Methode aufgerufen. Die Ausgabe eines statischen Methodenbefehls ist das Rückgabeobjekt dieser spezifischen Methode.

Ein Methodenbefehl besteht aus einer Startklasse, einer Methodensichtbarkeit, einem Methodennamen und einer Parameterfolge. Dies imitiert die Methodensignatur.

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

Die Startklasse ist die Klasse, in der die statische Methode gefunden wird.

Befehl für statisches Feld

Ein statischer Feldbefehl wird verwendet, um statische Feldwerte zu prüfen. Die Ausgabe eines statischen Feldbefehls ist das Objekt in diesem spezifischen Feld.

Ein Methodenbefehl besteht aus einer Startklasse, Feldsichtbarkeit und einem Feldnamen.

Syntax:

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

Beispiele für statische Feldbefehle:

Im folgenden Beispiel wird davon ausgegangen, dass this ein Benutzerobjekt ist. Hier greifen wir auf Felder verschiedener Sichtbarkeit in der Benutzerklasse zu. Die Ausgabe jeder Kette ist der Wert des jeweiligen Feldes.

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

Die Verwendung anderer Visibilitäten ist die gleiche wie in den Beispielen für Field Command.

Regex-Befehl

Mit einem regex-Befehl können Sie Zeichenfolgen suchen und/oder ersetzen, die sich aus der SOI ergeben, Rückgabewerte der Methodenbefehle oder der Feldwerte. Die Ausgabe eines regex-Befehls ist eine Zeichenfolge.

Ein regex-Befehl besteht aus der regex-Zeichenfolge. Optional kann er auch aus einer Ersatzzeichenfolge bestehen, zusammen mit der Angabe, ob das erste oder alle Vorkommen ersetzt werden sollen.

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

Beispiele für Regex-Befehle

Beispiele für erweiterte Variablen

Im Folgenden finden Sie ein Beispiel einer Befehlskette in der Datei 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) 

Prüfung der Ausführung der Variablenkette exampleVar:

Endgültiges Ergebnis: Wenn Sie Dimensionen dieses Spans anzeigen, wird ein Tag mit dem Namen exampleVarTag und dem Wert "OracleThatway" angezeigt. Beachten Sie, dass die Angabe von exampleVarTag: "${exampleVar}" im Tagabschnitt erforderlich war, um diese Span-Dimension anzuzeigen.

Voraussetzung:

JDK ist in PATH verfügbar, oder definieren Sie die Umgebungsvariable JAVA_HOME.

Speicherort:

Das Utility ACMLValidate befindet sich im Verzeichnis oracle-apm-agent/bin.

Führen Sie ACMLValidate aus:

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