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 as tcserver. 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 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 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

Table 2. Insight Dashboard insight.properties File

Property	Description
Agent communication using ActiveMQ. The following properties, prefaced with agent.activemq, specify how an agent connects to the Insight Dashboard using ActiveMQ. If you configure the ActiveMQ transport, the agent installer will write these settings to the agent's insight.properties file. The corresponding dashboard properties, prefaced with dashboard.activemq, are defined later in this table.
agent.activemq.host	Default: localhost
agent.activemq.password	Default: insight
agent.activemq.port	Default: 21234
agent.activemq.protocol	Default: nio
agent.activemq.username	Default: agent
Agent communication using HTTP. The following properties, prefaced with agent.http, specify how an agent connects to the Insight Dashboard using the default HTTP transport. If you configure the HTTP transport, the agent installer will write these settings to the agent's insight.properties file.
agent.http.conn.manager.timeout	Default: 10 (in seconds)
agent.http.context.path	Context path for the Insight Dashboard Web application, used, for example, in the URL to invoke the dashboard in a browser. Default: insight
agent.http.host	IP address or name of the host server on which the Insight Dashboard tc Server instance is running. Default: localhost
agent.http.max.conns.per.host	Default: 5
agent.http.max.request.retries	Default: 0
agent.http.password	Default: insight
agent.http.port	Port that the Insight Dashboard tc Server instance listens on. Default: 8080 for HTTP, 8443 for HTTPS
agent.http.protocol	Default: http
agent.http.proxy.host
agent.http.proxy.port	Default: 80
agent.http.send.json	Default: false
agent.http.ssl.allow.selfsigned	false
agent.http.use.proxy	false
agent.http.username	Default spring
Agent communication using RabbitMQ. The following properties, prefaced with agent.rabbitmq, specify how an agent connects to the Insight Dashboard using RabbitMQ. If you configure the RabbitMQ transport, the agent installer will write these settings to the agent's insight.properties file. The corresponding dashboard properties, prefaced with dashboard.rabbitmq, are defined later in this table.
agent.rabbitmq.host
agent.rabbitmq.port
agent.rabbitmq.vhost
agent.rabbitmq.username
agent.rabbitmq.password
agent.rabbitmq.ssl.keystore
agent.rabbitmq.ssl.keystore.password
agent.rabbitmq.ssl.keystore.format
agent.rabbitmq.ssl.truststore
agent.rabbitmq.ssl.truststore.password
agent.rabbitmq.ssl.truststore.format
agent.rabbitmq.ssl.use
agent.rabbitmq.multiplekeys.use
agent.rabbitmq.routing.key
agent.rabbitmq.exchange
agent.rabbitmq.fanout.exchange
agent.rabbitmq.queue.prefix
agent.rabbitmq.message.delivery.mode
agent.secured.conf	true or false
application.context.ignore.engine	Use to globally (across all Insight Agents) specify application contexts which should not be instrumented by Insight. Removing contexts that do not need Insight will improve startup time of the application. You can specify one or more entries of this form: application.context.ignore.Engine: Host|Context. Examples: application.context.ignore.myapp: localhost|my-app application.context.ignore.manager: localhost|manager
Dashboard communication using ActiveMQ. The following properties, prefaced with dashboard.activemq, configure ActiveMQ dashboard settings. The corresponding agent properties, prefaced with agent.activemq, are defined earlier in this table.
dashboard.activemq.agent.auth.login	Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Username and password an agent instance uses to log in to a dashboard instance. The login portion of the property is the username. The value of the property is the password. The default setting specifies the login name agent and password insight. You can define multiple username/password pairs for agents in the dashboard's properties file. More than one agent can use the same log credentials. Using different accounts for different sets of agents is useful for managing access to the dashboard. The username an agent uses to connect to the dashboard is not the name that appears for it in the dashboard. For information about the agent name, see the agent.name.override property. Default: #dashboard.activemq agent.auth.agent: insight (commented out)
dashboard.activemq.data.dir	Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default: \#{insightConfig.dataDir}/agent (commented out)
dashboard.activemq.host	Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default: localhost (commented out)
dashboard.activemq.port	Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default: 21234 (commented out)
dashboard.activemq.protocol	Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default: nio (commented out)
Dashboard communication using RabbitMQ. The following properties, prefaced with dashboard.rabbitmq, configure Rabbit MQ dashboard settings. The corresponding agent properties, prefaced with agent.rabbitmq, are defined earlier in this table.
dashboard.rabbitmq.client.keystore	Define this property if the RabbitMQ broker is configured to trust only certificates that were added to the broker certificate. The SSL keystore for the RabbitMQ broker clients. For related information see "Trust the Client's Root CA" in Enabling SSL Support in RabbitMQ in RabbitMQ documentation.
dashboard.rabbitmq.client.keystore.format	Define this property if the RabbitMQ broker is configured to trust only certificates that were added to the broker certificate. The client's keystore format. For related information see "Trust the Client's Root CA" in Enabling SSL Support in RabbitMQ in RabbitMQ documentation.
dashboard.rabbitmq.client.keystore.password	Define this property if the RabbitMQ broker is configured to trust only certificates that were added to the broker certificate. The password for the clients keystore. For related information see "Trust the Client's Root CA" in Enabling SSL Support in RabbitMQ in RabbitMQ documentation.
dashboard.rabbitmq.command.queue.message.ttl	Optional Commands time-to-live in milliseconds. Default: 60000
dashboard.rabbitmq.exchange	Optional The exchange the agent will use to send data to the dashboard. Default: default exchange
dashboard.rabbitmq.fanout.exchange	Optional The fanout exchange the dashboard will use to publish commands to the agents. Default: agent.command.exchange
dashboard.rabbitmq.host	Required (for Rabbit MQ transport.) RabbitMQ broker host name or IP address.
dashboard.rabbitmq.multipleKeys.use	Optional Default: agent.command.queue false
dashboard.rabbitmq.password	Required (for Rabbit MQ transport.) Password for agent connecting to the Dashboard.
dashboard.rabbitmq.port	Required (for Rabbit MQ transport.) RabbitMQ broker port number.
dashboard.rabbitmq.routing.key	Optional The routing key which the agents will use to send data to the dashboard. Default:
dashboard.rabbitmq.server.cert	Define this property if the RabbitMQ broker is configured to trust only certificates that were added to the broker certificate. The SSL certificate used by the RabbitMQ broker. For related information see "Trust the Client's Root CA" in Enabling SSL Support in RabbitMQ in RabbitMQ documentation.
dashboard.rabbitmq.ssl.keystore	Optional Dashboard's keystore.
dashboard.rabbitmq.ssl.keystore.format	Optional Default: jks
dashboard.rabbitmq.ssl.keystore.password	Optional Dashboard's keystore password.
dashboard.rabbitmq.ssl.truststore	Optional Dashboard's truststore.
dashboard.rabbitmq.ssl.truststore.format	Optional Dashboard's truststore format. Default: jks
dashboard.rabbitmq.ssl.truststore.password	Optional Dashboard's truststore password.
dashboard.rabbitmq.ssl.use	Optional Connect to the RabbitMQ broker using a SSL schema. To enable "trust-all" SSL connection set this property to true. For more information see Enabling SSL Support in RabbitMQ in RabbitMQ documentation. Default: false
dashboard.rabbitmq.username	Required (for Rabbit MQ transport.) Username for agent connecting to the Dashboard.
dashboard.rabbitmq.vhost	Optional RabbitMQ virtual host to use. Default: default virtual host (/)
database.driverClassName	Class name of the JDBC Driver that Insight uses to connect to its internal database. Default: org.h2.Driver
database.password	Password that the dashboard uses to connect to its internal database. Default: admin
database.url	URL of the dashboard's internal database. Default: dbc\:h2\:\#{insightConfig.dataDir} /dashboard/dashboard; DB_CLOSE_DELAY\=-1;MVCC\=TRUE
database.username	Username that the dashboard uses to connect to its internal database. Default: insight
insight.agent.heartbeater.enabled	The Dashboard heartbeater is disabled to avoid confusion with an actual agent/analyzer.
insight.collection.global.excluded.resource.properties.list	Sensitive resource properties filter used to exclude transmission of specific agent properties to the dashboard. Uncomment and define, as a comma-separated list, Default: a,b,c (commented out)
insight.collection.global.excluded.resource.patterns.list	Sensitive resource properties filter. Uncomment and define, as a comma-separated list of regular expressions, to exclude transmission of matching properties as part of the reported agent resource properties. Default: sysenv.*,sysprop.* (commented out)
insight.data.dir	Path to the directory in which Insight saves working data. Default: INSTANCE_DIR/insight/data
insight.purge.interval.min	Number of minutes between purges. Default: 30
metric.max.granularity.sec	Largest granularity, in seconds, for which Insight will aggregate metrics. Reduce the value to the maximum time frame for which you wish to view aggregated metric values. Default: 31536000 (one year)
resource.purge.batch	Number of resources that will be purged at a time. Default: 40
trace.exclude.path.type	Traces for application requests that you want to exclude based on their matching a specified pattern. Insight will discard traces for matching requests. This allows you to selectively not store trace data that is of no interest. Include this property (on a line of its own) for each pattern you wish to define. The default setting (shown below) excludes a number of static resource types. Default: trace.exclude.path.png: /**/*.png trace.exclude.path.png: /**/*.gif trace.exclude.path.jpg: /**/*.jpg trace.exclude.path.css: /**/*.css trace.exclude.path.js: /**/*.js trace.exclude.path.png: /**/*.ico trace.exclude.path.png: /**/*.jpeg
trace.max.memory.mb	Maximum amount of memory, in MB, that is available for trace storage. When this threshold is reached, traces are randomly removed, with older traces removed first. Default: 40
trace.purge.batch	Number of traces that the dashboard will purge at a time. Default: 500
trace.purge.expiry.days	Default: 7
trace.purge.expiry.min	Default: 10800
trace.throughput.max	Maximum number of traces that the dashboard will receive per minute. If this value, divided by the number of agents reporting to the dashboard is less than the value of an agent's agent.traces.rate.initial property, the calculated value limits the number of traces per minute sent by the agent to the dashboard. Default: 600

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.

