Installation and Configuration Procedures

Note: Spring Insight templates are no longer supported. The documentation is here for reference only.

This section provides instructions for installing and configuring Spring Insight Operations.

Master Process - Installation and Configuration Steps

This page lists main steps in the Insight Operations installation and configuration process with links to detailed procedures.

1. Prepare to install Insight Operations.

   • Review system requirements. Verify that the systems where you will run Insight components conform to the specifications in Insight Operations Supported Configurations and System Requirements.
   • Configure licensing. Insight Operations is licensed under Pivotal tc Server.
   • Understand the process. See Installation and Configuration Overview.

2. Install Dashboard template. Follow the procedure that applies to your archive format: Install Dashboard Template.

3. Create and start Dashboard .

4. Configure user accounts. Either Configure User Accounts in Insight or Configure Users in LDAP.

5. Configure HTTP Transport. Configure your own agent accounts; set up SSL or proxy.

6. Configure another transport. Optional. Either Configure ActiveMQ Transport and Configure RabbitMQ Transport.

7. Dashboard Data Management. If desired, you can tailor the Dashboard’s data management and purge policies.

8. Configure Insight Agent data collection and processing behaviors.

   As desired, edit the properties in agent.override.properties to configure a variety of agent behaviors related to trace collection and processing. See Configure Agent Defaults.

9. Download and Run Agent Installer Install Agent Using Installer is the recommended method for installing the Insight Agent, as it pre-configures the agents per your dashboard configuration.

   If you are using Pivotal tc Server to deploy your applications, you can Install Agent on tc Server Using a Template. In this method, the agent will not be pre-configured to connect to your Dashboard; rather, you specify the required configuration interactively when you create or update a tc Server instance with the Insight Agent template.

10. Tailor Insight Agent configuration. Typically, it is unnecessary to configure most agent properties. If you do need to edit an agent’s properties file to change its configuration, see Configure the Insight Agent and Insight Agent Properties.

Installation and Configuration Overview

What Insight Operation components are installed, and how.

An Insight Operations environment consists of an Insight Operations Dashboard and one or more Insight Operations Agents that report to the dashboard. Practically speaking, both dashboard and agent are web applications that run in a supported application server instance.

The first thing you do is create the Insight Operations Dashboard — that is, you create a tc Server instance using the insight-dashboard template (which you get from the tc Server downloads page). The dashboard application is automatically deployed to the dashboard tc Server instance.

After configuring dashboard and global agent behaviors (settings that apply to all agents) as described just below, you download an agent installer from the dashboard and use it to install an agent that is pre-configured to connect to the dashboard and behave as you specified.

What Dashboard and global agent behaviors you can you configure, and how.

The key dashboard configuration tasks are creating accounts for dashboard users and Insight Agents. You need to configure a dashboard keystore, if you intend agent and dashboard to use SSL. Optionally, you can configure an alternate dashboard-agent transport mechanism—you can enable the Dashboard to use either ActiveMQ or RabbitMQ, in addition to the default HTTP transport.

Most configurable dashboard behaviors are controlled in the dashboard’s insight.properties file.

You can also pre-configure many agent behaviors in the dashboard properties file. In addition to properties that govern dashboard behavior, the dashboard’s insight.properties file also contains global properties that affect all agents, and dashboard connection settings — based on how you configure such properties, the agent installer will configure corresponding properties in the agent’s insight.properties file. For a list of properties, see Insight Dashboard Properties.

