Diagnostic Framework Custom WLST Commands

8 Diagnostic Framework Custom WLST Commands

The Diagnostic Framework aids in capturing relevant and timely diagnostics for critical errors. The diagnostics can be sent to Oracle Support for further analysis. Use the Diagnostic Framework commands to generate incidents, query existing incidents and execute individual diagnostics dumps to gather specific diagnostics data. This chapter provides detailed descriptions of WLST commands for the Diagnostic Framework, including command syntax, arguments, and command examples.

For additional information about using the Diagnostic Framework, see Diagnosing Problems in Administering Oracle Fusion Middleware.

The following topics lists the different categories of Diagnostic Framework commands.

Incident Commands
An incident is a single occurrence of a problem. When a problem (critical error) occurs multiple times, an incident is created for each occurrence. The WLST Diagnostic Framework incident commands let you view problems and incidents and create incidents.
Diagnostic Dump Commands
A diagnostic dump captures and dumps specific diagnostic information when an incident is created (automatic) or on the request of an administrator (manual). The WLST diagnostic dump commands let you view and execute dumps.
Dump Sampling Commands
Diagnostic dump sampling captures the output of diagnostic dumps at specified intervals. The WLST diagnostic dump sampling commands let you manage dump samplings.

Incident Commands

An incident is a single occurrence of a problem. When a problem (critical error) occurs multiple times, an incident is created for each occurrence. The WLST Diagnostic Framework incident commands let you view problems and incidents and create incidents.

Use the commands in the following sections to view problems and incidents and to create incidents.

createAggregatedIncident
This command is used to create an aggregated incident, containing zip files that contain copies of incidents that match the specified criteria.
createIncident
This command is used to create a diagnostic incident.
getIncidentFile
This command is used to retrieve the contents of the specified incident file.
listADRHomes
This command lists the set of ADR Home paths.
listIncidents
This command lists a set of diagnostic incidents.
listProblems
This command lists a set of diagnostic problems.
queryIncidents
This command lists the incidents that meet the specified criteria.
reloadCustomRules
This command is used to reload all custom diagnostic rules or the specified rule.
showIncident
This command shows the details of a specified incident.

Parent topic: Diagnostic Framework Custom WLST Commands

createAggregatedIncident

This command is used to create an aggregated incident, containing zip files that contain copies of incidents that match the specified criteria.

Command Category: Incidents

Use with WLST: Online

Description

Creates an aggregated incident, containing zip files that contain copies of incidents that match the specified criteria.

Syntax

createAggregatedIncident(query [, servers])

Argument Definition

Argument	Definition
`query`	An expression composed of simple expressions, which can be connected by Boolean operators. An expression contains an incident attribute, an operator, and a string, in the following format: attribute operator "string" Simple expressions can be connected by the Boolean operators AND or OR, grouped by parentheses () The following incident attributes are supported: TIMESTAMP: Incident creation time. You can use the `from` and `to` operators to specify a time range. The date format is `YYYY-MM-DD HH:MM`. ECID: Execution Context ID PROBLEM_KEY: Problem Key MSG_FACILITY: The error message facility, such as ORA or OHS. MSG_NUMBER: The error message ID, such as 600. Custom incident attributes are also supported. For example, TRACEID, APP, URI, AND DSID are supported. The following operators are supported: equals notEqual startsWith endsWith contains isNull notNull
`servers`	The name of one or more servers to query. This argument is optional. If you do not specify it, the command operates on all servers in the domain. This option is only valid when you are connected to the Administration Server.

query

An expression composed of simple expressions, which can be connected by Boolean operators. An expression contains an incident attribute, an operator, and a string, in the following format:

attribute operator "string"

Simple expressions can be connected by the Boolean operators AND or OR, grouped by parentheses ()

The following incident attributes are supported:

TIMESTAMP: Incident creation time. You can use the from and to operators to specify a time range. The date format is YYYY-MM-DD HH:MM.
ECID: Execution Context ID
PROBLEM_KEY: Problem Key
MSG_FACILITY: The error message facility, such as ORA or OHS.
MSG_NUMBER: The error message ID, such as 600.

