IBM Integration Bus, Version 10.0.0.9 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS


mqsichangebluemixreporting command

Start of changeUse the mqsichangebluemixreporting command to configure integration servers to connect to Bluemix™ services in the IBM® Cloud, and to send data about the integration servers to those Bluemix services. You can configure integration servers to send startup and usage information to the IBM Cloud Product Insights service, to send logging, statistics, and accounting data to the Logmet service, or to send information to both services.End of change

Supported platforms

Purpose

IBM Cloud Product Insights is a Bluemix service that is part of IBM Connect to Cloud. Ensure that your version and fix pack level of IBM Integration Bus is compatible with the level of the Product Insights service before you enable IBM Integration Bus to connect to it.

Start of changeYou can use the mqsichangebluemixreporting command to configure a connection to the Product Insights Bluemix service and send it startup and usage information, either for a specified integration server or for all integration servers on a specified integration node. Optionally, you can configure the connection via a specified HTTP proxy server. You can then use a dashboard in Bluemix to view the usage information for your integration servers, including the CPU time, resident set size, and the number of active CPUs. End of change

Start of changeYou can also use the mqsichangebluemixreporting command to configure a connection to the Logmet service in Bluemix and send it logging, statistics, and accounting data, either for a specific integration server or for all integration servers on a specified integration node. You can then use a Kibana dashboard to view the reported data for all your integration servers across multiple integration nodes. The Logmet service can also receive logging events from other products such as IBM MQ, WebSphere® Liberty, and IBM Business Process Manager, which means that you can create single queries that include events from multiple products and view the results in one place. End of change

You run the mqsichangebluemixreporting command from the host machine that is running your integration node (typically on-premise) to activate the reporting feature, and the Bluemix service in the cloud receives notifications at the specified times. The Product Insights Bluemix service is notified each time an integration server starts, and the Logmet service receives data about the integration server at specified intervals.

The startup notification that is sent to the Product Insights service contains the following information:
  • IBM Integration Bus product ID, defined in the IBM License Metric Tool (ILMT)
  • IBM Integration Bus instance identifier, which is composed of the following information:
    • IBM Integration Bus installation root directory (for example, C:/Program Files/IBM/IIB/10.0.0.7/)
    • Host name
    • Group name
    • IBM Integration Bus integration node name
    • IBM Integration Bus integration server name
  • IBM Integration Bus product version
  • IBM Integration Bus installation root directory (for example, C:/Program Files/IBM/IIB/10.0.0.7/)
  • Host name
  • Host operating system name
  • Host operating system version
  • All APARs that have been applied
  • The URL of the IBM Integration Bus web user interface for this integration server.
The usage data that is sent to the Product Insights service contains the following information:
  • The CPU time used by the whole integration server process in the interval
  • The number of active CPUs available to the integration server process at the start of the interval.
    Note: For integration servers on z/OS, this value is not applicable and is set to 1.
  • The resident set size in kilobytes. This value is a measure of the physical memory used by the integration server, and is displayed only for those operating systems that provide it, such as Linux and Windows.

If you activate the logging capability (by specifying the -l parameter), BIP messages that are triggered by integration server events are sent to the Logmet service in IBM Bluemix. The logging data that is sent contains information about the events that are issued by the integration server process; events that are initiated by other components are not reported. If you compare the contents of the local event log with the contents of the log in the Kibana dashboard, you will see that a very small number of messages at the beginning and end of the local log are not shown in the dashboard; these are typically messages about the start and end of the message logging process.

Start of changeIf you have configured the integration server to send statistics and accounting data to Logmet, by specifying -o bluemix on the mqsichangeflowstats command, those statistics are also displayed on the Kibana dashboard. For more information, see Reporting logging, statistics, and accounting data to a Logmet service in IBM Bluemix and displaying it in a Kibana dashboard.End of change

The logging data that is sent to Logmet includes BIP messages with the following content:
@timestamp
ISO8601 date timestamp reported to Logmet
ALCH_TENANT_ID
Bluemix logging service tenant identifier
_type
The type of event, set to iib_message
host
Host name of the server that was the source of the event
loglevel
Severity indicator mapped to an equivalent Bluemix logging level name:
  • BIPnnnnE - ERROR
  • BIPnnnnW - WARNING
  • BIPnnnnI - INFO
module
"integration node name"."integration server name"
message
Full message text, starting with the message ID
ibm_sequence
Sequence number of the event, which is used to distinguish events with the same @timestamp
ibm_messageId
Message ID - IBM Integration Bus BIP number
ibm_serverName
Name of the integration server
ibm_threadId
Thread ID (text name)
ibm_processId
Process ID

You can override the host name that the integration server reports to the Product Insights service, by setting the MQSI_BLUEMIXREPORTING_HOSTNAME environment variable. This can be useful if you are running the integration server in a container.

You can run the mqsichangebluemixreporting command multiple times. Each time you run the command, only the values set by the specified parameters are updated; any other previously set values remain unchanged. For example, if you run the command once and specify only the name of the integration node and the -j (apiHost) and -k (apiKey) parameters, the configuration applies to all integration servers owned by the integration node, and the reporting state for startup and usage (which is set by the -c parameter) is set to inactive by default. You can then run the command again at a later date, setting the -c parameter to active, and all other previously set parameter values are then used for reporting the startup and usage information to the Product Insights Bluemix service.