The agent installer automatically configures an agent’s trace collection and processing properties based on the settings in the dashboard’s agent.override.properties file (in pivotal-tc-server-standard-x.x.x.RELEASE/myDashboard/insight/conf. So, if you want to re-configure these behaviors for all agents, edit agent.override.properties in addition to dashboard’s insight-properties file, before downloading the agent installer.

After you edit the dashboard’s insight-properties and agent.override.properties files, you download the agent installer (insight-agent.jar) from the Dashboard user interface to each machine with containers (supported versions of tc Server, JBoss, Tomcat, or WebLogic Server) where you have applications you want to monitor.

The agent installer requires no input; it configures the agent based on the dashboard properties files. You can however run the agent installer in interactive mode if you wish to supply configuration properties at the command line. For installer instructions Install Agent using insight-agent.jar.

After agent installation, configuration properties can be viewed and edited, as appropriate, in the agent instance’s insight/conf/insight.properties file.

Notes:

• In the absence of a running Dashboard from which you can download the agent installer, you can create an Insight Operations Agent by create a tc server instance with the agent template. In such cases, the agent will not be pre-configured based on dashboard configuration settings. An agent created with a tc Server template must be manually configured.

The sections that follow provide instructions primarily for configuration tasks that are required to get the Insight Dashboard and Insight Agent up, running, and talking to each other about your web applications. Detailed instructions are not provided for all optional configuration tasks. Configuration steps usually include editing configuration properties. Configuration properties are listed in Insight Dashboard Properties and Insight Agent Properties.

Dashboard Installation and Configuration Topics

The following topics describe how to install and configure the Spring Insight dashboard into a Pivotal tc Server instance:

• Install Dashboard Template from Template Repository or ZIP Archive
• Create and Start Dashboard
• Configure User Accounts in Insight
• Configure Users in LDAP
• Configure HTTP Transport
• Configure ActiveMQ Transport
• Configure RabbitMQ Transport
• Configure Dashboard Data Management
• Configure Agent Defaults
• Insight Dashboard Properties

Install Dashboard Template from Template Repository or ZIP Archive

The Spring Insight Operations template is available from tcruntime-admin get-template command. It can also be found on VMware Tanzu Network. The template archive contains a template for creating an Insight Dashboard tc Server instance. In this procedure, you unpack the package into the templates directory of a dedicated tc Server Standard Edition installation, and then create the Dashboard instance with the new template. (The Insight Agent installer is bundled with the dashboard.)

1. If you have not already done so, install Pivotal tc Server Standard Edition on the machine where you will run the Insight Dashboard. (Refer to the appropriate installation topic in Getting Started with Pivotal tc Server.)

   You will run the Insight Dashboard in a dedicated tc Server instance, not in the same container as your monitored applications, which is where you will install the Insight Agent.

2. On the computer on which you installed tc Server and on which you will run Insight Dashboard, log in astcserver. On Unix, if you have disabled interactive login, log in as the root user and use su - tcserver to become the user.

3. To retrieve Spring Insight Operations you can use the on-demand template option by executing tcruntime-admin get-template --list command from your tc Server installation directory, which will list the available templates. Once you specify the template, it will be downloaded and then installed into your templates directory for use when creating your instance. For example:

   ./tcruntime-admin.sh get-template spring-insight-operations
   

After installing the operations template, Create and Start Dashboard.

Create and Start Dashboard

In this step you create a tc Server instance using the insight-dashboard template. The instance you create has the dashboard application pre-deployed, and contains a downloadable agent installer.

On the machine where you installed the insight-dashboard template:

1. In a terminal window, change to the tc Server home directory. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard-version                  
   

2. Create a tc Server instance with tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows), using the insight-dashboard template. For example, to create an instance named myDashboard on a Unix system:

   prompt$ ./tcruntime-instance.sh create -t insight-dashboard myDashboard 
   

   Use the -i directory option of tcruntime-instance to specify a different instance directory from the current installation directory. For example:

   prompt$ ./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-server-standard -t insight-dashboard myDashboard
   

   For information about the tcruntime-instance command and supported command options, see the tcruntime-ctl Command Reference section in Getting Started with tc Server.

3. Start the Spring Insight Dashboard instance with the tcruntime-ctl.sh or tcruntime-ctl.bat command.

   • On Unix systems:

     prompt$ ./tcruntime-ctl.sh myDashboard start
     

   • On a Windows system, install a Windows Service for the instance before you start it the first time. (After that, you can control the service from the Windows services control panel.) Enter these commands to install and start the service:

     prompt> tcruntime-ctl.bat myDashboard install 
     

     prompt> tcruntime-ctl.bat myDashboard start
     

   For information about the tcruntime-ctl command and supported command options, see the tcruntime-ctl Command Reference section in Getting Started with tc Server.)

4. Open the Insight Dashboard user interface in a web browser at http://myDashboardHost:8080/insight.

   If your browser is on the same computer as tc Server, you can use http://localhost:8080/insight.

5. Log in using one of the pre-configured user accounts with a username-password combination listed in the following table. The insight_admin role is required to use dashboard administrative functions and support tools, for example, to download the agent installer.

   Table 1. Insight Dashboard Login Information

   Role	User Name	Password
   insight_admin	admin	insight
   insight	spring	insight

After creating the dashboard, proceed with remaining configuration tasks on Master Process: Installation and Configuration Steps.

Configure User Accounts in Insight

This section has instructions for configuring user accounts within Insight.

(Alternatively, to set up users in LDAP, see Configure Users in LDAP.)

The dashboard by default uses the INSTANCE-DIR/conf/tomcat.users file to authenticate users, where INSTANCE-DIR refers to the tc Server instance directory into which the Insight Dashboard is installed, such as /opt/pivotal/pivotal-tc-server-standard-version/myDashboard. Users can be regular users (insight role) or administrators (insight_admin role). The insight_admin role is required to perform some operations on the Administration page.

You should secure your Spring Insight Operations installation by changing the default users and passwords.

1. Edit the INSTANCE-DIR/conf/tomcat.users file. This is the initial content of the file:

   <?xml version="1.0"?>
   <tomcat-users>
       <role rolename="insight"/>
       <role rolename="insight_admin"/>
       <user password="insight"
             roles="insight"
             username="spring"/>
       <user password="insight"
             roles="insight,insight_admin"
             username="admin"/>
   </tomcat-users>
   

2. Edit or add <user> elements for the users you wish to authenticate, setting the password, roles, and username attributes for each user. Include the insight role for all users and add the insight_admin role for users who should have administrator capabilities.

3. Save changes to tomcat.users, then restart the Insight Dashboard with the tcruntime-ctl restart command.

After creating dashboard user, proceed with remaining configuration tasks on Master Process: Installation and Configuration Steps.

Configure Users in LDAP

If you use LDAP, you can use it to authenticate Insight Dashboard users. The procedure below is for Open LDAP.

1. Create a directory called plugin-config in the insight/dashboard-plugins directory of your Dashboard tc Runtime instance. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard-n.n.n.RELEASE/myDashboard
   prompt$ mkdir insight/dashboard-plugins/plugin-config
   

2. Copy the insight-dashboard-security-ldap-x.x.x.RELEASE.jar file from the insight/extras/ldap directory to the insight/dashboard-plugins directory of your Dashboard tc Runtime instance. For example:

   prompt$ cp insight/extras/ldap/insight-dashboard-security-ldap-x.x.x.RELEASE.jar insight/dashboard-plugins
   

