Setup using IBM webMethods Installer

End-to-End Monitoring node on the IBM webMethods Installer allows you to setup the on-premises monitoring agents, which enable the end-to-end transaction monitoring of hybrid integration.

Note
  • In the installer based setup, Hybrid Monitoring support is only available for versions above IBM webMethods Integration Server 10.7 and API Gateway 10.11. You are required to upgrade your IBM webMethods Integration Server and API Gateway, if you need Hybrid Monitoring support for older versions of IBM webMethods Integration Server and API Gateway.
  • Use the Integration Server package-based approach for Hybrid Monitoring support of these older versions.

  1. Install Integration Server or Microservices Runtime along with End-to-End Monitoring, if not done already. If you have Integration Server pre-installed, select only End-to-End Monitoring.

    • For version 10.7

    • From version 10.11 onwards

    Note

    Make your selections as per the following criteria:

    • For Hybrid Monitoring with Integration Server, select:

      • End-to-End Monitoring Core
      • Integration Server or Microservices Runtime Plug-in

    • For Hybrid Monitoring with API Gateway, select:

      • End-to-End Monitoring Core
      • API Gateway Plug-in

  2. Using IBM webMethods Update Manager, install the latest fixes for all installed IBM products along with End-to-End Monitoring core. Based on the product installed, install either Integration Server and Microservices Runtime plug-in fix, or API Gateway plug-in fix.

    Note
    • From v10.15 onwards, product code UHM has changed to UHA. If you come across a file name with UHA in it, consider it the same as a UHM file.

IBM webMethods Integration Server

  1. After fix installation, copy the plugin jar file:

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\plugins\uhm-onpremise-is-plugin.jar
    • To directory:
      <INSTALL-DIR>\IntegrationServer\lib\jars\

  2. Setting up logs: Copy logback xml file

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\config\e2ecustomlogback.xml
    • To directory:
      <INSTALL-DIR>\IntegrationServer\instances\default
    Note
    If you cannot locate the file e2ecustomlogback.xml in the installation, then install latest fixes.

  3. Add the following lines at the end of the file:
    <INSTALL-DIR>\profiles\IS_default\configuration\custom_wrapper.conf

    • Microsoft Windows 

      wrapper.java.additional.501=-Xbootclasspath/a:..\..\..\E2EMonitoring\agent\uhm-apm-agent.jar;"%JAVA_BOOT_CLASSPATH%"
wrapper.java.additional.502=-javaagent:..\..\..\E2EMonitoring\agent\uhm-apm-agent.jar=logging.dir=.\logs\

    • Linux 

      wrapper.java.additional.501=-Xbootclasspath/a:../../../E2EMonitoring/agent/uhm-apm-agent.jar:"%JAVA_BOOT_CLASSPATH%"
wrapper.java.additional.502=-javaagent:../../../E2EMonitoring/agent/uhm-apm-agent.jar=logging.dir=./logs/
    Note
    From v10.15 onwards, product code UHM has changed to UHA. Accordingly, replace uhm-apm-agent.jar with uha-apm-agent.jar in the above lines.

  4. Open the file: <INSTALL-DIR>\profiles\IS_default\configuration\custom_wrapper.conf, add the property:

    • Microsoft Windows:

          wrapper.java.additional.503=-Dlogback.configurationFile=.\e2ecustomlogback.xml

    • Linux:

          wrapper.java.additional.503=-Dlogback.configurationFile=./e2ecustomlogback.xml

  5. If multiple tenant connections are supported in Integration Server and a custom tenant connection is being used, then open the file: <INSTALL-DIR>\E2EMonitoring\agent\config\agent.configand set the below properties:

Property Description
agent.onprem_multitenant_alias = ${SW_AGENT_ONPREM_MULTITENANT_ALIAS:default} Un-comment this property and replace default with the tenant connection name. Restart Integration Server.
Note
  • When a custom tenant connection is not used, End-to-End Monitoring uses the default tenant connection value for agent.onprem_multitenant_alias in agent.config. You need to save the default tenant connection details in webMethods Integration Server when there is no custom connection.
  • Hybrid data transfer takes place within tenants of one given region only. When multiple tenant connections are created for different tenants belonging to the same region, specifying one of the tenant connection names for agent.onprem_multitenant_alias in agent.config is sufficient to trace hybrid transactions of other tenants belonging to the same region.
  • To see segment traces of on-premises API Gateway transaction in logs, set all log levels to DEBUG in versions below 10.15
    <INSTALL-DIR>\IntegrationServer\instances\default\e2ecustomlog4j2.properties
  • From v10.15 onwards, set log levels to debug in
    <INSTALL-DIR>\IntegrationServer\instances\default\e2elogback.xml
  • agent.trace_transfer_interval=${SW_AGENT_TRACE_TRANSFER_INTERVAL:180000}: This property defines the interval between each write operation to the file. The same property is used for data send interval through the gRPC channel. Default value is 18000 ms. It is recommended to reduce this time interval to shorter segment trace writes if you prefer a faster sync time.

