[17.0.0.1 and later]

Registering Liberty servers with the Product Insights service on IBM Cloud

By configuring the productInsights-1.0 feature, you can register your on-premises or cloud-based Liberty server to report usage metrics to the IBM® Cloud Product Insights service.

Before you begin

Note:

The IBM Bluemix® Product Insights service is being deprecated. After 21 March 2018, new Product Insights service instances cannot be created. Existing service instances will be removed on the end-of-support date, 13 May 2018. For more information, see Service Deprecation: IBM Cloud Product Insights.

  • Create a IBM Cloud account. To create your account, see Sign up for IBM IBM Cloud.
  • Decide whether to route the reported server data through the Product Insights gateway, which you can learn about and install from IBM Cloud Product Insights on IBM developerWorks®. By routing data through the gateway, you can review the data before it is sent to the Product Insights service.
    Whether you use the gateway impacts how you configure SSL communication to the Product Insights service on IBM Cloud:
    • If you install the gateway, you must use the server certificate from the Product Insights gateway. For information about the certificate, see the IBM Cloud Product Insights documentation on developerWorks.
    • If you do not use the gateway, download the digicert.jks file from IBM Cloud. This file contains a certificate from a well-known certificate authority.

    Place a copy of the keystore file for your chosen configuration in the ${server.config.dir}/resources/security directory of each server that you want to register.

  • In your Liberty installation, install the productInsights-1.0 feature by using the installUtility command. For more information, see Installing assets using the installUtility command.
    Important: If your Liberty installation does not have direct access to the internet, you must configure proxy settings for the installUtility command to install from the online IBM WebSphere® Liberty Repository.

About this task

From a single Product Insights service on IBM Cloud, you can track many Liberty servers that are hosted on-premises, in IBM Cloud, or in other cloud environments. When a Liberty server is registered with a Product Insights service instance, that server connects to the service on IBM Cloud and periodically reports the following usage metrics.
  • Number of active Liberty servers
  • Host location of each server
  • Product edition and version of each server
  • How busy each server is

Only you and other users that you authorize on IBM Cloud can control the Product Insights service instance.

For more information, see IBM Cloud Product Insights on IBM developerWorks.

Procedure

  1. Create an instance of the Product Insights service in the IBM Cloud console.

    Because the service can track many Liberty servers, you need only a single service instance.

    1. In the IBM Cloud Catalog, either search for the Product Insights service, or select the service under Services > Integrate.
    2. On the resulting page, optionally change the default service name, and then click Create.
    3. In your Product Insights service, go to Service Credentials and select View Credentials for one of the shown credentials.

      Make note of the API host and API key of the Product Insights service that you created. This information is added to the Liberty server configuration to register the server with the particular service instance.

  2. In the server.xml configuration file for the Liberty server that you want to register, add the productInsights-1.0 feature.
    <featureManager>
      <feature>productInsights-1.0</feature>
    </featureManager>
  3. In the server configuration, define the keystore and truststore for SSL communication between the Liberty server and the Product Insights service on IBM Cloud.
    <keyStore id="productInsightsKeyStore" location="keystorefile.jks" type="JKS"/>
    <ssl id="productInsightsSSL"
      keyStoreRef="productInsightsKeyStore"
      trustStoreRef="productInsightsKeyStore"
      sslProtocol="TLSv1.2"/>
    • On the keyStore element, specify an ID and reference the keystore file for your configuration, which is either the certificate for the gateway or the digicert.jks file, as described in Before you begin.
    • On the ssl element, specify and ID and reference the IDs of the keyStore element that you defined. For more information about SSL configuration, see SSL configuration attributes.
  4. Configure the Product Insights service on the productInsights element.
    <productInsights url="<apiHost_or_gatewayURL>" apiKey="<apiKey>" sslRef="productInsightsSSL" groups="<groupName>"
           proxyUrl="<proxyURL>" proxyUser="<proxyUserName>" proxyPassword="<proxyPassword>"/>
    • On the url and apiKey attributes, specify the API host and key credentials that you noted when you created the Product Insights service. If you installed the Product Insights gateway, specify the URL of the gateway on the url attribute instead.
    • On the sslRef attribute, reference the ID of the ssl element that you defined.
    • For the optional groups attribute, you can define sets of Liberty servers to be grouped for reporting purposes. You can define multiple nested group levels, and you can include each Liberty server in multiple groups by separating the group names with a comma, as shown in the following example.
      groups="libertyGroup1, libertyGroup1/subgroupA, subgroupA/smallGroupx"
      In this example, smallGroupx is nested inside subgroupA, which is nested inside libertyGroup1. Specify highest level groups without a forward slash (/). Specify nested groups with a forward slash, such as in parentGroup/nestedGroup. Grouped servers are displayed hierarchically in the Product Insights service.
    • If you are not using the gateway and the Liberty server does not have direct access to the internet, define the HTTP proxy on the proxyUrl, proxyUser, and proxyPassword attributes. The proxy URL must be in http://hostname:port format, and the proxy user name and password are needed only if your HTTP proxy server requires authentication.

      If the Liberty has internet access or you are routing data through the gateway, you do not need to define proxy settings.

Results

To view registered servers in the IBM Cloud console, go to Menu (☰) > Dashboard and select your Product Insights service instance. Your registered servers are listed on the Manage tab of the service.

To stop reporting usage metrics from a Liberty server, remove the productInsights configuration from that server's configuration.


Icon that indicates the type of topic Task topic

File name: twlp_config_blmx_productinsights.html