3. Copy the insight-plugin-dashboard-security-ldap.xml file from the insight/extras/ldap directory to the insight/dashboard-plugins/plugin-config/ directory. For example:

   prompt$ cp insight/extras/ldap/insight-plugin-dashboard-security-ldap.xml insight/dashboard-plugins/plugin-config
   

4. Remove the default insight-dashboard-security-tcserver.jar.

   prompt$ rm insight/dashboard-plugins/insight-dashboard-security-tcserver-x.x.x.RELEASE.jar
   

   Note: The dashboard-plugins directory may contain either insight-dashboard-security-tcserver.jar or insight-dashboard-security-ldap.jar, but not both.

5. In insight/dashboard-plugins/plugin-config/insight-plugin-dashboard-security-ldap.xml, check to see if the following bean definitions are present; if they are not, add them:

    <bean id="insightEntryPoint" class="com.springsource.insight.dashboard.plugins.security.DefaultEntryPoint" />
    <bean id="insightLogoutSuccessHandler" class="com.springsource.insight.dashboard.plugins.security.DefaultLogoutSuccessHandler" />
    <bean id="insightAuthFilter" class="com.springsource.insight.dashboard.plugins.security.DefaultAuthenticationFilter">
        <property name="filterProcessesUrl" value="/login/authenticate" />
        <property name="authenticationSuccessHandler" ref="authSuccessHandler" />
        <property name="authenticationFailureHandler" ref="authFailureHandler" />
        <property name="authenticationManager" ref="authenticationManager" />
    <bean>
   

6. In insight/dashboard-plugins/plugin-config/insight-plugin-dashboard-security-ldap.xml, modify bean contextSource to point to your own LDAP server.

   <bean id="contextSource" 
         class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
     <constructor-arg value="ldap://myOpenLDAPServer:389/dc=springsource,dc=com"/>
     <property name="userDn" value="cn=Manager,dc=springsource,dc=com"/>
     <property name="password" value="secret"/>
   </bean>
   

7. Add userDN and password properties that the Directory Manager or other user will use to connect to the LDAP server.

   Note: If the LDAP server allows anonymous access, you do not need to add userDN and password properties.

   <bean id="contextSource" 
         class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
     <constructor-arg value="ldap://myOpenLDAPServer:389/dc=springsource,dc=com"/>
     <property name="userDn" value="cn=Manager,dc=springsource,dc=com"/>
     <property name="password" value="secret"/>
   </bean>
   

8. In the insightAuthenticationProvider bean, modify the userDnPatterns property to specify your User Base DN.

   <property name="userDnPatterns">
            <list><value>cn={0},ou=Users,o=SpringInsight</value></list>
   </property>
   

9. Modify the first <constructor-arg> element of the TransformingLdapAuthoritiesPopulator bean to point to your Group Base DN.

   <bean class="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator">
     <constructor-arg ref="contextSource"/>
     <constructor-arg value="ou=Groups,o=SpringInsight"/>
     <property name="groupSearchFilter" value="(|(member={0})(member={1}))"/>
   </bean>
   

10. Set up the two Insight roles by modifying the map element of the second <constructor-arg> element to specify the groups for regular Insight users (Operators) and Insight administrators (Administrators).

    <map>
      <entry key="Operators" value="insight"/>
      <entry key="Administrators" value="insight_admin"/>
    </map>
    

After configuring LDAP authentication, proceed with remaining configuration tasks on Master Process: Installation and Configuration Steps.

Configure HTTP Transport

By default, the Insight Dashboard is configured to communicate with Insight Agents over HTTP. This section has instructions for optional HTTP transport configurations.

Most of the instructions tell you to update the file insight.properties, which is located in the INSTANCE-DIR/insight/conf directory, where INSTANCE-DIR refers to the directory in which the tc Server instance is located, such as /opt/var/pivotal-tc-server-standard-version.

Configure Agent Accounts

When an Insight Agent connects to the Insight Dashboard, it supplies a username and password that must match an account defined in the dashboard’s insight.properties file. When you create the dashboard instance using the insight-dashboard template, by default it will allow agents to log on over the default HTTP transport using the username “spring” and the password “insight”.

To create a new agent account for agents using the default HTTP transport, add the following properties to the INSTANCE-DIR/insight/conf/insight.properties file, replacing username and password with desired values:

agent.http.username: username
agent.http.password: password

Configure SSL for HTTP Transport

In INSTANCE-DIR/insight/conf/insight.properties:

1. Set agent.http.protocol to https.
2. If you do not want the dashboard to accept self-signed certificates, uncomment agent.http.ssl.allow.selfsigned and set it to true

3. Restart the tc Server instance that hosts the Insight Dashboard to make the configuration effective. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard/
   prompt$ ./tcruntime-ctl.sh myDashboard restart
   

Configure Proxy Server for HTTP Transport

In INSTANCE-DIR/insight/conf/insight.properties:

1. Set agent.http.use.proxy to true.
2. Useagent.http.proxy.host to specify the hostname of the proxy server.
3. Useagent.http.proxy.port to specify the listen port of the proxy server.

4. Restart the tc Server instance that hosts the Insight Dashboard to make the configuration effective. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard/
   prompt$ ./tcruntime-ctl.sh myDashboard restart
   

See Insight Dashboard Properties for optional properties, prefixed by “http”, that relate to the configuration of the HTTP transport.

Agent-Dashboad Connection URL

The URL that the agent uses to access the dashboard is formed from the related properties, like this:

agent.http.protocol://agent.http.host:agent.http.port/agent.http.context.path/agent/ 

Configure ActiveMQ Transport

This section has instructions for configuring the ActiveMQ dashboard - agent transport.

By default, the Insight Dashboard is configured to communicate with Insight Agents over HTTP. You can configure one additional transport—either Active MQ or RabbitMQ. You cannot define more than one additional transport, and you cannot disable the HTTP transport.

You configure transport behavior in the dashboard properties file. Note that the file contains both dashboard properties and agent properties (the latter of which the yet-to-be-downloaded agent installer will use to populate the agent’s own properties file.

1. Stop the dashboard instance. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard
   prompt$ ./tcruntime-ctl.sh myDashboard stop
   

2. Copy the insight-dashboard-agent-activemq-x.x.x.jar. plugin from the INSTANCE-DIR/insight/dashboard-plugins/extras/transports directory to theINSTANCE-DIR/insight/dashboard-plugins directory:

   INSTANCE-DIR refers to the tc Server instance directory of the Insight Dashboard, such as /opt/pivotal/pivotal-tc-server-standard-version/myDashboard.

   Note: Make sure that the INSTANCE-DIR/insight/dashboard-plugins does not contain any RabbitMQ jars.

3. This excerpt from INSTANCE-DIR/insight/conf/insight.properties, shows the dashboard and agent properties related to the ActiveMQ transport, uncommented:

   # Dashboard properties: These settings are used by the dashboard to provide an ActiveMQ transport
   # --------------------
   dashboard.activemq.protocol: nio
   dashboard.activemq.host: 0.0.0.0
   dashboard.activemq.port: 21234
   dashboard.activemq.data.dir: \#{insightConfig.dataDir}/agent
   dashboard.activemq.agent.auth.agent: insight
   ...
   ...
   ...
   # Agent properties: These settings are to connect to the dashboard via ActiveMQ
   # -----------------
   agent.activemq.protocol: nio
   agent.activemq.host: localhost 
   agent.activemq.port: 21234
   agent.activemq.username: agent
   agent.activemq.password: insight
   

   1. Uncomment the ActiveMQ-related properties.
   2. Define the Insight Dashboard insight.properties File dashboard.activemq.agent.auth.login property to configure a new agent account login and password. (This tells the dashboard to accept logins from that agent account.)
   3. Define the same credentials for the agent using agent properties: agent.activemq.username and agent.activemq.password. (When you download and use the agent installer after completing this configuration, these properties will be written to the installed agent’s properties file.)

4. If you want to use SSL for agent - dashboard communication, proceed to the next step. Otherwise skip to Step 7 of this procedure.

5. Create Keystore and Self-Signed Certificate for the dashboard. Perform these steps to create a keystore and certificate using the keytool utility included with the Sun JDK. You can use another tool, such as OpenSSL. See the documentation for your tool for the correct commands to use in the following procedure.

   Note: If you have a user-managed keystore and certificate for the dashboard that you prefer to use, skip this section and proceed with Step 6 of this procedure.

   If you prefer to use a CA-signed certificate rather than a self-signed certificate, purchase one from a CA such as VeriSign or Thawte. For help creating a Certificate Signing Request (CSR) and importing the signed certificate and trusted certificates into your keystore, see the documentation for keytool.

   1. If you do not already have a keystore file, create one with the following command:

      prompt$ keytool -genkey -alias dashboard -keyalg RSA -keystore dashboard.keystore
      

   2. Enter the requested information at the prompts.

      This information is encoded into the certificate the command creates. Make a note of the key password for use in later commands.

      The command creates the file dashboard.keystore containing one entry with the alias dashboard.

   3. Export the dashboard certificate.

      prompt$ keytool -export -alias dashboard -keystore dashboard.keystore -file dashboard_cert
      

   4. At the prompt, enter the keystore password.

      The file dashboard_cert is created in the current directory.

   5. To enable the changes, restart the tc Runtime instance.

6. Configure location of keystore.

   1. Set the Java system properties to specify the location of the dashboard.keystore file and the keystore password.

      It is easiest to do this in the INSTANCE-DIR/bin/setenv.sh script. Edit the setenv.sh script and add these lines above the JAVA_OPTS=... line.

      SSL_KEYSTORE="/full/path/to/dashboard.keystore" # e.g. "$CATALINA_BASE/conf/dashboard.keystore"
      SSL_KEYSTORE_PW="keystore_password"
      SSL_OPTS="-Djavax.net.ssl.keystore=$SSL_KEYSTORE -Djavax.net.ssl.keystorePassword=$SSL_KEYSTORE_PW"
      

   2. Add the SSL_OPTS environment variable to the JAVA_OPTS variable.

      JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBARARY_PATH $SSL_OPTS"
      

   3. If the Dashboard keystore is user managed, configure the dashboard’s keystore and trust store locations and passwords in each agent’s properties file with dashboard.connect.keyStore, dashboard.connect.trustStore, dashboard.connect.keyStorePassword, and dashboard.connect.trustStorePassword. Restart each agent after editing its properties file.

7. Restart the dashboard to make the transport configuration effective.

   prompt$ ./tcruntime-ctl.sh myDashboard start
   

Complete any remaining configuration tasks on Master Process: Installation and Configuration Steps before downloading and running the agent installer.

Configure RabbitMQ Transport

This section has instructions for configuring the RabbitMQ dashboard - agent transport.

By default, the Insight Dashboard is configured to communicate with Insight Agents over HTTP. You can configure one additional transport—either Active MQ or RabbitMQ. Note that you cannot define more than one additional transport, and you cannot disable the HTTP transport.

You configure transport behavior in the dashboard properties file.

1. Stop the dashboard instance. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard
   prompt$ ./tcruntime-ctl.sh myDashboard stop
   

2. Copy insight-dashboard-agent-rabbitmq-core-x.x.x.jar and insight-dashboard-agent-rabbitmq-standard-x.x.x.jar from the INSTANCE-DIR/insight/dashboard-plugins/extras/transports directory to the INSTANCE-DIR/insight/dashboard-plugins directory.

   INSTANCE-DIR refers to the tc Server instance directory of the Insight Dashboard, such as /opt/pivotal/pivotal-tc-server-standard-version/myDashboard.

   Note: Make sure that the INSTANCE-DIR/insight/dashboard-plugins does not contain the ActiveMQ transport jar.

3. In INSTANCE-DIR/insight/conf/insight.properties, define the location and credentials of the RabbitMQ broker using the following properties:

   dashboard.rabbitmq.host:
   dashboard.rabbitmq.port:
   dashboard.rabbitmq.username:
   dashboard.rabbitmq.password:
   

4. If you want to use SSL for agent - dashboard communication, proceed to the next step. Otherwise skip to Step 6 of this procedure.

5. To configure the dashboard for SSL communications with the agent:

   1. Configure the RabbitMQ broker for SSL. For more information see SSL Support in the RabbitMQ documentation.

   2. Depending on your RabbitMQ configuration:

      • If Rabbit MQ is configured for “trust-all” SSL, in the dashboard’s properties file, set:

        rabbitmq.ssl.use: true

      • If the RabbitMQ broker is configured to trust only certificates that exist in the broker keystore, in the dashboard’s properties file, set::

        rabbitmq.server.cert
        rabbitmq.client.keyStore
        rabbitmq.client.keyStore.password
        rabbitmq.client.keyStore.format
        

   3. See Insight Dashboard Properties for optional properties, prefixed by “rabbitmq”, that relate to the configuration of the RabbitMQ transport.

6. Restart the dashboard to make the transport configuration effective.

   prompt$ ./tcruntime-ctl.sh myDashboard start
   

Complete any remaining configuration tasks on Master Process: Installation and Configuration Steps before downloading and running the agent installer.

Configure Dashboard Data Management

The following dashboard properties control where the dashboard saves working data and its policies for purging traces, metrics, and resources from its internal database:

See property details at Insight Dashboard Properties.

• insight.data.directory
• insight.purge.internal.min
• metric.max.granularity.sec
• trace.exclude.path
• trace.max.memory.mb
• trace.purge.batch
• trace.purge.expiry.days
• trace.purge.expiry.min
• trace.throughput.max

Configure Agent Defaults

Use the properties in INSTANCE-DIR/insight/conf/agent.override.properties to configure agent behaviors related to what traces are collected and reported to the dashboard, where INSTANCE-DIR refers to the tc Server instance directory of the Insight Dashboard, such as /opt/pivotal/pivotal-tc-server-standard-version/myDashboard. You can throttle trace reporting, exclude applications or portions of applications, and configure other mechanisms to reduce the volume of data collected and reported.

See property details at Insight Dashboard Properties.

Any configuration changes you make in the overrides file will be reflected in the agent installer.

• agent.traces.rate.initial
• application.context.ignore.engine
• insight.collection.aspect.enabled
• insight.collection.collapsing-frame-builder.threshold
• insight.collection.global.excluded.resource.properties.list
• insight.collection.global.filter-unknown-application-traces
• insight.collection.min-operation-duration
• insight.collection.only-endpoints.enabled
• insight.collection.only-endpoints
• insight.collection.min-operation-duration.enabled
• insight.collection.plugins.spring-core.ComponentMethodOperationCollectionAspect.aspect.enabled
• insight.collection.prefix.instrument
• trace.exclude.path
• trace.filter.similar.per.hour
• agent.trace.queues
• agent.trace.digesters
• agent.trace.buffer
• agent.name.override
• application.name.override

Insight Dashboard Properties

You set properties for an Insight Dashboard instance in the insight.properties file for that instance. The properties file for the dashboard is located in the /insight/conf directory of the runtime instance where it runs. For example:

/opt/pivotal/pivotal-tc-server-standard-x.x.x.RELEASE/myDashboard/insight/conf

application.context.ignore.myapp: localhost|my-app
application.context.ignore.manager: localhost|manager

Agent Installation and Configuration Topics

The following topics describe how to install the Insight Agent into an application server (Pivotal tc Server, JBoss, Apache Tomcat, or WebLogic Server) and how to optionally configure it:

• Install Agent Using insight-agent.jar
• Agent Installer Properties
• Install Agent on WebLogic Server
• Install Agent on tc Server Using A Template
• Configure the Insight Agent
• Insight Agent Properties

Install Agent Using insight-agent.jar

This section has instructions for downloading the Insight Agent installer from the dashboard and using it to install the agent. Perform these steps after completing appropriate Dashboard configuration tasks listed in Master Process: Installation and Configuration Steps, so that the installer will be pre-configured with correct transport and other configuration options.

Perform this procedure on each machine that hosts applications you want to monitor. This procedure applies to applications that are deployed on one of the following application servers: Pivotal tc Server, JBoss, and Apache Tomcat. If the applications you want to monitor are deployed on WebLogic Server, see Install Agent on WebLogic Server.

1. If you have not already done so, install the Insight Dashboard in a Pivotal tc Server instance and start the instance. See Install Dashboard Template from ZIP Archive, Create and start Dashboard as required.

2. Open the Insight Dashboard in a web browser using the hostname and port number appropriate for your dashboard. For example:

   http://support.apps.example.com:8080/insight.

3. Log in as an Insight user that has the insight_admin role. The pre-configured administration user is admin with password insight. If you have created additional administration users, you can use their credentials instead.

4. Click the Administration tab in the dashboard user interface.

5. On the Administration page, click the Download Agent option in the Support Tools section on the left.

6. On the agent download page, click the Download Agent button, which is located at the bottom of the page.

   The insight-agent.jar is downloaded.

7. Copy insight-agent.jar from your downloads directory into one of the following directories, depending on the application server you are using to host the applications you want to monitor:

   • Pivotal tc Server: The tc Server instance directory, such as /opt/pivotal/pivotal-tc-server-standard-version/myInstance
   • JBoss: The JBOSS_HOME directory.
   • Apache Tomcat: The CATALINA_HOME directory.

   For example, if you are using Pivotal tc Server:

   prompt$ cp /Users/juliet/Downloads/insight-agent.jar /opt/pivotal/pivotal-tc-server-standard-version/myInstance
   

8. Change directory to directory into which you copied the insight-agent.jar. For example, for tc Server:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard-version/myInstance
   

9. Run the agent installer.

   prompt$ java -jar insight-agent.jar --install --interactive
   

   The --interactive specifies that you want to be prompted for configuration information, such as how to connect to the Insight dashboard. If you want the agent installation to take all default values, omit the --interactive option. Alternatively, you can provide the configuration values at the command line when your run the installer. All command options are defined in Agent Installer Command Options.

   It is assumed in the remainder of this procedure that you are using interactive mode.

10. Enter whether you want to install the Insight agent into the current directory; if you have already copied the JAR file into the directory appropriate for your application server, press Enter. If not, enter N and then enter the full directory of your application server.

11. The Agent installer prompts you to enter the following configuration information about the Insight Dashboard and the application server that is deploying the applications you want to monitor; you can often take the default values:

    • Whether you use a Java service wrapper to start the application server that is deploying the applications you want to monitor, and if so, the full pathname of the wrapper configuration file.
    • Confirmation about the type and version of the application server, such as Pivotal tc Server 3.0.0.
    • The type of transport protocol that the agent should use when communicating with the Dashboard, such as HTTP or HTTPS.
    • The IP address (or host name) and port number where the Insight dashboard is hosted. The default values correspond to the Insight Dashboard from which you downloaded the insight-agent.jar file.
    • The context path of the Insight Dashboard, which by default is insight
    • The username and password that the Insight agent should use when connecting to the Dashboard. The default value is spring/insight, which is one of the two pre-configured users created automatically when you install the Insight Dashboard. You might have created additional users.
    • Whether to use JSON serialization; default is N.
    • Whether communications with the Insight Dashboard will go through a proxy server, and if so, its host and port number.

    If the Insight agent installs successfully, you should see output similar to the following:

     Applying properties from file agent.override.properties 
     Insight agent installed successfully on tcServer 2.9 
    

After installing the agent, see Master Process: Installation and Configuration Steps to determine whether you want to perform additional agent configuration tasks.

Agent Installer Properties

The table below defines the options supported by the insight-agent.jar installer.

Install Agent on WebLogic Server

This section describes how to install the Insight Operations Agent on WebLogic Server.

About the Installation Process

You perform the installation using the insight-agent.jar installer.

For a given WebLogic domain, you install the agent on the machine where the Administration Server runs, and on any other machines that host Managed Servers (within the domain managed by the Administration Server) with applications that you want to monitor. To install the agent on distributed Managed Servers (Managed Servers running on a different machine than the Admin Server), you install the agent on the machine that hosts Managed Servers, using the --weblogic_distributed option to prevent the installer from looking for an Administration Server.

If you run the installer without supplying any command options on a machine that hosts an Administration Server, the installer installs the agent on the Administration Server. To install the agent on Managed Servers on that same host, you specify them at the command line using the --weblogic_target_names option. You can supply a comma-separated list of Managed Servers, or the name of a cluster that contains the target servers. Note that the agent will only be installed on the cluster members that run on the local machine.

If you run the installer with the --interactive option, you are prompted to specify the target servers.

Installer options are defined in Agent Installer Properties.

Notes

• Run the installer from the root folder of the WebLogic Server Domain.
• If you run the installer with no command qualifiers on a machine with an Administration Server and Managed Servers, the agent is installed on the Administration Server, but not on the Managed Servers,.
• If you run the installer with no command qualifiers on a machine with no Administration Server, and some Managed Servers, the installer will not detect the Managed Servers or offer the option to monitor them.
• You do not have to monitor the Administration Server for a domain. If you want to monitor only Managed Servers, not the Administration Server, supply the names of the target servers with the –weblogic_target_names command line option when you run the installer.
• ActiveMQ and RabbitMQ transports are supported for agents managing WebLogic Server.

Prerequisites

Before running insight-agent.jar to install the agent, making any changes to the installation, or uninstalling the agent:

• Stop the WebLogic servers on the machine where you are performing the installation. If the machine hosts the Administration Server for the domain, stop it. If it hosts Managed Servers, stop them.
• Stop the Node Manager on the machine where you are performing the installation.
• Make sure that the account you use to install the agent on the Administration Server machine has write permissions to files in the domain’s /bin and /config folders.
• On each machine where you will install the agent, verify that following property values in /WL_HOME/common/nodemanager/nodemanager.properties:
  • StartScriptEnabled=true
  • StartScriptName=startWebLogic.sh

Procedure - Install Agent on WebLogic Server

For instructions on running the agent installer, see Install Agent Using insight-agent.jar.

1. Verify that the target WebLogic Server instances are shut down.
2. On the command line, change directory to the root folder of the domain on the Administration Server machine.

3. Run the installer and specify the names of the targets to instrument, including any distributed servers.

   You can specify the target names interactively, if you run the agent installer with the -i (interactive) option, or on the command line if you supply the –weblogic_target_names argument when you run the installer. When a cluster name is specified, all local and distributed server names in the cluster are included. Servers that are added or removed from the cluster at a later time are not affected.

4. Restart the Administration Server and the Node Manager service.
Verify that they have completed the restart process.

5. (Optional) Restart the Managed Servers that reside on the Administration Server machine.

6. Using the --weblogic-distributed argument, run the installer on any other machines that have distributed servers that you specified in Step 3. For each distributed machine, specify all target names that are relevant to the distributed machine. If you previously specified a cluster name, you can specify it again, or you can specify the individual server names that are part of the cluster and reside on this machine.

7. Restart the distributed servers that you targeted, using the WebLogic Server Administration Console.

8. The agent is now installed on the target machines.

Example

In the following example, the agent installer is run interactively. Two target servers are specified, one valid, and one invalid. The domain’s Administration Server is called MedRecServer.

Agent installer invocation:

/Oracle/Middleware/wlserver_12.1/samples/domains/medrec# java -jar insight-agent.jar -i


Installer dialog:

Would you like to install Insight agent in the current directory? (/Oracle/Middleware/wlserver_12.1/samples/domains/medrec) Yn: 


Is a java service wrapper used to start the server? yN: 
Detected a WebLogic 12.1.1 Server, is this correct? Yn:

 
=============================================================== 

Installing Insight on WebLogic 12.1.1 

=============================================================== 


Installer JVM: Java HotSpot(TM) 64-Bit Server VM 1.6.0_30 


Please enter the names of the targets in this domain that you would like to instrument, separated by ',' [Default:MedRecServer]: MedRecServer, admin

Successfully edited config.xml file 

Target named: admin is not valid. Will not instrument it. 


Make sure there are no typos and that the target is either of type 'server', or that if it is of type 'cluster' then the cluster contains at least one server. 

Succesfully edited setDomainEnv script

1: HTTP
2: HTTPS


Please select a transport protocol [Default:HTTP]: 


Please enter the Insight IP address or host name [Default:localhost]: 10.23.197.123

Please enter the Insight port number [Default:8080]: 8085


Please enter the Insight context path [Default:insight]: 


Please enter the Insight user name [Default:spring]:


Please enter the Insight password [Default:insight]:


Use JSON serialization yN:


Use proxy yN: 
Insight agent installed successfully on WebLogic 12.1.1 
root@adi-devu:/Oracle/Middleware/wlserver_12.1/samples/domains/medrec#

Install Agent on tc Server Using A Template

The best practice is to install the Insight Agent using the insight-agent.jar installer, as described in Install Agent Using insight-agent.jar. However, if you are going to use Pivotal tc Server to deploy the applications that you want to monitor, you can also use an Insight Agent Template to install the agent into a tc Server instance.

The following procedure describes how to create a new tc Server instance using the Agent template. Where appropriate, it also shows how to update an existing tc Server instance to use the Insight agent template.

1. On the computer on which you want to install the Insight agent into a tc Server instance, log in as tcserver. On Unix, if you have disabled interactive login, log in as the root user and use su - tcserver to become the user.
2. From the Pivotal tc Server product page.
3. Download the Spring Insight Operations Agent ZIP file (insight-pivotal-tc-server-agent-version.zip).

4. Unpack the Insight Agent ZIP file into the templates sub-directory of the tc Server installation directory, such as /opt/pivotal/pivotal-tc-server-standard-version. This in turn will create an insight-agent sub-directory whose full pathname is similar to the following:

   /opt/pivotal/pivotal-tc-server-standard-version/templates/insight-agent

5. In a terminal window, change to the tc Server home directory. For example:

   prompt$ cd /opt/pivotal/pivotal-tc-server-standard-version
   
   

6. Create a tc Server instance with tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) using the -t insight-agent option to specify the Insight agent template. Also specify the --interactive option to be prompted for agent configuration values, such as how to connect to the Insight dashboard; this is necessary when installing the Insight Agent from a tc Server template because the template does not contain information about your specific Insight Dashboard instance. For example, to create an instance named myAgent on a Unix system:

   prompt$ ./tcruntime-instance.sh create -t insight-agent --interactive myAgent
   

   Use the -i directory option of tcruntime-instance to specify a different instance directory from the current installation directory. For example:

   prompt$ ./tcruntime-instance.sh create -i /var/opt/pivotal/pivotal-tc-server-standard -t insight-agent --interactive myAgent
   

   If you have previously created a tc Server instance on which you have already deployed applications that you now want to monitor with Insight, you can use tcruntime-instance.sh apply-template to apply the insight-agent template to the instance:

   prompt$ ./tcruntime-instance.sh apply-template -t insight-agent --interactive myAgent
   

   For information about the tcruntime-instance command and supported command options, see the tcruntime-ctl Command Reference section in Getting Started with tc Server.