Custom incident attributes are also supported. For example, TRACEID, APP, URI, AND DSID are supported.

The following operators are supported:

equals
notEqual
startsWith
endsWith
contains
isNull
notNull

servers

The name of one or more servers to query. This argument is optional. If you do not specify it, the command operates on all servers in the domain.

This option is only valid when you are connected to the Administration Server.

Examples

The following example creates an aggregated incident for al incidents that contain the ODL_TRACE_ID of 123456 on the server wls_server1:

createAggregatedIncident(query="ORDL_TRACE_ID equals 123456", servers="wls_server1")
Incident 55 created, containing the following incidents:
Server wls_server1
Incident Id    Problem Key                                     Incident Time
15                 TRACE [123456] [MANUAL]          Mon Apr 17 11:22:12 EDT 2017

The following example creates an aggregated incident for all incidents that contain the ODL_TRACE_ID of 123456 on all servers in the domain:

createAggregatedIncident(query="ORDL_TRACE_ID equals 123456", servers="wls_server1")
Incident 55 created, containing the following incidents:
Server wls_server1, wls_server2
Incident Id    Problem Key                                     Incident Time
15                 TRACE [123456] [MANUAL]          Mon Apr 17 11:22:12 EDT 2017

Parent topic: Incident Commands

createIncident

This command is used to create a diagnostic incident.

Command Category: Incidents

Use with WLST: Online

Description

Creates a diagnostic incident, using the specified information to determine the set of diagnostic rules and actions to execute.

Syntax

createIncident([adrHome] [,incidentTime] [,messageId] [,ecid] [,appName]
  [,description] [,server])

Argument	Definition
`adrHome`	The path for the ADR Home in which to create the incident. The ADR Home must exist. If this argument is not specified, the default ADR Home is used. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`incidentTime`	The timestamp at which the incident occurred. If this argument not specified, the current time is used. You can specify the following: The time of the current day, in the format HH:MM. For example: 19:45 The date and time, in the format MM/DD/YYYY HH:MM
`messageId`	The ID of the error message. For example, MDS-50400.
`ecid`	The Execution Context ID for the error message.
`appName`	The name of the deployed application for which the diagnostics are being gathered. For example, if you have multiple ADF applications deployed, each may register a dump called adf.dump. To execute this command for a specific application, you must specify the application name.
`description`	Descriptive text to associate with the incident. This is useful when reviewing the incident at a later time.
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example creates an incident that is related to messages with the ID MDS-50400:

createIncident(messageId="MDS-50400", description="sample incident")
Incident Id: 3
Problem Id: 2
Problem Key: MDS-50400 [MANUAL]
Incident Time:Tue May 23 11:52:45 PDT 20137
Error Message Id: MDS-50400
Execution Context:null
Flood Controlled: false
Dump Files :
   jvm_threads25_i3.txt
   dms_metrics26_i3.txt
   dfw_samplingArchive28_i3.readme.txt
   odl_logs29_i3.txt

Parent topic: Incident Commands

getIncidentFile

This command is used to retrieve the contents of the specified incident file.

Command Category: Incidents

Use with WLST: Online

Description

Retrieves the contents of the specified incident file.

Syntax

getIncidentFile(id, name [,outputFile] [,adrHome] [,server])

Argument	Definition
`id`	The ID of the incident that you want to retrieve.
`name`	The name of the file to retrieve. To find the name of the file, use the showIncident command.
`outputFile`	The name of the file to which to write the output.
`adrHome`	The path for the ADR Home from which to retrieve the information. If this argument is not specified, the default ADR Home is queried. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example writes the contents of the incident dms_metrics3_i1.dmp to the specified output file:

getIncidentFile(id='1', name='dms_metrics3_i1.dmp', outputFile='/tmp/incident1_dms.txt')
The content of 'dms_metrics3_i1.dmp'is written to /tmp/incident1_dms.txt

