8.3 Dump Sampling Commands

Use the commands in Table 8-4 to capture samples of diagnostic dumps at specified intervals.

Table 8-4 Dump Sampling Commands

Use this command...	To...	Use with WLST...
addDumpSample	Create samplings for Diagnostic Framework dumps.	Online
enableDumpSampling	Enable or disables all dump samplings.	Online
getSamplingArchives	Collect all dump samplings in a zip file containing the individual sampling files and a readme file.	Online
isDumpSamplingEnabled	List whether dump sampling is enabled or disabled.	Online
listDumpSamples	List all dump samplings, a specified dump sampling, or all dump samplings associated with a specified server.	Online
removeDumpSample	Remove the specified dump sampling.	Online
updateDumpSample	Update the specified dump sampling, modifying the settings of the sampling.	Online

8.3.1 addDumpSample

Use with WLST: Online

Description

Creates dump samplings for Diagnostic Framework dumps.

Syntax

addDumpSample(sampleName, diagnosticDumpName [, appName], samplingInterval,
 rotationCount [, dumpedImplicitly] [, toAppend] [, args] [, server])

Argument	Definition
sampleName	The name of the sampling.
diagnosticDumpName	The name of the diagnostic dump to be sampled.
appName	Optional. The name of the application associated with the specified diagnostic dump. If you do not specify appName, the diagnostic dump has a scope of system.
samplingInterval	The sampling interval in seconds. If you specify zero or a negative value, sampling is suspended.
rotationCount	The maximum number of diagnostic dump samples to be kept in a rotation list. When this limit is reached, the oldest sample is deleted.
dumpedImplicitly	Optional. A Boolean value that specifies whether the diagnostic dump archive will be included in the dfw.samplingArchive. Valid values are `true` and `false`. The default is true. If the value is false, and you want to include the dump archive in the dfw.samplingArchive, you must pass the sampling name to the executeDump command using the args parameter.
toAppend	Optional. A Boolean value that specifies whether the diagnostic dump samples are appended to its predecessor, resulting in a single archive when you execute dfw.samplingArchive. Valid values are `true` and `false`. The default is true. If the value is true, the sample is appended to its predecessor. If the value is false, dfw.sampleArchive returns a zip file containing individual sample files. Specify false if the dump samples contain binary data.
args	Optional. Diagnostic dump arguments to be used by the diagnostic dump at each sampling time. The arguments are expressed as name/value pairs.
server	Optional. The name of the server from which to collect the information. If you do not specify this parameter, this command associates the dump sampling with the Administration Server.

Example

The following example adds a sampling for the dump dms.metrics:

addDumpSample(sampleName='dms_metrics', diagnosticDumpName='dms.metrics',
               samplingInterval=300, rotationCount=10)
 
dms_metrics is added

8.3.2 enableDumpSampling

Use with WLST: Online

Description

Enables or disables all dump samplings. This command affects all configured dump samplings.

Syntax

enableDumpSampling(enable [,server])

Argument	Definition
enable	A Boolean value that specifies whether to enable or disable dump samplings. Valid values are `true` and `false`.
server	Optional. The name of the server for which to enable or disable dump sampling. If you do not specify this parameter, this command enables or disables the dump sampling for the Administration Server.

Example

The following example disables all dump samplings:

enableDumpSampling(enable=false)

Dump sampling disabled

8.3.3 getSamplingArchives

Use with WLST: Online

Description

Collects all dump samplings in a zip file containing the individual sampling files and a readme file. This method is particularly useful in dealing with binary format dumps.

Syntax

getSamplingArchives([sampleName,] outputFile [,server])

Argument	Definition
name	Optional. The name of a particular dump sampling that you want to retrieve. If you do not specify this argument, the command returns all dump samplings.
outputFile	The absolute path of the file to which the dump samplings will be written.
server	Optional. The name of the server from which to collect the information. If you do not specify this parameter, this command collects the dump samples for the Administration Server.

Example

The following example retrieves the dump sampling for the dump JVMThreadDump:

getSamplingArchives(sampleName="JVMThreadDump", outputFile="/tmp/jvm_dump.zip")
wrote 63518 bytes to /tmp/jvm_dump.zip

The following shows the contents of the zip file:

 unzip -l jvm_dump.zip