7. The tcruntime-instance command in interactive mode prompts you to enter the following configuration information about the new (or updated) tc Server instance and the Insight Dashboard to which the agent will connect:

   • (Unix) The user that starts the instance when using bin/init.d. The default value is the current user. (Prompt appears only for new instances; existing instances has this already configured.)
   • A custom JMX password. The default generated value is usually adequate. (Prompt appears only for new instances; existing instances has this already configured.)
   • The name of the sub-directory of the new tc Server instance that will contain the Insight log files. You must enter a value.
   • The IP address (or host name) and port number where the Insight dashboard is hosted.
   • The type of transport protocol that the agent should use when communicating with the Dashboard, such as HTTP or HTTPS.
   • The context path of the Insight Dashboard, which by default is insight
   • The username and password that the Insight agent should use when connecting to the Dashboard. The default value is spring/insight, which is one of the two pre-configured users created automatically when you install the Insight Dashboard. You might have created additional users.
   • The shutdown port of the new tc Server instance. (Prompt appears only for new instances; existing instances has this already configured.)
   • The JMX, HTTP, and HTTPS ports that the new tc Server instance should use. (Prompt appears only for new instances; existing instances has this already configured.)

   If the tc Server instance was created (or updated) successfully with the Insight agent template, you should the message Instance Created (or Template applied) and a list of properties associated with the instance.