Table 3. Agent Installer Command Options

Option	Description	Default
--activemq_host	Insight IP address or host name.	localhost
--activemq_keystore	Path to agent keyStore (required for SSL transport).
--activemq_keystorepass	Password to agent keyStore (required for SSL transport).
--activemq_password	Agent password for connecting to Insight.	insight
--activemq_port	Port number.	21234
--activemq_protocol	Transport protocol [nio, ssl, nio+ssl, tcp].	nio
--activemq_truststore	Path to agent trustStore (required for SSL transport).
--activemq_username	Agent username for connecting to Insight.	agent
--dispatch_accessor	URL to access the analyzer, for example, http://host:port/insight-agent/dispatch.
--dispatch_encoder	URI of the encoder to be used for dispatched data Admin Server only. Json://ignored?prettyPrint=false
--help	Displays help for installer.
--http_context_path	Insight context path (for example: insight).	insight
--http_host	Insight IP address or host name.	localhost
--http_password	Insight password.	insight
--http_port	Insight port number.	HTTP: 8443 HTTPS: 8443
--http_protocol	Insight transport protocol [HTTP, HTTPS].	http
--http_proxy_host	Proxy IP address or host name.
--http_proxy_port	Proxy port number.	80
--http_send_json	Use JSON serialization.	false
--http_use_proxy	Use proxy.	false
--http_username	Insight username.	spring
--https_allow_self_signed	Allow self-signed SSL certificates.	false
--install	Installs a new agent.
-i, --interactive	Interactive mode.
--jboss_profile profile	When you install the agent to a Jboss instance, specifies the JBoss configuration profile for the instance to which the Insight Agent is being deployed. Allowable values include: all default jbossweb-standalone minimal standard Default: default	default
--mode	Instrumentation mode [standalone, integrated]	integrated
--path	Supplies the path to the runtime instance where you want to deploy the agent. This directory contains the runtime's standard subdirectories: /conf, /logs, /webapps, /work, and /temp.	current directory
--rabbitmq_exchange	Exchange name to be used.	<empty>
--rabbitmq_host	RabbitMQ node IP address or host name.
--rabbitmq_keystore	Path to agent key store.
--rabbitmq_keystorepass	Password for agent key store.
--rabbitmq_keystorepass_format	Agent key store format.	JKS
--rabbitmq_message_delivery_mode	Message delivery mode [NON_PERSISTENT, PERSISTENT].	NON_PERSISTENT
--rabbitmq_no_ssl	Connect to RabbitMQ without SSL.
--rabbitmq_password	RabbitMQ password.
--rabbitmq_port	RabbitMQ port number.
--rabbitmq_queue_prefix	Agent temporary queue prefix.
--rabbitmq_routing_key	Routing key value.	command.queue
--rabbitmq_truststore	Path to agent trust store.
--rabbitmq_truststorepass	Password for agent trust store.
--rabbitmq_truststorepass_format	Agent trust store format.	JKS
--rabbitmq_use_ssl_cert	Connect to RabbitMQ over SSL with client certificate.
--rabbitmq_use_ssl_no_cert	Connect to RabbitMQ over SSL without validating the node certificate, and without presenting any client certificate.
--rabbitmq_username	RabbitMQ username.
--rabbitmq_vhost	RabbitMQ virtual host name.
--reinstall	Reinstalls the agent. The installer removes the existing agent installation.
--secure-conf	Limit access to insight.properties file to owner only.
--server_type	Server type [jboss, tcserver, tomcat, tomcatwinsvc, weblogic].	auto-detected
--server_version	Server version.	auto-detected
--service TomcatServiceName	If you are installing the agent to a Tomcat instance that runs on Windows, provides the service name of the Tomcat instance. To determine the service name, select Run from the Windows Start menu, enter services.msc, and click OK.
--target	Target type [agent, analyzer].	agent
--tmpdir	Specifies the full path to the temp directory for the runtime instance to which you are installing the agent.
--tomcat_catalina_base	CATALINA_BASE directory full path (Tomcat only).	same as installation path - CATALINA_HOME
--transport	Transport type [ActiveMQ, RabbitMQ, HTTP].	HTTP
--uninstall	Uninstalls the agent.
--update	Reconfigures the location of the dashboard, credentials for connecting to the agent, and the transport protocol to use for communicating with the dashboard. The installer prompts for updated connection information.
--verbose	Write log messages to console.
--weblogic_config_xml	Path to config.xml file if not running from domain root (WebLogic only).
--weblogic_distributed	Install on distributed machine (WebLogic only).
--weblogic_set_domain_env	Path to setDomainEnv script file if not running from domain root (WebLogic only).
--weblogic_start_weblogic_xml	Path to start WebLogic script if not running from domain root (WebLogic only).
--weblogic_target_names	Names of target in selected domain to instrument, separated by ',' (WebLogic only).	Admin Server only
--wrapper_conf_file	Full path to Java service wrapper configuration file.

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.

