Skip Headers
Oracle® Fusion Middleware WebLogic Scripting Tool Command Reference
11g Release 1 (10.3.6)

Part Number E13813-13
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

15 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 the Oracle Fusion Middleware Administrator's Guide.

Note:

To use the Diagnostic Framework custom WLST commands, you must invoke the WLST script from the Oracle Common home. See "Using Custom WLST Commands" in the Oracle Fusion Middleware Administrator's Guide.

Table 15-1 lists the different categories of Diagnostic Framework commands.

Table 15-1 Diagnostic Command Categories

Command Category Description

Incident Commands

View problems and incidents and create incidents.

Diagnostic Dump Commands

Display information about dumps and execute dumps.

Dump Sampling Commands

Capture samples of diagnostic dumps at specified intervals.s


Incident Commands

Use the commands in Table 15-2 to view problems and incidents and to create incidents.

Table 15-2 Incident Commands

Use this command... To... Use with WLST...

createIncident

Create a diagnostic incident.

Online

getIncidentFile

Retrieves the contents of the specified incident file.

Online

listADRHomes

List the set of ADR Home paths.

Online

listIncidents

List a set of diagnostic incidents.

Online

listProblems

List a set of diagnostic problems.

Online

reloadCustomRules

Reloads all custom diagnostic rules or the specified rule.

Online, Offline

showIncident

Show the details of a specified incident.

Online


createIncident

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

appNname

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: 55
Problem Id: 4
Problem Key: MDS-50400 [MANUAL]
Incident Time: 25th March 2010 11:55:45 GMT
Error Message Id: MDS-50400
Flood Controlled: false

getIncidentFile

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 will be 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

listADRHomes

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/WLS_Spaces

diag/ofm/fusionapps/GeneralLedger

listIncidents

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
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 will be 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   Problem Key                                 Incident Time
         10   MDS-50300 [WLS_Spaces] [oracle.mds.repos]   Mon Mar 15 11:22:12 PDT 2010
         24   MDS-50300 [WLS_Spaces] [oracle.mds.repos]   Thu Mar 11 15:11:35 PDT 2010

listProblems

Use with WLST: Online

Description

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

Syntax

listProblems([adrHome][,server])
Argument Definition
adrHome

The path for the ADR Home from which to query problems. If this argument is not specified, the default ADR Home will be 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-50300 [WLS_Spaces] [oracle.mds.repos]
         2        JOC-38922 [AdminServer] [oracle.cache.network]

reloadCustomRules

Use with WLST: Online, Offline

Description

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

Syntax

reloadCustomRules([name] [, server])
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.


Example

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

reloadCustomRules(name='myCustomRules.xml')

showIncident

Use with WLST: Online

Description

Shows the details of the specified incident.

Syntax

showIncident(id, [adrHome][, server])
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 will be 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: 1
Problem Key: MDS-50300 [WLS_Spaces] [oracle.mds.repos]
Incident Time: 25th March 2010 10:12:15 GMT
Error Message Id: MDS-50300
Execution Context: 0000ICK4rbYC8xT6uBf9EH1AX1qF000000
Flood Controlled: false
Dump Files :
      dms_ecidctx1_i1.dmp
      jvm_threads2_i1.dmp
      dms_metrics3_i1.dmp
      odl_logs4_i1.dmp
      diagnostic_image_AdminServer_2010_03_25_11_12_15.zip
      readme.txt

Diagnostic Dump Commands

Use the commands in Table 15-3 to display information about dumps and to execute dumps.

Table 15-3 Diagnostic Dump Commands

Use this command... To... Use with WLST...

describeDump

Display a description of the specified diagnostic dump.

Online

executeDump

Execute the specified diagnostic dump.

Online

listDumps

Display the set of diagnostic dumps that can be executed.

Online


describeDump

Use with WLST: Online

Description

Displays a description of the specified diagnostic dump.

Syntax

describeDump(name [,appName] [.server])
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.


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: Dumps recent ODL logs, or logs correlated by ECID
Manadatory Arguments:
Optional Arguments:
   Name       Type      Description
   ECID       String    Execution Context Id to correlate log entries with
   timestamp  String    Timestamp to query logs 5 minutes before/after

executeDump

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 will not be 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"})

listDumps

Use with WLST: Online

Description

Displays the set of diagnostic dumps that can be executed.

Syntax

listDumps([appName] [,server])
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.


Example

The following example lists all of the available dumps.

listDumps()
dms.metrics
jvm.classhistogram
jvm.threads
odl.logs
 
Use the command describeDump(name=<dumpName>) for help on a specific dump.

Dump Sampling Commands

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

Table 15-4 Dump Sampling Commands

Use this command... To... Use with WLST...

addDumpSample

Creates samplings for Diagnostic Framework dumps.

Online

enableDumpSampling

Enables or disables all dump samplings.

Online

getSamplingArchives

Collects all dump samplings in a zip file containing the individual sampling files and a readme file.

Online

isDumpSamplingEnabled

Lists whether dump sampling is enabled or disabled.

Online

listDumpSamples

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

Online

removeDumpSample

Removes the specified dump sampling.

Online

updateDumpSample

Updates the specified dump sampling, modifying the settings of the sampling.

Online


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

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

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

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 soa_server1:

isDumpSamplingEnabled(server="soa_server1")
Location changed to domainRuntime tree. This is a read-only tree with
DomainMBean as the root. 
For more help, use help(domainRuntime)

true

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 soa_server1:

listDumpSamples(server="soa_server1")
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
For more help, use help(domainRuntime)
 
Name              : JavaClassHistogram
Dump Name         : jvm.classhistogram
Application Name  : 
Sampling Interval : 1800
Rotation Count    : 5
Dump Implicitly   : false
Append Samples    : true
Dump Arguments    : 
 
Name              : JVMThreadDump
Dump Name         : jvm.threads
Application Name  : 
Sampling Interval : 60
Rotation Count    : 10
Dump Implicitly   : true
Append Samples    : true
Dump Arguments    : context=true, timing=true

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 soa_server1:

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

Removed HTTPSampling

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="soa_server1")
 
HTTPSampling is updated