6.3 DMS Parameter-Scoped Metrics Rules Commands

Parameter-scoped metrics commands enable you to create a metric, specifying a constraint and rules that associate sets of noun-types with sets of parameter names.

Use the commands in Table 6-4 to manage parameter-scoped metrics.

Table 6-4 DMS Parameter-Scoped Metrics Rules Commands

Use this command...	To...	Use with WLST...
createDMSScopedMetricsParameterConstraint	Create a parameter constraint that can be used in the setParameterScopedMetricsRule command.	Online
deleteDMSParameterScopedMetricsRules	Delete the specified parameter-scoped metric rules.	Online
dumpParameterScopedMetrics	Display the parameter-scoped metric data for the specified rule id.	Online
listDMSContextParameters	List the set of execution context parameters known to DMS.	Online
listDMSParameterScopedMetricsRules	Display the current parameter-scoped metrics configuration.	Online
resetDMSParameterScopedMetrics	Reset the parameter-scoped metric data associated with the given rule identifiers.	Online
sampleDMSContextParameterValues	Collect a sample of the set of values for the named context parameter.	Online
setDMSParameterScopedMetricsRule	Create or update a parameter-scoped metric rule.	Online

6.3.1 createDMSScopedMetricsParameterConstraint

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Creates a constraint that can be used with the setParameterScopedMetricsRule command.

Syntax

createDMSScopedMetricsParameterConstraint(name [, values] [,maxnumofvalues])

Argument	Definition
name	The name of the parameter to which the constraint refers.
values	Optional. A list of specific values to be applied by the constraint.
maxmumofvalues	Optional. The maximum number of values that the constraint will use. If omitted, and relevant, a value of 10 is assumed. This value is ignored if the values option is provided.

Example

The following example creates the parameter constraint name URI. It applies the values MyApp/advSearch.jspx and MyApp/basicSearch.jspx.

createDMSScopedMetricsParameterConstraint(  name="URI", values=["MyApp/advSearch.jspx", "MyApp/basicSearch.jspx"])

6.3.2 deleteDMSParameterScopedMetricsRules

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Deletes the specified parameter-scoped metric rule and its accumulated data.

Syntax

deleteDMSParameterScopedMetricsRules([server,] ids)