Click here for more details on End-to-End Monitoring agent configurable properties for hybrid monitoring with Integration Server.

Click here for more details on traces information in logs files.

Important
Complete the Mandatory Configuration after the Integration Server setup.

IBM webMethods Microservices Runtime

  1. After fix installation, copy the plugin jar file:

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\plugins\uhm-onpremise-is-plugin.jar
    • To directory:
      <INSTALL-DIR>\IntegrationServer\lib\jars\

  2. Setting up logs: Copy logback xml file

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\config\e2ecustomlogback.xml
    • To directory:
      <INSTALL-DIR>\IntegrationServer\
    Note
    If you cannot locate the file e2ecustomlogback.xml in the installation, then install latest fixes.

  3. Add the following lines at the end of the file:

    • Microsoft Windows

      <INSTALL-DIR>\IntegrationServer\bin\setenv.bat

      set JAVA_UHM_OPTS=-javaagent:"../E2EMonitoring/agent/uhm-apm-agent.jar=logging.dir=./logs/" -Xbootclasspath/a:"../E2EMonitoring/agent/uhm-apm-agent.jar"
set JAVA_CUSTOM_OPTS=%JAVA_CUSTOM_OPTS% %JAVA_UHM_OPTS%
set JAVA_CUSTOM_OPTS=%JAVA_CUSTOM_OPTS% -Dlogback.configurationFile="./e2ecustomlogback.xml"

    • Linux

      <INSTALL-DIR>\IntegrationServer\bin\setenv.sh

      JAVA_UHM_OPTS="-javaagent:../E2EMonitoring/agent/uhm-apm-agent.jar=logging.dir=./logs/ -Xbootclasspath/a:../E2EMonitoring/agent/uhm-apm-agent.jar"
JAVA_CUSTOM_OPTS="${JAVA_CUSTOM_OPTS} ${JAVA_UHM_OPTS}"
JAVA_CUSTOM_OPTS="${JAVA_CUSTOM_OPTS} -Dlogback.configurationFile=./e2ecustomlogback.xml"
Important
Complete the Mandatory Configuration after the Microservices Runtime setup.

IBM webMethods API Gateway

End-to-End Monitoring supports hybrid monitoring involving on-premises API Gateway v10.11 and later versions.

Note
  • On-premises Integration Server and API Gateway plugins cannot be installed in the same installation. This is a known limitation.
  • From v10.15 onwards, product code UHM has changed to UHA. If you come across a file name with UHA in it, consider it the same as a UHM file.

  1. Copy file: uhm-onpremise-is-http-plugin.jar

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\plugins\uhm-onpremise-is-http-plugin.jar
    • To directory:
      <INSTALL-DIR>\IntegrationServer\lib\jars\

  2. Copy file: uhm-api-onpremise-plugin.jar

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\plugins\ uhm-api-onpremise-plugin.jar
    • To directory:
      <INSTALL-DIR>\IntegrationServer\instances\default\packages\WmAPIGateway\code\jars

  3. Setting up logs:

    For versions below 10.15: Copy log4j properties file:

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\config\e2ecustomlog4j2.properties
    • To directory:
      <INSTALL-DIR>\IntegrationServer\instances\default\

    From v10.15 onwards: Copy logback xml file

    • From directory:
      <INSTALL-DIR>\E2EMonitoring\agent\config\e2ecustomlogback.xml
    • To directory:
      <INSTALL-DIR>\IntegrationServer\instances\default\

  4. Add the following lines at the end of the file:
    <INSTALL-DIR>\profiles\IS_default\configuration\custom_wrapper.conf

    • Microsoft Windows 

      wrapper.java.additional.501=-Xbootclasspath/a:..\..\..\E2EMonitoring\agent\uhm-apm-agent.jar;"%JAVA_BOOT_CLASSPATH%"
wrapper.java.additional.502=-javaagent:..\..\..\E2EMonitoring\agent\uhm-apm-agent.jar=logging.dir=.\logs\

    • Linux 

      wrapper.java.additional.501=-Xbootclasspath/a:../../../E2EMonitoring/agent/uhm-apm-agent.jar:"%JAVA_BOOT_CLASSPATH%"
