Oracle Cloud Infrastructure-Dokumentation

Metriken erfassen

Der APM-Java-Agent unterstützt die regelmäßige Erfassung von Anwendungsservermetriken.

Nachdem der APM-Java-Agent durch Deployment bereitgestellt wurde, können Sie die folgenden Metriktypen erfassen:

Standardmetriken

Standardmetriken sind vom System definierte Metriken, die standardmäßig verfügbar sind.

Eine vollständige Gruppe von Standardmetriken finden Sie unter Verfügbare Metriken: oracle_apm_monitoring für APM-Java-Agent.

Benutzerdefinierte Metriken

Benutzerdefinierte Metriken können zusätzlich zu den vorhandenen Standardmetriken erstellt werden, um bestimmte Anforderungen zu erfüllen.

Um eine benutzerdefinierte Metrik zu definieren, erstellen Sie eine neue Konfigurationsdatei mit dem Namen MetricCollection.acml im Verzeichnis oracle-apm-agent/config/<version>.

Die Datei MetricCollection.acml ist eine benutzerdefinierte Datei im ACML-Format (Untergruppe von YAML) für die Konfiguration der benutzerdefinierten Metrikerfassung.

ACML-Tag Datentyp Beschreibung
<group name>: Zeichenfolge Gruppe zur Trennung von Metriken mit unterschiedlichen Startzeiten und Intervallen der Erfassung.
<metric name>: Zeichenfolge Name der zu erfassenden Metrik. Ein Metrikname entspricht nur einem Wert. Die Benennungskonvention ist eine durch Bindestrich getrennte Zeichenfolge in Kleinbuchstaben.
type: Zeichenfolge Metriktyp. Kann eine Messung oder ein Delta sein.

- Messung: aktueller Laufzeitwert.

- Delta: Wertdifferenz zwischen Erfassungsintervallen.
scalar: Zeichenfolge Typ des numerischen Werts: Long oder Double.
source:   Tag, das ein Array von Quelleinträgen der Metrik darstellt. Jede Metrik kann einen oder mehrere Quelleinträge enthalten. Auch wenn mehrere Quelleneinträge vorhanden sind, wird bei der Erfassung jeder Eintrag der Reihe nach geprüft. Wenn der Eintrag einen gültigen Wert zurückgeben kann, wird er für den Metrikeintrag verwendet, und die restlichen Quelleinträge werden ignoriert.
-   Arrayelement für einen Metrikquelleintrag.
type: Zeichenfolge Typ der Metrikquelle. Kann "mbean" oder "mbeans" sein.

Bei der valuePath-Konfiguration kann es MBean oder MBeans sein.

Bei der Konfiguration operationName kann es sich nur um ein MBean handeln.

mbean_name: Zeichenfolge MBean-Objektname für den Typ "mbean" oder "mbeans". Beim Typ "mbeans" kann der Objektname Platzhalter (*) enthalten. Platzhalterzeichen werden vom Typ "mbeans" jedoch nicht unterstützt.
value_path: Zeichenfolge Der Pfad wird durch Schrägstriche (/) getrennt, um den Wert des MBeans zu erhalten. Der Wertpfad muss einen numerischen Wert ergeben. Neben dem Root-Pfad, der der Attributname des MBean-Objekts sein muss, kann der geteilte Pfad einem der folgenden Elemente des vorherigen Pfadwerts entsprechen:
  • Objektfeldname.
  • Methodenname des Objekts, der keinen Parameter annimmt.
  • Schlüssel von CompositeData.
  • Schlüssel von TubularData.
  • Index des Arrays.
  • Schlüssel der Zuordnung.
  • Index der Erfassung.

Beim Typ "mbeans" wird der Wert jedes MBean-Objekts aggregiert. Ebenso werden alle abgerufenen Werte aggregiert, wenn beim Typ "mbeans" ein Platzhalter (*) im Pfad verwendet wird.
operation_name Zeichenfolge Name der aufzurufenden MBean-Methode. Beachten Sie, dass MBean beim Plattformserver MBean registriert sein muss.
Parameter (optional) Zeichenfolge Werte von durch Komma getrennten Methodenparamatern.

Die übergebenen Methodenparameter und die entsprechenden Werte werden als Metrikdimensionen erfasst. Derzeit wird nur der Datentyp "Zeichenfolge" für Methodenparameter unterstützt.
Benutzerdefinierte Metriken können auf zwei Arten mit dem Attribut value_path oder operationName definiert werden.
  • Attribut value_path: Ermöglicht das Extrahieren der Metrik aus dem registrierten MBean
  • Attribut operationName: Ermöglicht dem Benutzer, jede benutzerdefinierte Klasse beim MBean-Server zu registrieren und die mit operationName angegebene MBean-Methode aufzurufen.

