mqsichangeflowstats command - Windows, Linux, and AIX systems

Some parameters have alternative long names; for example, -p and --admin-port are alternative parameter names of the administration REST API. The long names available are listed in the Parameters section.

You must specify at least one parameter to identify the target integration node or independent integration server for this command, in one of the following forms:

integrationNodeName

This parameter identifies the name of a specific integration node. To connect to a remote integration node by name, you must also specify -i and (optionally) -p.

-d integrationNodeFileName | --integration-node-file integrationNodeFileName

This parameter identifies the name of a .broker file that contains the connection details for an integration node or independent integration server. Include the location (path) and file name when you specify this parameter. You must ensure that the location is accessible when you run this command.

The file can be used to connect to an independent integration server if the connection details do not include a node name (integrationNodeName) and the host and port are for an independent integration server.

Use this option if multiple users want to connect to the same integration node or integration server, or if you are using advanced connection parameters such as SSL. For more information about creating and using a .broker file, see Connecting to an integration node by creating a .broker file.

If you want to run a command that uses SSL to administer a remote integration node or integration server over a secured channel, you must specify the keystore and truststore password for the connection that is using the IBM_JAVA_OPTIONS environment variable. For more information, see Resolving problems when running commands.

-i ipAddress, -p port | --admin-host ipAddress, --admin-port port

These parameters identify a host and port for an integration node or independent integration server, for connections that do not require advanced connection parameters.

To connect to a specific remote integration node by name, you can add the prefix integrationNodeName. You cannot use -d integrationNodeFileName in the same command.

For an integration node, any parameters that you omit assume default values.

• -i ipAddress: The hostname or IP address of the computer on which the integration node or server is running. If you do not specify this parameter, a value that represents the local computer is used.

  To connect to an independent integration server, the value is the host that you specified in the adminRestApiHost property in the server.conf.yaml configuration file for the integration server.

  If you want to connect to a secured integration node or server as a specific user, provide the security credentials as a URI in the following format: tcp://user:password@hostname. If your password contains URI Reserved characters, you must convert these characters to the percent-encoded format. For more information, see A correct URL and password returns error BIP1939 when you attempt to connect to a remote host name in Resolving problems when running commands.

• -p port: The port on which the web user interface HTTP connection listener is listening. If you do not specify this parameter, the value 4414 is used.

  To connect to an independent integration server, the value is the port that you set for the adminRestApiPort property in the server.conf.yaml configuration file; by default the value is set to 7600.

Other parameters:

-a | --archive

(Required) Specify that the command modifies archive accounting and statistics collection.

You must specify either -a or -s. If you do not specify one of these arguments you receive a warning message.

-b | --accounting-origin AccountingOrigin

(Optional) Specifies that the environment tree path Broker.Accounting.Origin is used to partition the collected statistics into distinct outputs. Possible values are:

• none - do not partition statistics according to accounting origin data
• basic - partition statistics according to accounting origin data

-c | --control Control

(Optional) Specify the string value that controls the level of the action to be applied to accounting and statistics collection for snapshot or archiving. Possible values are:

• active - turn on snapshot or archiving
• inactive - turn off snapshot or archiving.
• inherit - set status of snapshot or archiving to inherit.

-e | --integration-server integrationServerName

(Optional) This parameter is required only when connecting to an integration node. Specify the name for the integration server, for which accounting and statistics options are to be changed. Alternatively, specify --all-integration-servers to change accounting and statistics options for all integration servers.

-f | --flow MessageFlow

(Optional) Specify the label for the message flow, for which accounting and statistics options are to be changed. Alternatively, specify --all-flows to change accounting and statistics options for all message flows. When setting the -f parameter, you must also set a value for -k and optionally -y.

-k | --application applicationName

(Optional) This parameter specifies the name of the application that contains the message flow for which statistics are being collected. Alternatively, specify --all-applications to change accounting and statistics options for all applications.