Parent topic: Incident Commands

listADRHomes

This command lists the set of ADR Home paths.

Command Category: Incidents

Use with WLST: Online

Description

Lists the paths of all of the ADR Homes for the server.

Syntax

listADRHomes([server])

Argument	Definition
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example lists the paths of the ADR homes:

listADRHomes()
diag/ofm/base_domain/AdminServer
diag/ofm/EMGC_DOMAIN/EMOMS

Parent topic: Incident Commands

listIncidents

This command lists a set of diagnostic incidents.

Command Category: Incidents

Use with WLST: Online

Description

Lists the set of diagnostic incidents for the given problem ID, if specified, or all available incidents.

Syntax

listIncidents([id] [, adrHome] [,server])

Argument Definition

Argument	Definition
`id`	The ID of the problem for which you want to list the set of diagnostic incidents.
`adrHome`	The path for the ADR Home from which to query incidents. If this argument is not specified, the default ADR Home is queried. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

id

The ID of the problem for which you want to list the set of diagnostic incidents.

adrHome

The path for the ADR Home from which to query incidents. If this argument is not specified, the default ADR Home is queried.

The default ADR Home is the following location:

ADR_BASE/diag/OFM/domain_name/server_name

server

The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example lists the incidents associated with the problem with the ID 1:

listIncidents(id="1")
Incident Id     Incident Time                   Problem Key
        2       Tue May 23 11:05:59 PDT 2017    MDS-50500 [MANUAL]
        1       Tue May 23 11:02:22 PDT 2017    MDS-50500 [MANUAL]

Parent topic: Incident Commands

listProblems

This command lists a set of diagnostic problems.

Command Category: Incidents

Use with WLST: Online

Description

Lists the set of diagnostic problems associated with the specified ADR Home.

Syntax

listProblems([adrHome][,server])

Argument Definition

Argument	Definition
`adrHome`	The path for the ADR Home from which to query problems. If this argument is not specified, the default ADR Home is queried. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

adrHome

The path for the ADR Home from which to query problems. If this argument is not specified, the default ADR Home is queried.

The default ADR Home is the following location:

ADR_BASE/diag/OFM/domain_name/server_name

server

The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example lists the diagnostic problems in the default ADR home:

listProblems()
Problem Id        Problem Key
         1        MDS-50500 [MANUAL]
         2        JOC-38922 [AdminServer] [oracle.cache.network]

Parent topic: Incident Commands

queryIncidents

This command lists the incidents that meet the specified criteria.

Command Category: Incidents

Use with WLST: Online

Description

Lists the incidents that meet the specified criteria. You can query for the value of particular attributes across one or more servers, or all servers in a domain.

Syntax

queryIncidents(query [,servers])

Argument Definition

Argument	Definition
`query`	An expression composed of simple expressions, which can be connected by Boolean operators. An expression contains an incident attribute, an operator, and a string, in the following format: attribute operator "string" Simple expressions can be connected by the Boolean operators AND or OR, grouped by parentheses () The following incident attributes are supported: TIMESTAMP: Incident creation time. You can use the `from` and `to` operators to specify a time range. The date format is `YYYY-MM-DD HH:MM`. ECID: Execution Context ID PROBLEM_KEY: Problem Key MSG_FACILITY: The error message facility, such as ORA or OHS. MSG_NUMBER: The error message ID, such as 600 Custom incident attributes are also supported. For example, TRACEID, APP, URI, AND DSID are supported. In addition, the context values, as shown in the incident readme.txt file, are supported. For example, DFW_APP_NAME and DFW_USER_NAME are supported. The following operators are supported: equals notEqual startsWith endsWith contains isNull notNull
`servers`	The name of one or more servers to query. This argument is optional. If you do not specify it, the command operates on all servers in the domain. This option is only valid when you are connected to the Administration Server.

query

An expression composed of simple expressions, which can be connected by Boolean operators. An expression contains an incident attribute, an operator, and a string, in the following format:

attribute operator "string"

Simple expressions can be connected by the Boolean operators AND or OR, grouped by parentheses ()

The following incident attributes are supported:

TIMESTAMP: Incident creation time. You can use the from and to operators to specify a time range. The date format is YYYY-MM-DD HH:MM.
ECID: Execution Context ID
PROBLEM_KEY: Problem Key
MSG_FACILITY: The error message facility, such as ORA or OHS.
MSG_NUMBER: The error message ID, such as 600

Custom incident attributes are also supported. For example, TRACEID, APP, URI, AND DSID are supported. In addition, the context values, as shown in the incident readme.txt file, are supported. For example, DFW_APP_NAME and DFW_USER_NAME are supported.

The following operators are supported:

equals
notEqual
startsWith
endsWith
contains
isNull
notNull

servers

The name of one or more servers to query. This argument is optional. If you do not specify it, the command operates on all servers in the domain.

This option is only valid when you are connected to the Administration Server.

Examples

The following example queries all incidents in the domain for the ECID f19wAgN000001:

queryIncidents(query="ECID equals f19wAgN000001")

The following example queries all incidents that occurred between March 1, 2017 and March 15, 2017, for the server wls_server1:

 queryIncidents(query="TIMESTAMP from '2017-03-01 00:00'AND TIMESTAMP to '2017-03-15 00:00'", servers=["wls_server1"])

Parent topic: Incident Commands

reloadCustomRules

This command is used to reload all custom diagnostic rules or the specified rule.

Command Category: Incidents

Use with WLST: Online, Offline

Description

Reloads all custom diagnostic rules or the specified custom diagnostic rule.

Syntax

reloadCustomRules([name] [, server])

Argument Definition

Argument	Definition
`name`	The name of a custom diagnostic rule. This argument is optional. If you specify it, only the named rule is reloaded. If you do not specify this argument, all custom diagnostic rules are reloaded. The file containing the custom diagnostic rule must be located in one of the following directories: DOMAIN_HOME/config/fmwconfig/dfw DOMAIN_HOME/config/fmwconfig/servers/server_name/dfw
`server`	The name of the server to which to reload the rules. This argument is optional. If you do not specify it, the rules are reloaded to all servers. This option is only valid when you are connected to the Administration Server.

name

The name of a custom diagnostic rule. This argument is optional. If you specify it, only the named rule is reloaded. If you do not specify this argument, all custom diagnostic rules are reloaded.

The file containing the custom diagnostic rule must be located in one of the following directories:

DOMAIN_HOME/config/fmwconfig/dfw
DOMAIN_HOME/config/fmwconfig/servers/server_name/dfw

server

The name of the server to which to reload the rules. This argument is optional. If you do not specify it, the rules are reloaded to all servers.

This option is only valid when you are connected to the Administration Server.

Example

The following example reloads the custom diagnostic rule myCustomRules.xml:

reloadCustomRules(name='myCustomRules.xml')

Parent topic: Incident Commands

showIncident

This command shows the details of a specified incident.

Command Category: Incidents

Use with WLST: Online

Description

Shows the details of the specified incident.

Syntax

showIncident(id, [adrHome][, server])

Argument Definition

Argument	Definition
`id`	The ID of the incident that you want to view.
`adrHome`	The path for the ADR Home from which to query the incident. If this argument is not specified, the default ADR Home is queried. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

id

The ID of the incident that you want to view.

adrHome

The path for the ADR Home from which to query the incident. If this argument is not specified, the default ADR Home is queried.

The default ADR Home is the following location:

ADR_BASE/diag/OFM/domain_name/server_name

server

The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example displays information about the incident with the ID 10:

showIncident(id="10")
Incident Id: 10
Problem Id: 10
Problem Key: MDS-50500 [MANUAL]
Incident Time:Tue May 23 11:02:22 PDT 2017
Error Message Id: MDS-50500
Execution Context:
Flood Controlled: false
Dump Files :
   readme.txt
   jvm_threads10_i1.txt
   dms_metrics11_i1.txt
   dfw_samplingArchive13_i1.JVMThreadDump.txt
   dfw_samplingArchive13_i1.readme.txt
   odl_logs14_i1.txt
   dms_metrics20_i1.txt

Parent topic: Incident Commands

Diagnostic Dump Commands

A diagnostic dump captures and dumps specific diagnostic information when an incident is created (automatic) or on the request of an administrator (manual). The WLST diagnostic dump commands let you view and execute dumps.

Use the commands in the following sections to display information about dumps and to execute dumps.

describeDump
This command is used to display a description of the specified diagnostic dump.
executeDump
This command is used to execute the specified diagnostic dump.
listDumps
This command is used to display the set of diagnostic dumps that can be executed.

Parent topic: Diagnostic Framework Custom WLST Commands

describeDump

This command is used to display a description of the specified diagnostic dump.

Command Category: Diagnostic Dump

Use with WLST: Online

Description

Displays a description of the specified diagnostic dump.

Syntax

describeDump(name [,appName] [.server])

Argument Definition

Argument	Definition
`name`	The name of the dump for which to display information.
`appName`	The name of the deployed application for which information is gathered. For example, if you have multiple ADF applications deployed, each may register a dump called adf.dump. To execute this command for a specific application, you must specify the application name.
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

name

The name of the dump for which to display information.

appName

The name of the deployed application for which information is gathered.

For example, if you have multiple ADF applications deployed, each may register a dump called adf.dump. To execute this command for a specific application, you must specify the application name.

server

The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example displays information about the dump with the name odl.logs. You use the listDumps command to retrieve the list of available dumps.

describeDump(name="odl.logs")
Name: odl.logs
Description: Dump contents of diagnostic logs
Run Mode: asynchronous
Mandatory Arguments: 
Optional Arguments:
    Name        Type     Description
    match_all   BOOLEAN  Whether to match both ECID and time range or any one of them.
    timestamp   LONG     Log message timestamp in milliseconds
    ecid        STRING   Log message execution context ID (ecid)
    exclude_access_logs BOOLEAN  Excludes access logs from dump.
    timerange   LONG     Time range in minutes

Parent topic: Diagnostic Dump Commands

executeDump

This command is used to execute the specified diagnostic dump.

Command Category: Diagnostic Dump

Use with WLST: Online

Description

Executes the specified diagnostic dump.

Syntax

executeDump(name [,args] [,outputFile] [,id] [,adrHome] [,server])

Argument	Definition
`name`	The name of the diagnostic dump to execute.
`args`	Mandatory or optional arguments to pass to the dump.
`outputFile`	The name of the file to which to write the dump. If you do not specify this argument, the output is written to the console.
`id`	The ID of the incident to which to associate the dump. By default, the specified dump is not associated with an incident.
`adrHome`	The ADR home that contains the incident. If you do not specify this argument, the default ADR home is used. The default ADR Home is the following location: ADR_BASE/diag/OFM/domain_name/server_name
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Arguments that are either required or are optional can be specified using the "args" keyword. For example:

executeDump("java.sysprops",args={"prop" : "os.name"})

Examples

The following example executes the dump with the name jvm.threads and writes it to the file dumpout.txt:

executeDump(name="jvm.threads", outputFile="/tmp/dumpout.txt")
Diagnostic dump jvm.threads output written to /tmp/dumpoutput.txt

The following example executes the dump with the name jvm.threads and the Incident ID for 33 and writes it to the file dumpout.txt:

executeDump(name="jvm.threads", outputFile="/tmp/dumpout.txt", id="33")
Diagnostic dump jvm.threads output associated with incident 33 in ADR Home diag/ofm/base_domain/AdminServer

The following example executes a dump with the argument prop set to the value os.name:

executeDump(name="java.sysprops",args={"prop" : "os.name"})

Parent topic: Diagnostic Dump Commands

