Installing an App Visibility agent using the wizard


Where you are in the Installation process

Step Task
1 Complete the planning activities
2 Prepare for TrueSight Operations Management installation
3 Install Remedy Single Sign-On
4 Install TrueSight Presentation Server
5 Install TrueSight Infrastructure Management (if licensed) 
6 Install TrueSight App Visibility Manager — Phase A
Install TrueSight App Visibility Manager — Phase B Task 1 (You are here)
Install TrueSight App Visibility Manager — Phase B Task 2
7 Install Real End User Experience Monitoring Software Edition (If licensed)
8 Install TrueSight IT Data Analytics (If licensed)
9 Complete the post-installation activities

App Visiblity agents are available for Java and .NET environments. Based on your environment, you can install the applicable agent on the computer with the application server you want to monitor. After you install the agent, connect it to the App Server instance. 

To install the App Visibility agent for Java 

  1. Log in to the computer with the user that runs the application server.
    On Windows computers, you must run the installation with a user that has administrator privileges.

  2. Copy and extract the files to a temporary directory on the target computer.
  3. (Linux) Set the DISPLAY environment variable to ensure that the wizard-based installer launches the screens appropriately.
    export DISPLAY=<IP address of the host computer>:0.0
  4. Launch the installation wizard:
    • (Windows) Double-click setup.exe.
    • (Unix) Double-click setup.bin.
  5. On the Welcome page, click Next.
  6. Read the license agreement, agree to the terms, and click Next.
  7. Specify the installation directory or retain the default, and click Next
    The default directory is:

    • (WindowsC:\Program Files (x86)\BMC Software\App Visibility\Agent for Java

    • (Linux, AIX, Solaris/opt/bmc/App_Visibility/Agent_for_Java

  8. Type the Application Server Display Name, which is displayed in the TrueSight console, and click Next. The default name is the DNS host name.
  9. Type the values for the Portal Connection parameters.
    1. Enter the Portal connection details:
      • Portal Server—Enter the IP address or host name on which the App Visibility portal is (or will be) installed.

        If a load balancing server manages access to the portal, enter the host name or IP address of the load balancer.

      • Portal Port—Enter the App Visibility portal port number.

        If a load balancing server manages access to the portal, enter the port number of the load balancer.

    2. If your environment requires the agent to use a proxy server when communicating with the portal and collector, enter Proxy Server Details:

      Note

      Proxy server details are required only if you are using a reverse proxy server or load balancing server. This server is not the same server as the App Visibility proxy, which is used to collect end-user browser data.

      • Proxy Server—Select one of the following:
        • No Proxy
        • HTTPS Proxy
        • SOCKS Proxy

        Default: No Proxy

      • Proxy Host Name or IP Address—Enter the web proxy server host name or IP address.

        If the App Visibility portal is behind a proxy server, enter the server host name or IP address.

      • Proxy Port—Enter the web proxy server port number for outbound connection. If you use a proxy server, this property cannot be blank.

    3. Click Next
      The installation utility tests the connection.
      • If the system successfully connects to the App Visibility portal, the Installation Preview page is displayed.
      • If the system fails to connect to the App Visibility portal or the proxy server, a validation error is displayed. Do one of the following:
        • Click Previous to verify the connection details and test the connection again. 
        • Continue with the installation, and change the connection details after installation.
  10. Review the details, and click Install.

  11. Click Done to end the installation process. 
  12. Configure the Java options for the agent.

      Click here to see the steps.

    After you install the agent, you need to add the agent to the Java command line. The javaagent option is required to connect the App Visibility agent to the JVM process. Enter the information that is relevant to your installation.

    1. Add the following agent JVM options to the Java command line of your application server.

      Replace <installationDirectory> with the destination directory in which the App Visibility agent was installed.

      The procedure to update Java options is different for each application server type.

      • (Windows) -javaagent:<installationDirectory>\ADOPsInstall\adops-agent.jar

      • (Linux, AIX, Solaris) -javaagent:<installationDirectory>/ADOPsInstall/adops-agent.jar

    2. If you have a single App Visibility agent installation directory that is used by multiple JVM processes, you can assign meaningful names to distinguish each instance.
    3. Restart the application server or JVM process.

  13. Verify that the installation of the App Visibility agent for Java was successful, and that the agent was invoked, by reviewing the log files created during installation.

      To review the installation logs
    1. Open the bmc_ad_agent_install.log file, located in the %temp% (Windows) or temp (Linux) directory.
    2. Examine the log:
      • App Visibility Agent for Java was installed successfully. indicates the installation was successful.
      • Error messages can indicate incorrect privileges or write access. Ensure that you have execute privileges on the installation scripts, and write access to the installation location.

        Example of a bmc_ad_agent_install.log

        2014/12/30 13:20:26:583 CT [INFO] com.bmc.aps.server.agentinstaller.se.AgentInstaller - Thread[main,5,main]4461550 -
        ------------------------------------------------------------------
        App Visibility Agent for Java was installed successfully.
        
        Installation parameters summary: 
            -destination      "C:\Users\Administrator\Desktop\Granite App Visibility\build - 175\agent"
            -host             ""
            -portalIP         "localhost"
            -portalPort         "8100"
            -proxyHttpsHost     ""
            -proxyHttpsPort     "-1"
            -proxySocksHost     ""
            -proxySocksPort     "-1"
        
        To run an application server with App Visibility Java Agent, add the following 
        parameter to the JVM options of your application server:
        -javaagent:C:\Users\Administrator\Desktop\Granite App Visibility\build - 175\agent\ADOPsInstall\adops-agent.jar
        * The -javaagent option is required to connect the Agent to the JVM process. 
        * A -Dcom.bmc.adops.agent.server.id=<uniqueID> option may be used. It is 
          only needed when a single Agent installation directory is to serve multiple 
          JVM processes, and only if Agent fails to generate a unique, persistent id 
          per instance on its own. If provided, <uniqueID> should be unique per 
          application server instance using an Agent on this machine (for example, 
          server-name from server's start-script environment variables).
        
      To verify that the agent for Java has been invoked
    1. Access the log files folder in the local installation directory, for example: C:\AppVis\ADOPsInstall\instances\<instance_name>\logs 
      The <instance_name> variable is a name that is generated dynamically when the agent first starts.
    2. Examine the aps_agent.log file.
      If the log file exists, the installation was successful.
      Examine [ERROR] messages for issues that you can address, such as App Visibility portal connection issues. Ensure that the portal address is correct and that a firewall is not blocking access.
    3. In the TrueSight console, select Administration > App Visibility Agents from the navigation pane and confirm that the agent is online.

Configuring App Visibility agents for Java

After installing the App Visibility agent for Java, complete the following configuration tasks:

Update Java options according to the application server type

As part of the App Visibility agent for Java installation process, you must add the agent JVM options to the Java command line of your application server.

The procedure to update the JVM options is different for each application server type, and this topic provides examples for some of the leading types of application servers. If you have more than one JVM process using the same agent installation, you can assign meaningful names to distinguish each instance.

The App Visibility agent for Java runs in the same JVM memory space as the monitored applications, therefore BMC recommends increasing by 256 MB the maximum heap size specified through the -Xmx Java option.

Example

set JAVA_OPTS=%JAVA_OPTS% -Xmx1024m

For full details about both the -javaagent and -Xmx options, refer to the Java options documentation for your application server type.

In the following procedures, replace the <AgentInstallationDirectory> with the location where the agent is installed. The default folder is the one from which the installation script is run, for example:

  • (Windows) <AgentInstallationDirectory>\ADOPsInstall\adops-agent.jar
    Where <AgentInstallationDirectory> is the C:\bmc\appvis_agent directory
  • (Linux) <AgentInstallationDirectory>/ADOPsInstall/adops-agent.jar
    Where <AgentInstallationDirectory> is the /usr/bmc/appvis_agent directory
  To distinguish multiple JVM processes using the same agent installation

If you have a single App Visibility agent installation directory that is used by multiple JVM processes, you can assign meaningful names to distinguish each instance. Otherwise, the same application server name (defined during installation) might be displayed multiple times.

Use one of the following command-line arguments for each JVM process:

  • -Dcom.bmc.adops.agent.instance.global.name=<globallyUniqueName>
    The <globallyUniqueName> value must be unique among all App Visibility agents in the system.
  • -Dcom.bmc.adops.agent.instance.local.name=<locallyUniqueName>
    The <locallyUniqueName> value must be unique for each application server instance on the computer that uses the agent. The <locallyUniqueName> value is appended to the application server display name defined during agent installation (or the agent host name, if you did not define a name during installation).

Note

The values for <globallyUniqueName> and <locallyUniqueName> can include only alphanumeric Latin characters, spaces, underscore characters (_), and hyphens (-).

Configure WebSphere JVM options from the admin console; do not configure them from the start script.

  1. Log in to the WebSphere admin console.
  2. Expand Server Type and select WebSphere application servers.
  3. Click the name of the server to which you want to attach the App Visibility agent.
  4. Expand Java and Process Management and select Process Definition.
  5. Under the Additional Properties section, click Java Virtual Machine.
  6. Scroll down and locate the text box for Generic JVM arguments.
  7. Add the following arguments, separating each argument by a single space:

    • (Windows) -javaagent:<AgentInstallationDirectory>\ADOPsInstall\adops-agent.jar -Dcom.bmc.adops.agent.instance.local.name=<locallyUniqueName>

    • (Linux) -javaagent:<AgentInstallationDirectory>/ADOPsInstall/adops-agent.jar -Dcom.bmc.adops.agent.instance.local.name=<locallyUniqueName>

    Note

    Do not enter a new line between the arguments. A new line between the arguments can prevent the argument from being applied.

  8. Save the configuration.
  9. Restart the WebSphere Application Server process.

For further information about setting JVM arguments in WebSphere, see the  IBM website .

  To update options for Oracle WebLogic
Watch videos on YouTube

Watch Installing App Visibility Part 4 | Installing the Agent for Java (starting at 1:05) to add the agent through the Oracle starter file,  startWebLogic.cmd, in the  bin directory.
  1. Edit the startWebLogic.cmd(Windows) or startWebLogic.sh(Linux) script. 
    This script is used when starting both admin and managed servers. The startManagedWebLogic script calls the startWebLogic script.
  2. Locate the JAVA_OPTIONS environment variable and add the following lines:

    • (Windows) set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:<AgentInstallationDirectory>\ADOPsInstall\adops-agent.jar -Dcom.bmc.adops.agent.instance.local.name=<locallyUniqueName>

    • (Linux) JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:<AgentInstallationDirectory>/ADOPsInstall/adops-agent.jar -Dcom.bmc.adops.agent.instance.local.name=<LocalUniqueID>"

  3. Restart the WebLogic Application Server process.

For further information about specifying Java options for a WebLogic server instance, see the  Oracle website .

  To update options for JBoss
  1. Edit the JBoss run.cmd(Windows) or run.sh(Linux) script.
  2. Locate the JAVA_OPTS environment variable.
  3. Add the following lines:

  4. Restart the JBoss Application Server process.
    For further information about updating the JBoss configuration or run script, see the  JBoss website .

Grant Java 2 permissions to the App Visibility agents

The App Visibility agent requires permissions to the Java 2 system, such as write access to the application server computer (for log entries), and API access to various application interfaces to collect diagnostic information. On application servers that use Java 2 security, you must provide permissions to the App Visibility agent.

Granting the relevant permissions depends on the Java 2 security provider and application server type. This topic describes how to grant the relevant Java 2 permissions on different application server types.

  To grant Java 2 permissions on IBM WebSphere

On secured WebSphere servers you grant Java 2 permissions by configuring the server.policy file, as described in the following steps:

  1. Locate and open the server.policy file, which is found in the properties library.
  2. Modify the server.policy file with the relevant permissions. For details, refer to the Configuring server.policy file resource section on the  IBM website .
  3. Restart WebSphere.

    Example of the lines added to the IBM WebSphere server.policy file to grant Java 2 permission for the App Visibility agent:

    Example

    // Allow the App Visibility agent all permissions
    grant codeBase "file:C:/aps_agent/ADOPsInstall/-" {
      permission java.security.AllPermission;
    };
    
  To grant Java 2 permissions on Oracle WebLogic

WebLogic does not have a default policy file and can be configured to use one, as described in the following steps:

  1. Locate the weblogic.policy file, which is usually found in the security library, and open it for editing.
  2. Modify the policy file with the relevant permissions. For details, refer to the Using Java Security to Protect WebLogic Resources and Java Security Overview sections on the  Oracle website .
  3. Restart WebLogic.
  To grant Java 2 permissions on Apache Tomcat

On secured Tomcat servers this is achieved by configuring the catalina.policy file, as described in the following steps:

  1. Locate the catalina.policy file, which is usually found in the conf library, and open it for editing.
  2. Modify the catalina.policy file with the relevant permissions. For details, refer to the Security Manager HOW-TO section on the  Tomcat website .
  3. Restart Tomcat.
  To grant Java 2 permissions on JBoss

JBoss does not have a default policy file. It uses the JVM’s default policy file, or you can configure it to use a different one, as described in the following steps:

  1. Locate the server.policy file, which is usually found in the conf library, and open it for editing.
  2. Modify the policy file with the relevant permissions. For details, refer to the Java Security Manager section on the  JBoss website .
  3. Restart JBoss.

To install the App Visibility agent for .NET

  1. Log in to the computer with the user that runs the application server.
    On Windows computers, you must run the installation with a user that has administrator privileges. 
  2. Copy and extract the files to a temporary directory on the target computer.
  3. Launch the installation wizard by double-clicking setup.exe.
  4. On the Welcome page, click Next.
  5. Read the license agreement, agree to the terms, and click Next.
  6. Specify the installation directory or retain the default, and click Next

    The default directory is C:\Program Files (x86)\BMC Software\App Visibility\Agent for .NET.

  7. Type the Application Server Display Name, which is displayed in the TrueSight console, and click Next. The default name is the DNS host name.
  8. Type the values for the Portal Connection parameters..
    1. Enter the Portal connection details:
      • Portal Server—Enter the IP address or host name on which the App Visibility portal is (or will be) installed.

        If a load balancing server manages access to the portal, enter the host name or IP address of the load balancer.

      • Portal Port—Enter the App Visibility portal port number.

        If a load balancing server manages access to the portal, enter the port number of the load balancer.

    2. If your environment requires the agent to use a proxy server when communicating with the Portal and Collector, select Use Web Proxy Server and enter connection details:

      Note

      Proxy server details are required only if you are using a reverse proxy server or load balancing server. This server is not the same server as the App Visibility proxy, which is used to collect end-user browser data.

      • Proxy Host Name or IP Address—Enter the web proxy server host name or IP address.
      • Proxy Port—Enter the web proxy server port number.
    3. Click Next
      The installation utility tests the connection.
      • If the system successfully connects to the App Visibility portal, the Installation Preview page is displayed.
      • If the system fails to connect to the App Visibility portal or the proxy server, a validation error is displayed. Click Previous to verify the connection details and test the connection again. If the connection fails again, continue with the installation and change the connection details after installation.
  9. Review the details, and click Install.

  10. Click Done to end the installation process.

  11. When the installation process is complete, restart IIS.
  12. Verify that the App Visibility agent for .NET installation was successful, and that the agent for .NET was invoked. 

      To review the installation logs
    1. Open the agentinstaller_install_log.txt file, located in the %temp% folder.
    2. In the log file, verify whether any error messages were reported. 
      If no error messages are in the log file, the installation was successful.
    3. In the TrueSight console, select Administration > App Visibility Agents from the navigation menu and confirm that the agent is online.

Troubleshooting installation issues

If you face issues during installation, see Troubleshooting the App Visibility Manager deployment

Next Step in the Installation process

Step 6 Phase B Task 2 Now that you have successfully installed the App Visibility agent, you must install the Transaction Execution Adapter agent.

Was this page helpful? Yes No Submitting... Thank you

Comments