wrapper.java.additional.502=-javaagent:../../../E2EMonitoring/agent/uhm-apm-agent.jar=logging.dir=./logs/
    Note
    From v10.15 onwards, product code UHM has changed to UHA. Accordingly, replace uhm-apm-agent.jar with uha-apm-agent.jar in the above lines.

  5. For versions below 10.15,

    Open the file: <INSTALL-DIR>\profiles\IS_default\configuration\custom_wrapper.conf, edit the property Dlog4j.configurationFile and append e2ecustomlog4j2.properties to it.

    • Microsoft Windows:

      • Existing

        wrapper.java.additional.204=Dlog4j.configurationFile="<INSTALL-DIR>\profiles\IS_default\configuration\logging\log4j2.properties,.tc.custom.log4j2.properties"

      • Appended

        wrapper.java.additional.204=Dlog4j.configurationFile="<INSTALL-DIR>\profiles\IS_default\configuration\logging\log4j2.properties,.tc.custom.log4j2.properties,e2ecustomlog4j2.properties"

    • Linux:

      • Existing

        wrapper.java.additional.204=-Dlog4j.configurationFile="<INSTALL-DIR>/profiles/IS_default/configuration/logging/log4j2.properties,.tc.custom.log4j2.properties"

      • Appended

        wrapper.java.additional.204=-Dlog4j.configurationFile="<INSTALL-DIR>/profiles/IS_default/configuration/logging/log4j2.properties,.tc.custom.log4j2.properties,e2ecustomlog4j2.properties"

    From v10.15 onwards,

    Open the file: <INSTALL-DIR>\profiles\IS_default\configuration\custom_wrapper.conf, add the property:

    • Microsoft Windows:

          wrapper.java.additional.503=-Dlogback.configurationFile=".\e2ecustomlogback.xml"

    • Linux:

          wrapper.java.additional.503=-Dlogback.configurationFile="./e2ecustomlogback.xml"

What are the API Gateway specific configurable properties?

Property Description
agent.service_name=${SW_AGENT_NAME:ONPREMISEIS} Indicates service name that monitors product calls.
Set SW_AGENT_NAME to ONPREMISEAPI, to monitor on-premise API Gateway calls.
agent.onprem_tenant_id=${SW_AGENT_ONPPREM_TENANT_ID:default} Indicates cloud tenant from which transactions to on-premise API Gateway takes place.
Tenant name is the value for SW_AGENT_ONPPREM_TENANT_ID.

New value: agent.onprem_tenant_id=${SW_AGENT_ONPPREM_TENANT_ID:<TenantName}
agent.onprem_multitenant_alias = ${SW_AGENT_ONPREM_MULTITENANT_ALIAS:default} Indicates name of the custom tenant connection used in Integration Server.
Custom tenant connection name created in the Integration Server is the value for the SW_AGENT_ONPREM_MULTITENANT_ALIAS.
This property is commented out by default, un-comment it if custom tenant connection is used in the Integration Server.
agent.apigw_tag=${SW_AGENT_APIGW_TAG:<custom tag>} End-to-End Monitoring, by default, monitors all the on-premises API Gateway calls with tag e2em. If you need to monitor an API containing custom tags , add this property in agent.config with custom tag value. To enable tracing, add the e2em tags to the API Gateway API, in case you do not have them already.
agent.onprem_jndi_auth_enable=${SW_AGENT_ONPREM_JNDI_AUTH_ENABLE:false} This property defines on-premises to cloud JNDI based authentication. Verify that it is set to false.
collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES: uhm.e2em-hybrid-az-us.webmethods.io:443} In case of agent to collector connection issues, this property can be used to set collector endpoint so that the agent can connect to the specified collector. This property is not required to be set explicitly from v10.15 onwards, for v10.11 or v1.3.0 latest fixes (Fix 5 and above).

Note: Refer Collector end-point section for specific collector end-point values.

Click here for the common configurable properties in the End-to-End Monitoring agent available at
<INSTALL-DIR>\E2EMonitoring\agent\config\agent.config

Note
  • To see segment traces of on-premises API Gateway transaction in logs, set all log levels to DEBUG in
    <INSTALL-DIR>\IntegrationServer\instances\default\e2ecustomlog4j2.properties (For versions below 10.15)
    <INSTALL-DIR>\E2EMonitoring\agent\config\e2ecustomlogback.xml (From v10.15 onwards)
  • End-to-End Monitoring can trace transactions belonging to a single tenant, even if end-to-end transactions involve multiple API Gateway tenants at a time.
  • Hybrid monitoring works with on-premises Integration Server as well as on-premises API Gateway. However, End-to-End Monitoring does not support usage of both products together as part of hybrid integration.
  • End-to-End Monitoring by default monitors all the on-premises API Gateway calls with the tag e2em.
  • agent.trace_transfer_interval=${SW_AGENT_TRACE_TRANSFER_INTERVAL:180000}: This property defines the interval between each write operation to the file. The same property is used for data send interval through the gRPC channel. Default value is 18000 ms. It is recommended to reduce this time interval to shorter segment trace writes if you prefer a faster sync time.

Click here for more details on traces information in logs files.

Important
Complete the Mandatory Configuration after the API Gateway setup.