Argument	Definition
server	Optional. Specifies the server from which to delete the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')
ids	The list of identifiers of the rules to be deleted. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example: ids=["id1", "id2"

Argument

Definition

server

Optional. Specifies the server from which to delete the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')

ids

The list of identifiers of the rules to be deleted. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example:

ids=["id1", "id2"

Example

The following example deletes the parameter-scoped metric rules for the Managed Server wls_server1 and with the id of rule1:

deleteDMSParameterScopedMetricsRules(server='wls_server1', rule1)

6.3.3 dumpParameterScopedMetrics

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Displays the parameter-scoped metric data for the specified rule id.

Syntax

dumpParameterScopedMetrics([server,] ruleid)

Argument	Definition
server	Optional. Specifies the server for which to dump the parameter-scoped metric data. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')
ruleid	The id of the parameter-scoped metric rule for which data is to be displayed

Argument

Definition

server

Optional. Specifies the server for which to dump the parameter-scoped metric data. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')

ruleid

The id of the parameter-scoped metric rule for which data is to be displayed

Example

The following example displays data for the parameter-scoped metric rule regionRule for the Managed Server wls_server1:

dumpParameterScopedMetrics(server="wls_server1", ruleid="regionRule")

6.3.4 listDMSContextParameters

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Lists the set of execution context parameters known to DMS.

Syntax

listDMSContextParameters([server][, parameternames] [, verbose])

Argument Definition

Argument	Definition
server	Optional. Specifies the server for which to display the execution context parameters. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')
parameternames	Optional. A list of names of execution context parameters of interest. Any parameter name not found on the server will be ignored (no error will be reported). If this argument is not used, all execution context parameters will be listed.
verbose	Optional. If `true`, then for each execution context parameter the output will include, where available, the description of the execution context parameter along with its set of possible values and their descriptions.

server

Optional. Specifies the server for which to display the execution context parameters. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')

parameternames

Optional. A list of names of execution context parameters of interest. Any parameter name not found on the server will be ignored (no error will be reported). If this argument is not used, all execution context parameters will be listed.

verbose

Optional. If true, then for each execution context parameter the output will include, where available, the description of the execution context parameter along with its set of possible values and their descriptions.

Example

The following example shows the parameter-scoped metric rules for the Managed Server wls_server1:

listDMSContextParameters(server='wls_server1')
Server: ManagedServer1
 
    Module
    FlowId
    Action
    RCID

6.3.5 listDMSParameterScopedMetricsRules

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Displays the current parameter-scoped metric configuration.

Syntax

listDMSParameterScopedMetricsRules([server])

Argument	Definition
server	Optional. Specifies the server for which to display the parameter-scoped metric configuration. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')

Argument

Definition

server

Optional. Specifies the server for which to display the parameter-scoped metric configuration. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')

Example

The following example shows the parameter-scoped metric rules for the Managed Server wls_server1:

listDMSParameterScopedMetricsRules(server='wls_server1')

  Rule: ruleA 
   Noun types: 
      JDBC_Connection 
   Context Parameter Constraints: 
      Parameter: URI 
        Constraining values: 
          MyApp/advSearch.jspx 
          MyApp/basicSearch.jspx

6.3.6 resetDMSParameterScopedMetrics

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Resets the parameter-scoped metric data associated with the given rule identifiers. The operation is not guaranteed to be atomic, that is, metric data will continue to be gathered while the reset operation is in progress.

Syntax

resetDMSParameterScopedMetrics([server,] ids)

Argument	Definition
server	Optional. Specifies the server for which to reset the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')
ids	The list of identifiers of the rules to be reset. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example: ids=["id1", "id2"

Argument

Definition

server

Optional. Specifies the server for which to reset the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')

ids

The list of identifiers of the rules to be reset. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example:

ids=["id1", "id2"

Example

The following example resets the rule with the id ruleA for the managed server wls_server1:

resetDMSParameterScopedMetrics(server="wls_server1", ids="ruleA")

6.3.7 sampleDMSContextParameterValues

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Collects a sample of the set of values for the named context parameter.

Syntax

sampleDMSContextParameterValues([parametername] [, naxmuofvaleus] [,action])

Argument Definition

Argument	Definition
parametername	Optional. The name of the context parameter to be sampled. This argument must be used in combination with the argument `action`.
manmumofvalues	Optional. The maximum number of distinct values to include in the sample. If omitted, a value of 10 is applied. A value of 0 will cause all distinct values to be sampled. Depending on the context parameter, this could mean sampling a set of unbounded size. Only relevant when specifying the action="start".
action	Optional. The action to be sampled. This argument must be used in combination with the argument `parametername`. The valid values are: start: Start sampling values stop: Stop sampling values and show the values show: Display the histogram of sampled values.

parametername

Optional. The name of the context parameter to be sampled. This argument must be used in combination with the argument action.

manmumofvalues

Optional. The maximum number of distinct values to include in the sample. If omitted, a value of 10 is applied. A value of 0 will cause all distinct values to be sampled. Depending on the context parameter, this could mean sampling a set of unbounded size. Only relevant when specifying the action="start".

action

Optional. The action to be sampled. This argument must be used in combination with the argument parametername.

The valid values are:

start: Start sampling values
stop: Stop sampling values and show the values
show: Display the histogram of sampled values.

Examples

The following example starts sampling the values for the parameter bespoke.ServiceLevel:

sampleDMSContextParameterValues(parametername="bespoke.ServiceLevel", maxnumofvalues=5, action="start")
Values of the parameter bespoke.ServiceLevel are now being sampled.
 List of parameters currently being sampled:
    bespoke.ServiceLevel has been sampled for 0 seconds.

The following example stops the sampling and displays the histogram of the values:

sampleDMSContextParameterValues()
  List of parameters currently being sampled:    bespoke.ServiceLevel has been sampled for 87 seconds.
sampleDMSContextParameterValues(parametername="bespoke.ServiceLevel", action="stop")
  Histogram of values for parameter bespoke.ServiceLevel.
    Gold 21
    Silver 5
    Bronze 37
  Values of the parameter bespoke.ServiceLevel will no longer be sampled.

6.3.8 setDMSParameterScopedMetricsRule

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Creates or updates a parameter-scoped metric rule. Only one rule at a time can manage the collection of metrics for a particular noun type and parameter combination. For example, you cannot have two separate rules to attempt to collect parameter-scoped metrics based on the context parameter URI and the noun type JDBC_Connection.

Syntax

setDMSParameterScopedMetricsRule([server,] id, nountypes [, ctxparamconstraints][, actparamconstraints] [,replace={true|false}])

Argument	Definition
server	Optional. Specifies the server for which to set the parameter-scoped metric rule. Valid values are a list of WebLogic Server instance names and system component names. To specify the server, use the following syntax: server='servername' If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components. You must be connected to the Administration Server to use this argument. For system components, such as Oracle HTTP Server, use the following format: servers=['component_name], servertype='component_type')
id	The identifier of the rule.
nountypes	The list of noun types to which the rule applies.
ctxparamconstraints	Optional. The list of context parameter constraints to be used by this rule. You must specify at least one of this argument or actparamconstraints. See "createDMSScopedMetricsParameterConstraint".
actparamconstraints	Optional. The list of activation parameter constraints to be used by the rule. You must specify at least one of this argument or ctxparamconstraints. See "createDMSScopedMetricsParameterConstraint".
replace	Optional. If `true`, the new rule replaces an existing rule of the same id. If `false` or if left unset, and a rule with the id already exists an error is raised.

Example

The following example creates the rule with the id ruleA, the nountype JDBC_Connection and the context parameter constraint ctxP1:

setDMSParameterScopedMetricsRule(id="ruleA", nountypes=["JDBC_Connection"],  ctxparamconstraints=[ctxP1])