Archive:  jvm_dump.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
   508780  05-21-13 07:25   dfw_samplingArchive1065570966467923683.JVMThreadDump.dmp
      840  05-21-13 07:25   dfw_samplingArchive7749640004639161119.readme.txt
 --------                   -------
   509620                   2 files

8.3.4 isDumpSamplingEnabled

Use with WLST: Online

Description

Lists whether dump sampling is enabled or disabled.

Syntax

isDumpSamplingEnabled([server])

Argument	Definition
server	Optional. The name of the server to determine if dump sampling is enabled or disabled. This argument is only valid when you are connected to the Administration Server.

Example

The following example lists the whether dump sampling is enabled or disabled for the server wls_server_1:

isDumpSamplingEnabled(server="wls_server_1")

true

8.3.5 listDumpSamples

Use with WLST: Online

Description

Lists all dump samplings, a specified dump sampling, or all dump samplings associated with a specified server.

Syntax

listDumpSamples([sampleName] [, server])

Argument	Definition
sampleName	Optional. The name of the sampling.
server	Optional. The name of the server for which to list the dump samplings. If you do not specify this parameter, this command lists the dump samplings for the Administration Server.

Example

The following example lists all dump samplings associated with the server wls_server_1:

listDumpSamples(server="wls_server_1")
Name              : JVMThreadDump
Dump Name         : jvm.threads
Application Name  : 
Sampling Interval : 30
Rotation Count    : 20
Dump Implicitly   : true
Append Samples    : true
Dump Arguments    : context=true, timing=true, progressive=true, depth=20, threshold=30000
 
Name              : JavaClassHistogram
Dump Name         : jvm.classhistogram
Application Name  : 
Sampling Interval : 1800
Rotation Count    : 5
Dump Implicitly   : false
Append Samples    : true
Dump Arguments    :

8.3.6 removeDumpSample

Use with WLST: Online

Description

Removes the dump sampling.

Syntax

removeDumpSample(sampleName [,server])

Argument	Definition
sampleName	The name of the sampling to be removed.
server	Optional. The name of the server from which to remove the sampling. If you do not specify this parameter, the dump sampling is removed from the Administration Server.

Example

The following example removes the dump sampling named HTTPSampling, associated with the server wls_server_1:

removeDumpSample(sampleName="HTTPSampling", server="wls_server_1")

Removed HTTPSampling

8.3.7 updateDumpSample

Use with WLST: Online

Description

Updates the specified dump sampling, modifying the settings of the sampling. You cannot change the name of the sampling. Modifications take affect at the next sampling interval.

Syntax

updateDumpSample(sampleName [, appName], samplingInterval, 
    rotationCount [,dumpedImplicitly] [, toAppend] [, arg,] 
    [, server])

Argument	Definition
sampleName	The name of the dump sampling.
appName	Optional. The name of the application associated with the specified diagnostic dump. If you do not specify appName, the diagnostic dump has a scope of system.
samplingInterval	Optional. The sampling interval in seconds. If you specify zero or a negative value, sampling is suspended.
rotationCount	Optional. The maximum number of diagnostic dump samplings to be kept in a rotation list. When this limit is reached, the oldest sampling is deleted
dumpedImplicitly	Optional. A Boolean value that specifies whether the diagnostic dump archive will be included in the dfw.samplingArchive. Valid values are `true` and `false`. The default is true. If the value is false, and you want to include the dump archive in the dfw.samplingArchive, you must pass the sampling name to the executeDump command using the args parameter.
toAppend	Optional. A Boolean value that specifies whether the diagnostic dump samples are appended to its predecessor, resulting in a single archive when you execute dfw.samplingArchive. Valid values are `true` and `false`. The default is true. If the value is true, the sample is appended to its predecessor. If the value is false, dfw.sampleArchive returns a zip file containing individual sampling files. Specify false if the dump samplings contain binary data.
args	Optional. Diagnostic dump arguments to be used by the diagnostic dump at each sampling time. The arguments are expressed as name/value pairs.
server	Optional. The name of the server from which to collect the information. If you do not specify this parameter, the dump sampling is updated for the Administration Server.

Example

The following example updates the dump sampling HTTPSampling, modifying the sampling interval, rotation count, and server.

updateDumpSample(sampleName="HTTPSampling", samplingInterval=200,
                   rotationCount=5, server="wls_server1")
 
HTTPSampling is updated