8. Start the new tc Server instance with the tcruntime-ctl.sh or tcruntime-ctl.bat command.

   • On Unix systems:

     prompt$ ./tcruntime-ctl.sh myAgent start
     

   • On a Windows system, install a Windows Service for the instance before you start it the first time. (After that, you can control the service from the Windows services control panel.) Enter these commands to install and start the service:

     prompt> tcruntime-ctl.bat myAgent install
     

     prompt> tcruntime-ctl.bat myAgent start
     

   (For information about the tcruntime-ctl command and supported command options, see the “tcruntime-ctl Command Reference” section in Getting Started with tc Server.)

9. Deploy an application on the new tc Server instance and generate activity. Check the associated Insight Dashboard – if the Insight Agent was correctly configured, you should see trace information about the application activity within a short period of time.

Configure the Insight Agent

Agent Configuration Options

Agent behaviors are controlled by the properties in the agent’s insight-properties file. Typically, you do not need to edit the agent’s properties file.

When you run the Insight Agent installer (insight-agent.jar), it creates the agent’s insight-properties file in accordance with the property settings defined in the dashboard’s configuration files (its insight-properties file, and the agent-override-properties file at the time of installer download.

If you install an agent into a tc Server instance by using the insight agent template, you might need to manually configure some settings, such as SSL-related properties if you want to enable the agent to communicate securely with the dashboard. A procedure for manually configuring SSL for the agent is provided below. For other agent installation options, see the properties listed on Insight Agent Properties.

Configure SSL for Agent

This section has instructions for manually configuring a SSL keystore and truststore for an Insight Agent.

Note: This setup is only necessary only for agents that were created using the Insight agent template, (rather than the Insight agent installer), and must use SSL to communicate with the Dashboard.

The instructions assume you have already performed set up SSL for the Insight Dashboard, as described in Configure ActiveMQ Transport.

1. Copy the dashboard_cert certificate file you exported from the dashboard’s keystore onto the each Agent host computer, or make it available on a network drive or a thumb drive.
2. Change to the directory where you want to create the Insight Agent keystore and truststore files, for example, CATALINA_BASE/conf.

3. Create a keystore for the agent, if one does not already exist.

   keytool -genkey -alias agent -keyalg RSA -keystore agent.keystore
   

4. When prompted, enter the requested information.

   The identification information is encoded into the Agent’s certificate. Make a note of the keystore password you create for later steps. The command creates the agent.keystore file in the current directory.

5. Create a truststore and import the dashboard public certificate into the keystore.

   keytool -import -alias dashboard -keystore agent.truststore -f /full/path/to/dashboard_cert
   

6. Set the Java system properties to specify the location of the agent.keystore file, the location of the agent.truststore file, and the keystore password.

   It is easiest to do this in the INSTANCE-DIR/bin/setenv.sh script. Edit the setenv.sh script and add the following lines before the JAVA_OPTS=... line.

   SSL_KEYSTORE="/full/path/to/agent.keystore" # e.g. "$CATALINA_BASE/conf/agent.keystore"
   SSL_TRUSTSTORE="/full/path/to/agent.trustore" # e.g. "$CATALINA_BASE/conf/agent.truststore"
   SSL_KEYSTORE_PW="keystore_password"
   SSL_OPTS="-Djavax.net.ssl.keystore=$SSL_KEYSTORE -Djavax.net.ssl.truststore=$SSL_TRUSTSTORE \
       -Djavax.net.ssl.keystorePassword=$SSL_KEYSTORE_PW"
   

7. Add the SSL_OPTS environment variable to the JAVA_OPTS variable.

   JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBARARY_PATH $SSL_OPTS"
   

8. To enable these changes, restart the tc Runtime instance.

Insight Agent Properties

You configure an Insight Agent by editing its insight.properties file.

The properties file is in /opt/pivotal/pivotal-tc-server-standard-n.n.n.RELEASE/myInstance/insight/.

Note that each agent has its own properties file.