Alternatively, you might want to run the mqsichangebluemixreporting command once to configure your integration servers to send startup and usage information to the Product Insights service, and then run the command again to configure the integration servers to send logging information to the Logmet service. Any configuration that was set when you ran the command previously is retained unless you specify a new value for a parameter that was set previously.

The changes that are made by the mqsichangebluemixreporting command become effective the next time the integration server starts, so you must either stop and restart the integration node by using the mqsistop and mqsistart commands, or reload the integration server by running the mqsireload command.

Syntax

Read syntax diagramSkip visual syntax diagram
>>-mqsichangebluemixreporting--integrationNodeName-------------->

>--+-----------------------------+------------------------------>
   +- -e --integrationServerName-+   
   '- -g ------------------------'   

>--+-------------------------+--+---------------+--------------->
   '- -c --startupUsageState-'  '- -j --apiHost-'   

>--+--------------+--+-----------------+------------------------>
   '- -k --apiKey-'  '- -y --httpProxy-'   

>--+------------------+--+-----------------+-------------------->
   '- -m --intMinutes-'  '- -n --groupName-'   

>--+--------------------+--+--------------+--------------------->
   '- -l --loggingState-'  '- -r --region-'   

>--+--------------------+--+-------------+---------------------->
   '- -o --organization-'  '- -a --space-'   

>--+----------------+--+----------------+----------------------->
   '- -u --username-'  '- -p --password-'   

>--+------------------+--+----------------+--------------------->
   '- -s --intSeconds-'  '- -d --tenantId-'   

>--+----------------+--+-----------------------+---------------->
   '- -x --hostname-'  '- -i --spaceIdentifier-'   

>--+--------------------+--------------------------------------><
   '- -t --loggingToken-'   

Parameters

Integration node:

integrationNodeName
(Required) The name of the integration node.
-e integrationServerName
Start of change(Optional) Specifies a single integration server for which startup, usage, and logging information, and statistics and accounting data, will be reported. If you specify this parameter, you cannot specify the -g parameter. If neither the -e nor -g property is specified, the configuration is set as a default for all integration servers in the integration node, and is applied only to integration servers that have never been configured using the -e or -g flags.End of change
-g
Start of change(Optional) Specifies that startup, usage, and logging information, and statistics and accounting data, will be reported for all integration servers on the specified integration node. If you specify this parameter, you cannot specify an integration server name by using the -e parameter. If neither the -e nor -g property is specified, the configuration is set as a default for all integration servers in the integration node, and is applied only to integration servers that have never been configured using the -e or -g flags.End of change

Startup and usage reporting:

-c startupUsageState
(Optional) Enables or disables the reporting of startup and usage information for the integration server to the Product Insights service. Valid values are active or inactive. When this parameter is set to active, IBM Integration Bus attempts to connect to the Product Insights service, and reports the startup and usage information for the specified integration server (or for all integration servers).

If this parameter is set to active, valid values must also be specified (or must have been specified previously) for the -j and -k parameters.

The reporting state is inactive by default.

-j apiHost
(Optional) Specifies the URL of the API host to be used for reporting startup and usage information. The API host for your region (where your data will be sent) is specified in your service credentials for the Product Insights service. To find the value that you need to specify for the -j, check the API host information that is specified in the credentials for your service instance. For more information about how to check your service credentials, see Configuring the IBM Cloud Product Insights service.

A value for this parameter must be specified (or must have been specified previously) if the -c parameter is set to active.

-k apiKey
(Optional) Specifies the API key for the startup and usage service. The API key is specified in your service credentials for the Product Insights service. To find the value that you need to specify for the -k parameter, check the API key information that is specified in the credentials for your service instance. For more information about how to check your service credentials, see Configuring the IBM Cloud Product Insights service.

A value for this parameter must be specified (or must have been specified previously) if the -c parameter is set to active.

Start of change-y httpProxyEnd of change
Start of change(Optional) Specifies the address of a proxy server, in the form hostname:port. Use this option to enable your integration servers to connect to the Product Insights service through an HTTP proxy server. You can remove the setting for a previously specified proxy server by setting the -y parameter to "". For more information, see Configuring a connection to IBM Cloud Product Insights through an HTTP proxy server.End of change
-n groupName
(Optional) Specifies a group name for the integration server. When details of integration servers are viewed in the Product Insights service, they are grouped together according to the name that is specified by this parameter. If this parameter is specified, integration servers are grouped according to the group name and then by integration node within the group. If this parameter is not specified, integration servers are grouped by integration node only.
-m intMinutes
(Optional) Specifies the reporting interval for the usage service, in minutes. The default value is 15.

Start of changeLogging, statistics, and accounting services:End of change

Start of change
-l loggingState
(Optional) Enables or disables the reporting of logging, statistics, and accounting data for the integration server to the Logmet service. Valid values are active or inactive.

