Instrumentierungsagent für die Entitätsleistung

Die Leistung von Entitäten mit Feldzugriff kann durch Aktivierung des Instrumentierungsagenten von WebSphere eXtreme Scale verbessert werden, wenn Java Development Kit (JDK) Version 1.5 oder höher verwendet wird.

Agenten von eXtreme Scale in JDK Version 1.5 oder höher aktivieren

Der ObjectGrid-Agent kann über eine Java-Befehlszeilenoption mit der folgenden Syntax aktiviert werden:
-javaagent:jarpath[=Optionen]
In dieser Syntax steht jarpath für den Pfad zu einer JAR-Datei (Java-Archiv) der eXtreme-Scale-Laufzeitumgebung, die eine eXtreme-Scale-Agentenklasse und unterstützende Klassen enthält, wie z. B. objectgrid.jar, wsobjectgrid.jar, ogclient.jar, wsogclient.jar oder ogagent.jar. In einem eigenständigen Java-Programm oder in einer Java-EE-Umgebung (Java Platform, Enterprise Edition), in der WebSphere Application Server nicht ausgeführt wird, verwenden Sie gewöhnlich die Datei objectgrid.jar oder die Datei ogclient.jar. In einer Umgebung mit WebSphere Application Server oder mehreren Klassenladeprogrammen müssen Sie die Datei ogagent.jar in der Java-Befehlszeilenoption für den Agenten angeben. Geben Sie die Datei ogagent.config im Klassenpfad an, oder verwenden Sie die Agentenoptionen, um weitere Informationen anzugeben.

Optionen für den Agenten von eXtreme Scale

config
Überschreibt den Namen der Konfigurationsdatei.
include
Gibt die Definition der Umsetzungsdomäne an bzw. überschreibt sie. Diese Definition ist der erste Teil der Konfigurationsdatei.
exclude
Gibt die @Exclude-Definition an bzw. überschreibt sie.
fieldAccessEntity
Gibt die @FieldAccessEntity-Definition an bzw. überschreibt sie.
trace
Gibt eine Tracestufe an. Die gültigen Stufen sind ALL, CONFIG, FINE, FINER, FINEST, SEVERE, WARNING, INFO und OFF.
trace.file
Gibt die Position der Tracedatei an.
Das Semikolon (;) wird als Trennzeichen zwischen den Optionen verwendet. Das Komma () wird als Trennzeichen zwischen den Elementen in einer Option verwendet. Das folgende Beispiel demonstriert die eXtreme-Scale-Agentenoption für ein Java-Programm:
-javaagent:objectgridRoot/lib/objectgrid.jar=config=myConfigFile;
include=includedPackage;exclude=excludedPackage;
fieldAccessEntity=package1,package2

Datei ogagent.config