Beispiel mit dem Attribut value_path:

MyMetrics:
    jvm-used-heap:
        type: measurement
        scalar: long
        source:
          -
            type: mbean
            mbean_name: java.lang:type=Memory
            value_path: HeapMemoryUsage/used
    jvm-used-heap-after-old-gc:
        type: measurement
        scalar: long
        source:
          -
            type: mbeans
            mbean_name: java.lang:type=GarbageCollector,name=*Old*
            value_path: LastGcInfo/memoryUsageAfterGc/*/value/used
          -
            type: mbeans
            mbean_name: java.lang:type=GarbageCollector,name=*MarkSweep*
            value_path: LastGcInfo/memoryUsageAfterGc/*/value/used

Im obigen Beispiel werden Metriken am Anfang jeder Minute erfasst. Zwei Metriken sollen erfasst werden: jvm-heap-used und jvm-used-heap-after-old-gc.

Für jvm-heap-used gibt es nur eine Quelle, nämlich mbean. Der Name des MBean-Objekts lautet java.lang:type=Memory. Dieses MBean-Objekt hat das Attribut HeapMemoryUsage mit dem Datentyp CompositeDataSupport. Es ist nicht numerisch und kann nicht als Metrik verwendet werden. Es stellt jedoch eine Zuordnung von Metriken dar, aus denen der verwendete Heap abgerufen werden kann. Daher ist ein Drilldown zum Objekt mit dem verwendeten Zuordnungsschlüssel erforderlich.

Für jvm-used-heap-after-old-gc gibt es zwei Quellen vom Typ mbeans (jeweils im Plural mit "s"). Die Metrik wird in der Reihenfolge gemäß Definition erfasst, und die erste Quelle, die eine gültige Metrik zurückgibt, wird verwendet. Der Grund für das Vorhandensein von zwei Quellen besteht in den unterschiedlichen Garbage-Collector-Namen unterschiedlicher Java-Versionen. Für den Drilldown zu value_path werden außerdem Platzhalter verwendet, und alle Werte für den gesamten belegten Arbeitsspeicher nach GC werden als einzelner Metrikwert summiert. Der Daten-Drilldown für den Wertpfad lautet LastGcInfo/memoryUsageAfterGc/*/value/used, was sich auf LastGcInfo(CompositeData)/memoryUsageAfterGc(TabularData)/<index>(CompositeData)/value(MemoryUsage)/used(Long) bezieht.

Beispiel mit dem Attribut operationName:

MyMetrics:
    CacheStatistics:
       type: measurement
       scalar: double
       skippable: false
       source:
        - type: mbean
          mbean_name:com.cache:type=CacheServiceMXBean
          operation_name: cacheStatistics
          params: SessionCache,JohnDoe
    DatabaseQueryTime:
       type: measurement
       scalar: long
       skippable: false    
       source:
        - type: mbean
          mbean_name: com.db:type=DbManagerMXBean
          operation_name: dbQueryTime

Im obigen Beispiel werden Metriken am Anfang jeder Minute erfasst. Es müssen zwei Metriken erfasst werden: CacheStatistics und DatabaseQueryTime. Quelle für diese MBean-Konfiguration kann nur MBean sein.

Für CacheStatistics lautet der MBean-Objektname com.cache:type=CacheServiceMXBean. Die aufzurufende Methode ist cacheStatistics. Der Vorgang ruft Cache-Statistiken für den angegebenen Cachenamen ab, gefiltert nach dem jeweiligen Benutzer. SessionCache und JohnDoe sind die Parameterwerte für CacheName bzw. UserName. Benutzer können eine Zuordnung nützlicher Attribute wie AssociatedCacheName, CacheHits, CacheMisses, InMemoryHits, OnDiskHits als Dimensionen erstellen und als Teil der unterstützten Rückgabetypen zurückgeben, wie unten beschrieben, zusammen mit den entsprechenden Werten.

Für DatabaseQueryTime lautet der MBean-Objektname com.db:type=DbManagerMXBean. Die aufzurufende Methode ist dbQueryTime. Für dieses MBean wurden keine Parameter konfiguriert.

Folgende Methodenrückgabetypen werden unterstützt:
  • Map<Map<String, Object>, Long>
  • Map<Map<String, Object>, Double>
  • Long
  • Double