Installation and Configuration Procedures
- Master Process - Installation and Configuration Steps
- Installation and Configuration Overview
-
Dashboard Installation and Configuration Topics
- 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
- Agent Installation and Configuration Topics
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.
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.
Install Dashboard template. Follow the procedure that applies to your archive format: Install Dashboard Template.
Configure user accounts. Either Configure User Accounts in Insight or Configure Users in LDAP.
Configure HTTP Transport. Configure your own agent accounts; set up SSL or proxy.
Configure another transport. Optional. Either Configure ActiveMQ Transport and Configure RabbitMQ Transport.
Dashboard Data Management. If desired, you can tailor the Dashboard’s data management and purge policies.
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.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.
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.)
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.
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 theroot
user and usesu - tcserver
to become the user.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:
In a terminal window, change to the tc Server home directory. For example:
prompt$ cd /opt/pivotal/pivotal-tc-server-standard-version
Create a tc Server instance with
tcruntime-instance.sh
(Unix) ortcruntime-instance.bat
(Windows), using theinsight-dashboard
template. For example, to create an instance namedmyDashboard
on a Unix system:prompt$ ./tcruntime-instance.sh create -t insight-dashboard myDashboard
Use the
-i directory
option oftcruntime-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 thetcruntime-ctl
Command Reference section in Getting Started with tc Server.Start the Spring Insight Dashboard instance with the
tcruntime-ctl.sh
ortcruntime-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 thetcruntime-ctl
Command Reference section in Getting Started with tc Server.)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
.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.
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>
Edit or add
<user>
elements for the users you wish to authenticate, setting thepassword
,roles
, andusername
attributes for each user. Include theinsight
role for all users and add theinsight_admin
role for users who should have administrator capabilities.Save changes to
tomcat.users
, then restart the Insight Dashboard with thetcruntime-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.
Create a directory called
plugin-config
in theinsight/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
Copy the
insight-dashboard-security-ldap-x.x.x.RELEASE.jar
file from theinsight/extras/ldap
directory to theinsight/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
Copy the
insight-plugin-dashboard-security-ldap.xml
file from theinsight/extras/ldap
directory to theinsight/dashboard-plugins/plugin-config/
directory. For example:prompt$ cp insight/extras/ldap/insight-plugin-dashboard-security-ldap.xml insight/dashboard-plugins/plugin-config
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 eitherinsight-dashboard-security-tcserver.jar
orinsight-dashboard-security-ldap.jar
, but not both.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>
In
insight/dashboard-plugins/plugin-config/insight-plugin-dashboard-security-ldap.xml
, modify beancontextSource
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>
Add
userDN
andpassword
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
andpassword
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>
In the
insightAuthenticationProvider
bean, modify theuserDnPatterns
property to specify your User Base DN.<property name="userDnPatterns"> <list><value>cn={0},ou=Users,o=SpringInsight</value></list> </property>
Modify the first
<constructor-arg>
element of theTransformingLdapAuthoritiesPopulator
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>
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
:
- Set
agent.http.protocol
tohttps
. - If you do not want the dashboard to accept self-signed certificates, uncomment
agent.http.ssl.allow.selfsigned
and set it totrue
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
:
- Set
agent.http.use.proxy
totrue
. - Use
agent.http.proxy.host
to specify the hostname of the proxy server. - Use
agent.http.proxy.port
to specify the listen port of the proxy server. 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.
Stop the dashboard instance. For example:
prompt$ cd /opt/pivotal/pivotal-tc-server-standard prompt$ ./tcruntime-ctl.sh myDashboard stop
Copy the
insight-dashboard-agent-activemq-x.x.x.jar.
plugin from theINSTANCE-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.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
- Uncomment the ActiveMQ-related properties.
- 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.)
- 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.)
If you want to use SSL for agent - dashboard communication, proceed to the next step. Otherwise skip to Step 7 of this procedure.
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.
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
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 aliasdashboard
.Export the dashboard certificate.
prompt$ keytool -export -alias dashboard -keystore dashboard.keystore -file dashboard_cert
At the prompt, enter the keystore password.
The file
dashboard_cert
is created in the current directory.To enable the changes, restart the tc Runtime instance.
Configure location of keystore.
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 thesetenv.sh
script and add these lines above theJAVA_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"
Add the SSL_OPTS environment variable to the
JAVA_OPTS
variable.JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBARARY_PATH $SSL_OPTS"
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
, anddashboard.connect.trustStorePassword
. Restart each agent after editing its properties file.
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.
Stop the dashboard instance. For example:
prompt$ cd /opt/pivotal/pivotal-tc-server-standard prompt$ ./tcruntime-ctl.sh myDashboard stop
Copy
insight-dashboard-agent-rabbitmq-core-x.x.x.jar
andinsight-dashboard-agent-rabbitmq-standard-x.x.x.jar
from theINSTANCE-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 the ActiveMQ transport jar.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:
If you want to use SSL for agent - dashboard communication, proceed to the next step. Otherwise skip to Step 6 of this procedure.
To configure the dashboard for SSL communications with the agent:
- Configure the RabbitMQ broker for SSL. For more information see SSL Support in the RabbitMQ documentation.
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
See Insight Dashboard Properties for optional properties, prefixed by “rabbitmq”, that relate to the configuration of the RabbitMQ transport.
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
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: |
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: |
agent.http.host |
IP address or name of the host server on which the Insight Dashboard tc Server instance is running. Default: |
agent.http.max.conns.per.host |
Default: |
agent.http.max.request.retries |
Default: |
agent.http.password |
Default: |
agent.http.port |
Port that the Insight Dashboard tc Server instance listens on. Default: |
agent.http.protocol |
Default: |
agent.http.proxy.host |
|
agent.http.proxy.port |
Default: |
agent.http.send.json |
Default: |
agent.http.ssl.allow.selfsigned |
false |
agent.http.use.proxy |
false |
agent.http.username |
Default |
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:
|
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 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](#install-properties-file-insight-agent__agent.name.override) property. Default:
(commented out) |
dashboard.activemq.data.dir |
Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default:
(commented out) |
dashboard.activemq.host |
Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default:
(commented out) |
dashboard.activemq.port |
Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default:
(commented out) |
dashboard.activemq.protocol |
Uncomment and define this property if the Dashboard is configured for the ActiveMQ transport. Default:
(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](http://www.rabbitmq.com/ssl.html#enabling-ssl) 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](http://www.rabbitmq.com/ssl.html#enabling-ssl) 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](http://www.rabbitmq.com/ssl.html#enabling-ssl) 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
|
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](http://www.rabbitmq.com/ssl.html#enabling-ssl) in RabbitMQ documentation. |
dashboard.rabbitmq.ssl.keystore |
Optional Dashboard’s keystore. |
dashboard.rabbitmq.ssl.keystore.format |
Optional Default:
|
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:
|
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 Default:
|
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:
|
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:
|
database.username |
Username that the dashboard uses to connect to its internal database.
Default:
|
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:
(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:
(commented out) |
insight.data.dir |
Path to the directory in which Insight saves working data.
Default:
|
insight.purge.interval.min |
Number of minutes between purges.
Default:
|
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:
|
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.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:
|
trace.purge.batch |
Number of traces that the dashboard will purge at a time. Default:
|
trace.purge.expiry.days |
Default:
|
trace.purge.expiry.min |
Default:
|
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:
|
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.
- 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.
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
.Log in as an Insight user that has the
insight_admin
role. The pre-configured administration user isadmin
with passwordinsight
. If you have created additional administration users, you can use their credentials instead.Click the Administration tab in the dashboard user interface.
On the Administration page, click the Download Agent option in the Support Tools section on the left.
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.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
- Pivotal tc Server: The tc Server instance directory, such as
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
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.
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.
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.
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: |
--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:
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: |
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 |
|
--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.
- Verify that the target WebLogic Server instances are shut down.
- On the command line, change directory to the root folder of the domain on the Administration Server machine.
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.Restart the Administration Server and the Node Manager service. Verify that they have completed the restart process.
(Optional) Restart the Managed Servers that reside on the Administration Server machine.
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.Restart the distributed servers that you targeted, using the WebLogic Server Administration Console.
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.
- 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 theroot
user and usesu - tcserver
to become the user. - From the Pivotal tc Server product page.
- Download the Spring Insight Operations Agent ZIP file (
insight-pivotal-tc-server-agent-version.zip
). 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 aninsight-agent
sub-directory whose full pathname is similar to the following:/opt/pivotal/pivotal-tc-server-standard-version/templates/insight-agent
In a terminal window, change to the tc Server home directory. For example:
prompt$ cd /opt/pivotal/pivotal-tc-server-standard-version
Create a tc Server instance with
tcruntime-instance.sh
(Unix) ortcruntime-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 namedmyAgent
on a Unix system:prompt$ ./tcruntime-instance.sh create -t insight-agent --interactive myAgent
Use the
-i directory
option oftcruntime-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 theinsight-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 thetcruntime-ctl
Command Reference section in Getting Started with tc Server.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
(orTemplate applied
) and a list of properties associated with the instance.- (Unix) The user that starts the instance when using
Start the new tc Server instance with the
tcruntime-ctl.sh
ortcruntime-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.)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.
- 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. - Change to the directory where you want to create the Insight Agent keystore and truststore files, for example,
CATALINA_BASE/conf
. Create a keystore for the agent, if one does not already exist.
keytool -genkey -alias agent -keyalg RSA -keystore agent.keystore
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.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
Set the Java system properties to specify the location of the
agent.keystore
file, the location of theagent.truststore
file, and the keystore password.It is easiest to do this in the
INSTANCE-DIR/bin/setenv.sh
script. Edit thesetenv.sh
script and add the following lines before theJAVA_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"
Add the SSL_OPTS environment variable to the
JAVA_OPTS
variable.JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBARARY_PATH $SSL_OPTS"
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.
Property | Description |
---|---|
agent.heartbeat.interval |
Frequency, in seconds, with which the Insight Agent instance sends a heartbeat to Insight Dashboard.
Default:
|
agent.http.conn.manager.timeout |
Default: 10 (in seconds) |
agent.http.context.path |
Default:
|
agent.http.host |
Default:
|
agent.http.max.conns.per.host |
Default: |
agent.http.max.request.retries |
Default: 1 |
agent.http.password |
Default:
|
agent.http.port |
Default:
|
agent.http.protocol |
Default:
|
agent.http.proxy.host |
Default: |
agent.http.proxy.port |
Default:
|
agent.http.send.json |
Default:
|
agent.http.use.proxy |
Default:
|
agent.http.username |
Default:
|
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:
|
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:
|
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:
|
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 For example, if the dashboard’s This filter runs after the Determine an appropriate value for this property by dividing the value Default:
|
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:
where:
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 where:
The following example ignores the Tomcat Manager application, which has the application context
Default:
|
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:
|
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:
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:
|
|
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](#install-properties-file-insight-agent__insight.collection.min-operation-duration) property.
Default:
|
|
When the agent’s [insight.collection.min-operation-duration.enabled](#install-properties-file-insight-agent__insight.collection.min-operation-duration.enabled) property is yes , this property specifies the operation duration threshold, in ms.
Default:
|
|
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, Default:
|
|
When [insight.collection.only-endpoints.enabled](#install-properties-file-insight-agent__insight.collection.only-endpoints.enabled) is set to yes , this property governs what percentage of the agent’s traces will be endpoint-only.
Default:
|
insight.collection.plugins.spring-core.ComponentMethodOperationCollectionAspect.aspect.enabled |
Disable @Component by default, Default: false |
|
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:
where you can specify
Default: none |
insight.transport.type |
The transport used for communication with the agent. Values may be: HTTP , ActiveMQ , or RabbitMQ .
Default: |
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:
|