Die Datei ogagent.config ist der vordefinierte Name für die Konfigurationsdatei des eXtreme-Scale-Agenten. Wenn der Dateiname im Klassenpfad enthalten ist, findet der eXtreme-Scale-Agent die Datei und analysiert sie syntaktisch. Sie können den vordefinierten Dateinamen mit der Option "config" des eXtreme-Scale-Agenten überschreiben. Das folgende Beispiel veranschaulicht, wie die Konfigurationsdatei angegeben wird:
-javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
Die Konfigurationsdatei eines eXtreme-Scale-Agenten setzt sich aus den folgenden Teilen zusammen:
  • Umsetzungsdomäne: Der Teil für die Umsetzungsdomäne ist der erste Teil in der Konfigurationsdatei. Die Umsetzungsdomäne ist eine Liste mit Paketen und Klassen, die am Klassenumsetzungsprozess beteiligt sind. Diese Umsetzungsdomäne muss alle Klassen enthalten, die Entitätsklassen mit Feldzugriff sind, und alle Klassen, die auf diese Entitätsklassen mit Feldzugriff verweisen. Entitätsklassen mit Feldzugriff und die Klassen, die auf diese Entitätsklassen mit Feldzugriff verweisen, bilden die Umsetzungsdomäne. Wenn Sie Entitätsklassen mit Feldzugriff im Teil "@FieldAccessEntity" angeben möchten, müssen Sie die Entitätsklassen mit Feldzugriff hier nicht angeben. Die Umsetzungsdomäne muss vollständig sein. Andernfalls wird eine Ausnahme des Typs "FieldAccessEntityNotInstrumentedException" ausgelöst.
  • @Exclude: Das Token "@Exclude" zeigt an, dass Pakete und Klassen, die hinter diesem Token aufgelistet werden, aus der Umsetzungsdomäne ausgeschlossen werden.
  • @FieldAccessEntity: Das Token "@FieldAccessEntity" zeigt an, dass Pakete und Klassen, die hinter diesem Token aufgelistet werden, Entitätspakete und -klassen mit Feldzugriff sind. Wenn dem Token "@FieldAccessEntity" keine Zeile folgt, ist das dasselbe, als würden Sie @FieldAccessEntity nicht angeben. Der eXtreme-Scale-Agent bestimmt, dass keine Entitätspakete und -klassen mit Feldzugriff definiert sind. Wenn dem Token "@FieldAccessEntity" Zeilen folgen, stellen diese die benutzerdefinierten Entitätspakete und -klassen dar, z. B. "Entitätsdomäne mit Feldzugriff". Die Entitätsdomäne mit Feldzugriff ist eine Unterdomäne der Umsetzungsdomäne. Pakete und Klassen, die in der Entitätsdomäne mit Feldzugriff aufgelistet sind, gehören zur Umsetzungsdomäne, selbst wenn sie nicht in der Umsetzungsdomäne aufgelistet sind. Das Token "@Exclude", das Pakete und Klassen auflistet, die von der Umsetzung ausgeschlossen werden, hat keine Auswirkung auf die Entitätsdomäne mit Feldzugriff. Wenn Sie das Token "@FieldAccessEntity" angeben, müssen alle Entitäten mit Feldzugriff in dieser Entitätsdomäne mit Feldzugriff enthalten sein. Andernfalls wird eine Ausnahme des Typs "FieldAccessEntityNotInstrumentedException" ausgelöst.

Beispiel für eine Agentenkonfigurationsdatei (ogagent.config)

################################
# Das Zeichen # kennzeichnet eine Kommentarzeile.
################################
# Dies ist eine ObjectGrid-Agentenkonfigurationsdatei (der vordefinierte Dateiname ist "ogagent.config"), die
# von einem ObjectGrid-Agenten gefunden und syntaktisch analysiert werden kann, wenn sie im Klassenpfad enthalten ist.
# Wenn die Datei den Namen "ogagent.config" hat und im Klassenpfad enthalten ist, wird für Java-Programme,
# die mit "-javaagent:objectgridRoot/ogagent.jar" ausgeführt werden, der
# ObjectGrid-Agent aktiviert.
# Wenn die Datei nicht den Namen "ogagent.config" hat, aber im Klassenpfad enthalten ist,
# können Sie den Dateinamen mit der Option "config" des ObjectGrid-Agenten angeben.
#     -javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
# In den folgenden Kommentaren finden Sie weitere Informationen zum Überschreiben
# der Instrumentierungseinstellung.

# Der erste Teil der Konfiguration ist die Liste der Pakete und Klassen, die in die
# Umsetzungsdomäne eingeschlossen werden sollen.
# Die einzuschließenden Elemente (Pakete/Klassen), aus denen sich die Instrumentierungsdomäne
# zusammensetzt, müssen am Anfang der Datei stehen.
com.testpackage
com.testClass