listDumps

This command is used to display the set of diagnostic dumps that can be executed.

Command Category: Diagnostic Dump

Use with WLST: Online

Description

Displays the set of diagnostic dumps that can be executed.

Syntax

listDumps([appName] [,server])

Argument Definition

Argument	Definition
`appName`	The name of a deployed application for which diagnostics are being gathered. For example, if you have multiple ADF applications deployed, each may register a dump called adf.dump. To execute this command for a specific application, you must specify the application name. If you specify this argument, the command returns the dumps for the specified application. If you do not specify this argument, the command returns the system dumps.
`server`	The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

appName

The name of a deployed application for which diagnostics are being gathered.

For example, if you have multiple ADF applications deployed, each may register a dump called adf.dump. To execute this command for a specific application, you must specify the application name.

If you specify this argument, the command returns the dumps for the specified application. If you do not specify this argument, the command returns the system dumps.

server

The name of the Managed Server from which to collect information. This argument is valid only when you are connected to the Administration Server.

Example

The following example lists all of the available dumps.

listDumps()
adf.DiagnosticsJarsVersionDump
dfw.samplingArchive
dms.configuration
dms.ecidctx
dms.metrics
http.requests
jvm.classhistogram
jvm.threads
mds.MDSInstancesDump
odl.activeLogConfig
odl.logs
odl.quicktrace
opss.diagTest
opss.identityStoreUserRoleApiConfig
opss.securityContext
wls.image
 
Use the command describeDump(name=<dumpName>) for help on a specific dump.

Parent topic: Diagnostic Dump Commands

Dump Sampling Commands

Diagnostic dump sampling captures the output of diagnostic dumps at specified intervals. The WLST diagnostic dump sampling commands let you manage dump samplings.

Use the commands in the following sections to capture samples of diagnostic dumps at specified intervals.

addDumpSample
This command is used to create samplings for Diagnostic Framework dumps.
enableDumpSampling
This command is used to enable or disables all dump samplings.
getSamplingArchives
This command is used to collect all dump samplings in a zip file containing the individual sampling files and a readme file.
isDumpSamplingEnabled
This command lists whether dump sampling is enabled or disabled.
listDumpSamples
This command lists all dump samplings, a specified dump sampling, or all dump samplings associated with a specified server.
removeDumpSample
This command is used to remove the specified dump sampling.
updateDumpSample
This command is used to update the specified dump sampling, modifying the settings of the sampling.

Parent topic: Diagnostic Framework Custom WLST Commands

addDumpSample

This command is used to create samplings for Diagnostic Framework dumps.

Command Category: Dump Sampling

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 is 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

Parent topic: Dump Sampling Commands

enableDumpSampling

This command is used to enable or disables all dump samplings.

Command Category: Dump Sampling

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

Parent topic: Dump Sampling Commands

getSamplingArchives

This command is used to collect all dump samplings in a zip file containing the individual sampling files and a readme file.

Command Category: Dump Sampling

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 are 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-17 07:25   dfw_samplingArchive1065570966467923683.JVMThreadDump.dmp
      840  05-21-17 07:25   dfw_samplingArchive7749640004639161119.readme.txt
 --------                   -------
   509620                   2 files

Parent topic: Dump Sampling Commands

isDumpSamplingEnabled

This command lists whether dump sampling is enabled or disabled.

Command Category: Dump Sampling

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

Parent topic: Dump Sampling Commands

listDumpSamples

This command lists all dump samplings, a specified dump sampling, or all dump samplings associated with a specified server.

Command Category: Dump Sampling

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 argument, 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    :

Parent topic: Dump Sampling Commands

removeDumpSample

This command is used to remove the specified dump sampling.

Command Category: Dump Sampling

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

Parent topic: Dump Sampling Commands

updateDumpSample

This command is used to update the specified dump sampling, modifying the settings of the sampling.

Command Category: Dump Sampling

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 effect 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 is 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

Parent topic: Dump Sampling Commands