Table 4. Insight Agent Properties File

Property	Description
agent.heartbeat.interval	Frequency, in seconds, with which the Insight Agent instance sends a heartbeat to Insight Dashboard. Default: 15
agent.http.conn.manager.timeout	Default: 10 (in seconds)
agent.http.context.path	Default: insight
agent.http.host	Default: localhost
agent.http.max.conns.per.host	Default:
agent.http.max.request.retries	Default: 1
agent.http.password	Default: insight
agent.http.port	Default: 8080
agent.http.protocol	Default: http
agent.http.proxy.host	Default:
agent.http.proxy.port	Default: 80
agent.http.send.json	Default: false
agent.http.use.proxy	Default: false
agent.http.username	Default: spring
agent.name.override	You can use this property to assign a unique, fixed ID for the Insight Agent instance. By default, an agent's name is constructed from the hostname and pid of the Agent's JVM process, so its name is different each time the JVM is restarted. This can be desirable in environments with rapidly changing clusters. If you prefer the agent name to stay the same after JVM restart, use agent.name.override to assign a fixed name. Default: none
agent.http.ssl.allow.selfsigned	Default: false
agent.syncpropertiesbeat.interval	Agent SyncResourcePropertiesCommand interval (in seconds) Default: 1800
agent.trace.buffer	Maximum number of traces to store in memory before analysis. If the agent is not able to process traces quickly enough, additional traces will be dropped and a warning issued. Default: 20000
agent.trace.digesters	Number of threads devoted to processing traces from web applications. Higher values may mean that traces are processed more expediently but this may waste resources. Lower values risk an overflow of agent.trace.buffer. Default: 1
agent.trace.queues	Number of queues for processing traces. (An application threads add traces to a queue for Insight to process.) The total number of traces in all queues should not exceed agent.trace.buffer. Generally, for all traces to be processed immediately, the value of agent.trace.queues should be the same or less than the value of agent.digester.threads. Higher values may reduce contention in the trace queue between application threads. Default: 1
agent.traces.rate.initial	Throttles trace reporting. This property sets the initial maximum number of traces to send per minute to the dashboard. This value sets the maximum rate at which the agent will send traces to the dashboard. Note however, that an agent may send fewer traced per minute than specified by this property. Upon connection to the dashboard, the actual rate is limited by dividing the value of the dashboard's trace.throughput.max property by the number of agents reporting to the dashboard. If the calculated value is less than the value agent.traces.rate.initial, it supersedes it. For example, if the dashboard's trace.throughput.max is 100, and 4 agents are connected, each agent will be throttled to a maximum of 20 traces per minute. This filter runs after the trace.filter.similar.per.hour filter. Ideally the rate or trace reporting will always be less than the value of agent.traces.rate.initial because the prior filter should reduce trace volume be eliminating traces that provide "redundant" information about application behavior. Determine an appropriate value for this property by dividing the value trace.throughput.max by the number of agents that will report to the dashboard. Default: 200
application.name.override	Assign the name by which a monitored application is identified in the Dashboard, rather than the true name of the application (which is the name of .war file, or a name specified in the application's web.xml file.) It is useful to assign an override name to an application if you are monitoring multiple instances of it—so that each instance of the application has a unique name in the Dashboard user interface.) Overrides take the form: application.name.override.host|context: host|context where: The first host|context specifies the actual application host and application context name. The second host|context are the host name and context name to substitute in data forwarded to Insight Dashboard Strip out forward slashes from context names. Add a separate property definition for each application instance you wish to rename. Default: none
application.context.ignore.identifier	Application contexts that you want Insight to ignore, and not instrument. (Instrumentation can increase the time it takes an application to start. ) The default value (shown below) excludes the Insight Agent from being instrumented. The format for this property is application.context.ignore.identifier:hostName|contextName where: identifier is a value that makes the property name unique in the properties file; Insight does not use the value. Specify any identifier that is meaningful to you. hostName identifies the application host. contextName is the URL context that invokes the application. This is generally is the name of the WAR file in which the application is packaged, unless it is otherwise specified in the application's web.xml file. The following example ignores the Tomcat Manager application, which has the application context manager. application.context.ignore.mgr: localhost|manager Default: application.context.ignore.agent: localhost|insight-agent
dashboard.connect.keyStore	If the agent will communicate over SSL with the dashboard, and the dashboard keystore is user-managed, use this property to specify the full path to the dashboard keystore. You do not need to specify this property if you instead configure a self-signed SSL certificate for the dashboard, as described in [Configure ActiveMQ Transport](#install-configure-activemq).
dashboard.connect.trustStore	If the agent will communicate over SSL with the dashboard, and the dashboard keystore is user-managed, use this property to specify the full path to the dashboard trust store. You do not need to specify this property if you instead configure a self-signed SSL certificate for the dashboard, as described in [Configure ActiveMQ Transport](#install-configure-activemq).
dashboard.connect.keyStorePassword	If the agent will communicate over SSL with the dashboard, and the dashboard keystore is user-managed, use this property to specify password for dashboard keystore. You do not need to specify this property if you instead configure a self-signed SSL certificate for the dashboard, as described in [Configure ActiveMQ Transport](#install-configure-activemq).
dashboard.connect.trustStorePassword	If the agent will communicate over SSL with the dashboard, and the dashboard keystore is user-managed, use this property to specify the password for the dashboard truststore. You do not need to specify this property if you instead configure a self-signed SSL certificate for the dashboard, as described in [Configure ActiveMQ Transport](#install-configure-activemq).
insight.collection.aspect.enabled	Enables or disables specific plugin aspects. This strategy differs from the PrefixExcludeCollectionStrategy in that it operates on aspects as opposed to specific instrumented classes and methods. This strategy interacts with the AdviceErrorHandlingAspect to automatically disable plugins that create detectable problems. Default: true
insight.collection.collapsing-frame-builder.threshold	Collapsing frame builder settings. Threshold when to start # collapsing frames. zero = disabled Default: 0 (disabled)
insight.collection.global.excluded.resource.patterns.list	A filter for excluding sensitive resource properties from transmissions to the dashboard. The value is a comma-separated list of regular expressions. Default: sysenv.*,sysprop.* The default value matches Java system properties prefixed with sysprop, and the current environment variable values prefixed with sysenv.
insight.collection.global.excluded.resource.properties.list	A filter for excluding sensitive resource properties from transmissions to the dashboard. The value is comma-separated list of properties names/
insight.collection.global.filter-unknown-application-traces	Filter Unknown application traces. Default: false
insight.collection.min-operation-duration.enabled	Enables the Minimum Operation Duration collection strategy for the agent, which when enabled, causes the agent to collect trace data only for operations whose duration exceeds the length specified by in the agent's insight.collection.min-operation-duration property. Default: true
insight.collection.min-operation-duration	When the agent's insight.collection.min-operation-duration.enabled property is yes, this property specifies the operation duration threshold, in ms. Default: 0
insight.collection.only-endpoints.enabled	Enables the Endpoint Only collection strategy for the agent, which when enabled, causes the agent to collect endpoint-only trace data in a specified percentage of traces it performs. An end-point only trace excludes the activity of resources involved in a request that are not potential end-points. (The Insight plug-in that manages a resource type defines where or not the type is a potential endpoint). The associated agent property, insight.collection.only-endpoints defines what percentage of traces will be endpoint-only, when Endpoint Only tracing is enabled. Default: true
insight.collection.only-endpoints.percent	When insight.collection.only-endpoints.enabled is set to yes, this property governs what percentage of the agent's traces will be endpoint-only. Default: 10
insight.collection.plugins.spring-core.ComponentMethodOperationCollectionAspect.aspect.enabled	Disable @Component by default, Default: false
insight.collection.prefix.instrument	Excludes a package, class, or method from instrumentation. You can specify this property multiple times in the properties file, once for each exclude target. Specify the property in this format: insight.collection.prefix.instrument.package.class.method where you can specify package only to exclude a complete package, package.class to exclude a class, or package.class.method to exclude a particular method. For example: insight.collection.prefix.instrument. com.example excludes all classes and methods in the com.example package. insight.collection.prefix.instrument. com.example.myExampleClass excludes the myExampleClass class in the com.example package. insight.collection.prefix.instrument. com.example.myExampleClassmyMethod excludes the myMethod method in the myExampleClass class in the com.example package. Default: none
insight.transport.type	The transport used for communication with the agent. Values may be: HTTP, ActiveMQ, or RabbitMQ. Default: HTTP
trace.exclude.path	Paths to exclude from tracing (in ant path format)
trace.filter.similar.per.hour	Limits how times per hour the agent will send "similar" traces to the Dashboard. (Two traces are similar if they have the same endpoint, error state, and a similar response time.) Throttling trace volume reduces the volume of retained traces that provide essentially the monitoring results. With the default setting of 12, an agent sends a trace with a given signature once within a 5 minute interval. If you set the value to 4, the agent will send a trace with a given signature only once during a 15 minute interval. Default: 12