# Umsetzungsdomäne: Die vorherigen Zeilen sind Pakete/Klassen, aus denen sich die Umsetzungsdomäne zusammensetzt.
# Das System verarbeitet Klassen mit Namen, die mit den zuvor genannten Paketen/Klassen beginnen, bei der Umsetzung.
#
# Token @Exclude: Schließt Elemente aus der Umsetzungsdomäne aus.
# Das Token @Exclude zeigt an, dass die nachfolgenden Pakete/Klassen aus der Umsetzungsdomäne ausgeschlossen werden sollen.
# Es wird verwendet, wenn der Benutzer einige Pakete/Klassen der zuvor angegebenen eingeschlossenen Pakete ausschließen möchte.
#
# Token @FieldAccessEntity: Entitätsdomäne mit Feldzugriff
# Das Token @FieldAccessEntity gibt an, dass die nachfolgenden Pakete/Klassen Entitätspakete/-klassen mit Feldzugriff sind.
# Wenn dem Token @FieldAccessEntity keine Zeile folgt, ist dies dasselbe, als würden Sie das Token @FieldAccessEntity nicht angeben.
# Die Laufzeitumgebung berücksichtigt es, wenn der Benutzer keine Entitätsklassen/-pakete mit Feldzugriff angibt.
# Die Domäne "Entitätsdomäne mit Feldzugriff" ist eine Unterdomäne der Umsetzungsdomäne.
#
# Pakete/Klassen, die in der "Entitätsdomäne mit Feldzugriff" aufgelistet sind, gehören immer zur Umsetzungsdomäne,
# selbst wenn sie nicht in der Umsetzungsdomäne aufgelistet sind.
# Das Token @Exclude, unter dem Pakete/Klassen aufgelistet werden, die von der Umsetzung ausgeschlossen sind, hat
# keine Auswirkung auf die "Entitätsdomäne mit Feldzugriff".
# Anmerkung: Wenn Sie @FieldAccessEntity angeben, müssen alle Entitäten mit Feldzugriff in der Entitätsdomäne
#            mit Feldzugriff enthalten sein, ansonsten wird eine Ausnahme des Typs "FieldAccessEntityNotInstrumentedException" ausgegeben.
#
# Die Standardkonfigurationsdatei für den ObjectGrid-Agenten ist "ogagent.config".
# Die Laufzeitumgebung sucht diese Datei als Ressource im Klassenpfad und verarbeitet sie.
# Benutzer können diese vordefinierte ObjectGrid-Agentenkonfigurationsdatei mit der Option
# "config" des Agenten überschreiben.
#
# Beispiel:
#	javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
#
# Die Instrumentierungsdefinition, einschließlich Umsetzungsdomäne, @Exclude und @FieldAccessEntity, kann
# individuell mit entsprechenden vordefinierten Agentenoptionen überschrieben werden.
# Zu den vordefinierten Agentenoptionen gehören:
#    include              -> Wird verwendet, um die Definition der Instrumentierungsdomäne (erster Teil der Konfigurationsdatei) zu überschreiben.
#    exclude              -> Wird verwendet, um die @Exclude-Definition zu überschreiben.
#    fieldAccessEntity    -> Wird verwendet, um die @FieldAccessEntity-Definition zu überschreiben.
#
# Die Agentenoptionen müssen durch ein Semikolon (";") voneinander getrennt werden.
# In der Agentenoption müssen die Pakete und Klassen ein Komma (",") voneinander getrennt werden.
#
# Im Folgenden sehen Sie ein Beispiel, das den Namen der Konfigurationsdatei nicht überschreibt:
#    -javaagent:objectgridRoot/lib/objectgrid.jar=include=includedPackage;exclude=excludedPackage;fieldAccessEntity=package1,package2
#
################################

@Exclude
com.excludedPackage
com.excludedClass

@FieldAccessEntity

Leistungshinweis

Um eine bessere Leistung zu erzielen, geben Sie die Umsetzungsdomäne und die Entitätsdomäne mit Feldzugriff an.