You can use this parameter with the -y (library name) parameter to specify that the message flow is contained in a library that is referenced by the application.

-n | --node-data-level NodeData

(Optional) Specify a string value to modify the collection of node statistics data for a message flow. Possible values are:

• none - exclude node related data in the statistics
• basic - include node related statistics in the statistics
• advanced - include node related and terminal related data in the statistics

-o | --output-format OutputFormat

(Optional) Specify the output destination for the statistics reports. You can specify multiple output destinations by using comma-separated values. You can specify an output format for snapshot statistics (by using this parameter in combination with the -s | --snapshot parameter), but not for archive statistics (in combination with the -a | --archive parameter). Possible values are:

• usertrace - this is the default and writes "bip" messages to user trace.
• xml - the statistics reports are generated as XML documents and published by the integration node running the message flow.
  The topic on which the data is published has the following structure.

  • For publications on an MQ pub/sub broker:

    $SYS/Broker/integrationNodeName/StatisticsAccounting/recordType
    /integrationServerName/message_flow_name

  • For publications on an MQTT pub/sub broker:

    IBM/IntegrationBus/integrationNodeName/StatisticsAccounting/recordType
    /integrationServerName/message_flow_name

  where recordType is set to Snapshot or Archive, and integration node, integration server, and message flow names are specified according to the subscriber's requirements.
• json - the statistics reports are generated in JSON format, which enables the statistical information to be viewed in the web user interface. If statistics collection is turned on in the web user interface, the output format is changed to json. The topic on which the data is published has the following structure:

  $SYS/Broker/integrationNodeName/Statistics/JSON/SnapShot/isName/applications/MyApplication
  /libraries/MyLibrary/messageflows/MyFlowName

• csv - the statistics are converted to Comma Separated Value (csv) format and are written to a collection of rolling log files. When a file is full, the file writer moves on to the next file, up to a maximum of four files. When the last file is filled, it starts overwriting data in the first file. This cycle of writing continues, ensuring that the newest data is retained.

-r | --reset-archival

(Optional) This parameter applies only to archive data and specifies that archive data is to be reset.

This results in the clearing out of accounting and statistics data accumulated so far for this interval, and restarts collection from this point. All archive data for all flows in the integration server, or groups, is reset.

The archive interval timer is reset only if the -v option (statistics archive interval) of mqsicreatebroker is not zero.

That is, the interval timer is set only if the internal interval notification mechanism is being used, and not an external method.

-s | --snapshot

(Required) Specify that the command modifies snapshot accounting and statistics collection.

You must specify either -a or -s. If you do not specify one of these arguments you receive a warning message.

-t | --thread-data-level ThreadData

(Optional) Specify a string value to modify the collection of thread statistics data for a message flow Possible values are:

• none - exclude thread related data from the statistics
• basic - include thread related data in the statistics

-y | --library libraryName

(Optional) This parameter specifies the name of the library that contains the message flow for which statistics are being collected. Alternatively, specify --all-libraries to change accounting and statistics options for message flows in all libraries.

If you specify the -y parameter, you must also specify the -k (application name) parameter. If you specify the -f (message flow) parameter, you must also specify -k, and optionally -y.

--all-applications

(Optional) This parameter specifies that accounting and statistics options are changed for message flows in all applications.

--all-flows

(Optional) This parameter specifies that accounting and statistics options are changed for all message flows.

--all-integration-servers

(Optional) This parameter specifies that accounting and statistics options are changed for message flows in all integration servers.

--all-libraries

(Optional) This parameter specifies that accounting and statistics options are changed for message flows in all libraries.

--non-persist

(Optional) This parameter specifies that the other settings that are specified by the command do not persist when the integration server is restarted or when the message flow is redeployed. At that point, the settings that are specified in the server.conf.yaml file take effect. By default, this parameter is not set, which means that the settings that you specify with this command persist when the integration server or node is restarted and when the message flow is redeployed.