WebSphere eXtreme Scale Programming Guide > Access data in WebSphere eXtreme Scale > EntityManager API introduction > EntityManager interface performance impact



Instrumentation agent


You can improve the performance of field-access entities by enabling the WebSphere eXtreme Scale instrumentation agent when using Java™ Development Kit (JDK) Version 1.5 or later.


Enable eXtreme Scale agent on JDK v1.5 or above

The ObjectGrid agent can be enabled with a Java command line option with the following syntax: 

-javaagent:jarpath[=options]

The jarpath value is the path to an eXtreme Scale runtime Java archive (JAR) file that contains eXtreme Scale agent class and supporting classes such as the objectgrid.jar, wsobjectgrid.jar, ogclient.jar, wsogclient.jar, and ogagent.jar files. Typically, in a stand-alone Java program or in a Java Platform, Enterprise Edition environment that is not running WebSphere Application Server, use the objectgrid.jar or ogclient.jar file. In a WebSphere Application Server or a multi-classloaders environment, use the ogagent.jar file in the Java command line agent option.

In addition to the agent JAR file, the cglib.jar file is required for inclusion in the bootstrap class path. In WebSphere Application Server, although the cglib.jar file might already be in the lib directory and included in application server class path, specify the cglib.jar file path in the class path property of the Java virtual machine (JVM) that is associated with the application server. Provide the ogagent.config file in the class path or use agent options to specify additional information.


eXtreme Scale agent options

config

Overrides the configuration file name.

include

Specifies or overrides transformation domain definition that is the first part of the configuration file.

exclude

Specifies or overrides the @Exclude definition.

fieldAccessEntity

Specifies or overrides the @FieldAccessEntity definition.

trace

Trace level. Levels can be ALL, CONFIG, FINE, FINER, FINEST, SEVERE, WARNING, INFO, and OFF.

trace.file

Location of the trace file.
The semicolon ( ; ) is used as a delimiter to separate each option. The comma ( , ) is used as a delimiter to separate each element within an option. The following example demonstrates the eXtreme Scale agent option for a Java program: 

-javaagent:objectgridRoot/lib/objectgrid.jar=config=myConfigFile;
include=includedPackage;exclude=excludedPackage;
fieldAccessEntity=package1,package2


ogagent.config file

The ogagent.config file is the designated eXtreme Scale agent configuration file name. If the file name is in the class path, the eXtreme Scale agent finds and parses the file. You can override the designated file name through the config option of eXtreme Scale agent. The following example shows how to specify the configuration file: 

-javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile

An eXtreme Scale agent configuration file has the following parts:


Example agent configuration file (ogagent.config)

################################
# The # indicates comment line
################################
# This is an ObjectGrid agent config file (the designated file name is ogagent.config) that can be found and parsed by the ObjectGrid agent
# if it is in classpath.
# If the file name is "ogagent.config" and in classpath, Java program runs with -javaagent:objectgridRoot/ogagent.jar will have
# ObjectGrid agent enabled.
# If the file name is not "ogagent.config" but in classpath, you can specify the file name in config option of ObjectGrid agent
#     -javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
# See comments below for more info regarding instrumentation setting override.

# The first part of the configuration is the list of packages and classes that should be included in transformation domain.
# The includes (packages/classes, construct the instrumentation doamin) should be in the beginning of the file.
com.testpackage
com.testClass

# Transformation domain: The above lines are packages/classes that construct the transformation domain.
# The system will process classes with name starting with above packages/classes for transformation.
#
# @Exclude token : Exclude from transformation domain.
# The @Exclude token indicates packages/classes after that line should be excluded from transformation domain.
# It is used when user want to exclude some packages/classes from above specified included packages
#
# @FieldAccessEntity token: Field-access Entity domain.
# The @FieldAccessEntity token indicates packages/classes after that line are field-access Entity packages/classes.
# If there is no lilne after the @FieldAccessEntity token, it is equivalent to "No @FieldAccessEntity specified".
# The runtime will consider the user does not specify any field-access Entity packages/classes.
# The "field-acces Entity domain" is a sub-domain of transformation domain.
#
# Packages/classes listed in the "field-access Entity domain" will always be part of transformation domain,
# even they are not listed in transformation domain.
# The @Exclude, which lists packages/classes excluded from transformation, has no impact on the "field-acces Entity domain".
# Note: When @FieldAccessEntity is specified, all field-access entities must be in this field-acces Entity domain,
#       otherwise, FieldAccessEntityNotInstrumentedException may occur.
#
# The default ObjectGrid agent config file name is ogagent.config
# The runtime will look for this file as a resource in classpath and process it.
# Users can override this designated ObjectGrid agent config file name via config option of agent.
#
# e.g.
#    javaagent:objectgridRoot/lib/objectgrid.jar=config=myOverrideConfigFile
#
# The instrumentation definition, including transformation domain, @Exclude, and  @FieldAccessEntity can be overriden individually
# by corresponding designated agent options.
# Designated agent options include:
#    include              -> used to override instrumentation domain definition that is the first part of the config file
#    exclude              -> used to override @Exclude definition
#    fieldAccessEntity    -> used to override @FieldAccessEntity definition
#
# Each agent option should be separated by ";"
# Within the agent option, the package or class should be seperated by ","
#
# The following is an example that does not override the config file name:
#    -javaagent:objectgridRoot/lib/objectgrid.jar=include=includedPackage;exclude=excludedPackage;fieldAccessEntity=package1,package2
#
################################

@Exclude
com.excludedPackage
com.excludedClass

@FieldAccessEntity


Performance consideration

For better performance, specify the transformation domain and field-access entity domain.



Parent topic

EntityManager interface performance impact


+

Search Tips   |   Advanced Search