Install and Configure Insight Developer

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

This section has instructions for installing and configuring Insight Developer, and documents the inisght.properties file.

Install Insight Developer

To install Spring Insight Developer, you install Pivotal tc Server Developer edition, use the Template Repository to retrieve the latest spring-insight-developer template, and then create a new tc Runtime instance using the insight template.

1. From the Pivotal tc Server product page, click Downloads.

2. Download tc Server Developer edition.

3. Create a directory for tc Server, for example:

   /home/tcserver

4. Unpack the tc Server archive into the directory created in the previous step, such that the tc Server home directory is a sub- directory of it, for example:

   /home/tcserver/pivotal-tc-developer-2.x.x.x. 
   

5. Two options can be used to retrieve Spring Insight

   1. You can download the Spring Insight Developer template zip files from the Pivotal tc Server product page and expand into the templates directory.

   2. Retrieve the template using the Template Repository 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-developer
      

6. Create a tc Server instance where Insight will run:

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

   2. Create a tc Server instance with tcruntime-instance.sh or tcruntime-instance.bat, using the insight template.

      For example, to create an instance named "Insight", enter the following command:

      ./tcruntime-instance.sh create Insight -t insight
      

7. Start the new tc Server instance using the tcruntime-ctl.sh or tcruntime-ctl.bat command.

   • On Unix, to start an instance named "Insight":

     ./tcruntime-ctl.sh Insight start
     

   • On Windows, 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.) To install an instance named "Insight" as a Windows service, and then start it :

     tcruntime-ctl.bat Insight install
     

     tcruntime-ctl.bat Insight start 
     

8. Deploy your Web applications to tc Server by copying the WAR files to the webapps directory of the tc runtime instance. If necessary, update conf/server.xml and conf/context.xml files to support the deployed application.

9. Access the Spring Insight Dashboard by opening http://localhost:8080/insight in your browser.

See the Pivotal tc Server 3.x Documentation for more detailed information about installing and configuring tc Server.

Configure Spring Insight

You configure Spring Insight by editing the insight.properties file, located in the insight directory of the tc Runtime instance. For example, the properties file for an instance called insight-instance is tc-server/pivotal-tc-server-developer-x.x.x/insight-instance/insight/insight.properties.

The properties file lists supported properties in property: value form. Comment lines begin with #.

The following table defines the properties you can set in insight.properties.

Table 1. Properties of the insight.properties File

Property and Default Setting	Description
application.context.ignore.identifier	(Optional) Specify application contexts that you want Spring Insight to ignore, and not instrument. (Instrumentation can increase application startup time. ) 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
database.driverClassName	Specifies the class name of the JDBC Driver that Spring Insight uses to connect to the database. Default: org.h2.Driver
database.password	Specifies the password of the user that connects to the database that Spring Insight uses to persist its data. Default: admin
database.url	Specifies the URL of the database that Spring Insight uses to persist its data. Note: Spring Insight bundles the H2 Java SQL database and uses it internally to persist its data. By default, a tc Runtime instance configured with Spring Insight is configured to use the H2 database. Default: jdbc\:h2\:\#{insightConfig.dataDir}/dashboard/dashboard;DB_CLOSE_DELAY\=-1;MVCC\=TRUE
database.username	Specifies the name of the user that connects to the database that Spring Insight uses to persist its data. Default: insight
insight.data.dir	Specifies the full pathname of the directory in which Spring Insight persists its data. Default: INSTANCE_DIR/insight/data.
insight.purge.interval.min	Specifies, in minutes, how frequently Spring Insight purges traces and resources from the database. Default: 30
metric.max.granularity.sec	Specifies, in seconds, the maximum granularity at which Spring Insight aggregates metrics. Spring Insight collects metrics every 15 seconds, and aggregates metric values at various granularities from minute up to the default value of one year. Default: 31,536,000 (one year)
trace.exclude.path.type	This property configures Spring Insight to not save traces for application requests whose performance you do not wish to track, such as requests for static content. You specify the requests to ignore by specifying a pattern (in ant path format) against which requests are matched. Insight does not save traces that match a path specified by trace.exclude.path. Specify each path you wish excluded separately, as shown in the example below. This excerpt from the default insight.properties file excludes traces for requests for content of the following types: .png, .gif, .jpg, .css., and .js: Default: trace.exclude.path.png: /**/*.png trace.exclude.path.gif: /**/*.gif trace.exclude.path.jpg: /**/*.jpg trace.exclude.path.css: /**/*.css trace.exclude.path.js: /**/*.js
trace.purge.batch	Specifies how many traces Spring Insight purges each time it periodically purges traces from the database. Default: 500
trace.max.memory.mb	The 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.expiry.days	Specifies how many days Spring Insight saves traces before purging them from the database. Default: 7
resource.purge.batch	Specifies how many resources Spring Insight purges each time it periodically purges resources from the database. Note that, regardless of the value of this property, Spring Insight only purges resources that are not referenced by any traces. Default: 40

Increasing Memory when Using Spring Insight

When you monitor an application with Spring Insight, you need to take into account the memory requirements of Insight itself. It may be necessary to increase the memory available to tc Runtime to ensure enough memory is available for both the monitored application and Spring Insight. Pivotal recommends 256MB permgen for an application, depending on the complexity. With the Sun JVM, you increase the size of the Permanent Generation using the -XX-MaxPermSize JVM option.

To increase the memory used by tc Runtime, edit the CATALINA_BASE/bin/setenv.sh|bat file, where CATALINA_BASE refers to the root directory of your instance, such as /home/tcserver/pivotal-tc-server-developer-2.x.x.x/insight-instance. The comments in the file itself show examples of setting the JVM options.