If this parameter is set to active, valid values must also be specified (or must have been specified previously) for the -x (hostname:portnumber) and -a (space) parameters.

The logging state is inactive by default.

-r region
(Optional) Specifies the Bluemix region for logging, statistics, and accounting services. You can use the -r parameter to specify a Bluemix API endpoint, such as https://api.ng.bluemix.net for the us-south region, or https://api.eu-gb.bluemix.net for the eu-gb region. Alternatively, you can use the region names us-south or eu-gb. If you specify a Bluemix API endpoint, the Logmet host and port are obtained dynamically from a Bluemix service, rather than being set with a static value. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
-o organization
(Optional) Specifies the Bluemix organization for logging, statistics, and accounting services. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
-a space
(Optional) Specifies the Bluemix space for logging, statistics, and accounting services. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
-u username
(Optional) Sets the Bluemix user name for logging, statistics, and accounting services. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
-p password
(Optional) Specifies the Bluemix password for the logging, statistics, and accounting services. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
-s intSeconds
(Optional) Specifies the interval, in seconds, for sending information to the logging, statistics, and accounting service. The minimum value is 1, the maximum value is 300, and the default value is 60.
Note: If the integration server is raising an exceptionally high rate of BIP message events, the integration server will send data more often than the configured interval.
-d
(Optional) Publishes the current Kibana dashboard for Bluemix logging, statistics, and accounting services. For more information, see Configuring an integration server to send logging, statistics, and accounting data to a Kibana dashboard in IBM Bluemix.
End of change

Logging, statistics, and accounting services (manual configuration):

Start of change
-x logmetHost
(Optional) Specifies the host name and, optionally, the port number for logging, statistics, and accounting services, in the form hostname:portnumber. For more information, see Configuring an integration server and loading the IBM Integration Bus Kibana dashboard manually.
-i spaceIdentifier
(Optional) Specifies the Bluemix space identifier for logging, statistics, and accounting services. For more information, see Configuring an integration server and loading the IBM Integration Bus Kibana dashboard manually.
-t loggingToken
(Optional) Specifies the Bluemix logging token for logging, statistics, and accounting services. For more information, see Configuring an integration server and loading the IBM Integration Bus Kibana dashboard manually.
End of change

Responses

In addition to standard command responses, the following responses are returned by this command.
  • BIP8372: The mqsichangebluemixreporting command changes the Bluemix reporting state and configuration.
  • BIP6500: The integration server could not complete Bluemix reporting setup.
  • BIP6501: The integration server failed to perform Bluemix reporting.
  • BIP6502: The integration server failed to post a Bluemix reporting event.
  • BIP6503: The integration server posted a Bluemix reporting event and received an unexpected response code.
  • BIP8377I: The mqsichangebluemixreporting command has prepared the IBM Integration Bus Kibana dashboard. This message includes the location of the prepared Kibana json files for possible manual import into the IBM Bluemix logging service.

Authorization

For information about platform-specific authorizations, see the following topics: If you have enabled integration node administration security, you must also set up the authority that is detailed in Tasks and authorizations for administration security.

Examples

Always enter the command on a single line; in some examples, line breaks have been added to enhance readability.

In the following example, the Product Insights reporting function is enabled for a specified integration server called myIntegrationServer3.
mqsichangebluemixreporting myIntegrationNode1 -e myIntegrationServer3 -c active 
-n Test -j https://productinsights-api.ng.bluemix.net -m 15 
-k ab232e28-6aed-4365-8996-7457d176b0c7

As an alternative to specifying a particular integration server (by using the -e parameter), you can set the -g parameter to enable reporting for all integration servers on the specified integration node.

The -j parameter specifies the API host for your region (where your data will be sent), as specified in your service credentials. To find your API host, check the information that is specified in the credentials for your service instance, as described in Configuring the IBM Cloud Product Insights service.

The -k parameter specifies the API key, which you can also obtain by following the instructions in Configuring the IBM Cloud Product Insights service.

Start of changeThe following example sets the startup and usage reporting service for all integration servers to active, and specifies that the startup and usage information will be sent via the proxy server that is specified by the -y parameter (https:mygateway.co.uk):
mqsichangebluemixreporting TESTNODE -g -c active -j https://hybridconnect-api.ng.bluemix.net
-k 9ec5g5c2-c5m1-3287-b2xd-c371fc22d467 -y https:mygateway.co.uk
You can remove the setting for a previously specified proxy server by setting the -y parameter to "". For example:
mqsichangebluemixreporting TESTNODE -g -c active -j https://hybridconnect-api.ng.bluemix.net
-k 9ec5g5c2-c5m1-3287-b2xd-c371fc22d467 -y ""
End of change
The following example enables the reporting of logging information for all integration servers to the us-south region IBM Bluemix Logmet service, and deploys the IBM Integration Bus Kibana dashboard into the dev Bluemix space:
mqsichangebluemixreporting myIntegrationNode1 -g -l active -r https://api.ng.bluemix.net 
-o a.user@comp.com -a dev -u a.user@comp.com -p password123 -d

bz91100_.htm | Last updated 2017-07-17 12:46:56