table of contents - pivotal software · insight operations now supports three different transports...

12345

3445

TableofContents

TableofContentsAboutSpringInsightOperationsSupportedConfigurationsandSystemRequirementsOverviewofSpringInsightOperationsInstallationandConfigurationProceduresUsingInsightOperationsAgentManagementAPI

©CopyrightPivotalSoftwareInc,2013-2016 1 1.9

AboutSpringInsightOperationsSpringInsightOperationsdescribesSpringInsightconceptsandprovidesinstructionsforconfiguringandusingSpringInsightOperationswithPivotaltcServer.SpringInsightOperations,whichrunswithtcServerSpringEdition,providesin-depthperformancemonitoringofWebapplicationsandtcServerinproductionenvironments.

SupportedConfigurationsandSystemRequirements

OverviewofSpringInsightOperations

InstallationandConfigurationProcedures

UsingInsightOperations

AgentManagementAPI

IntendedAudienceSpringInsightOperationsisintendedforoperationsteamsanddeveloperswhouseSpringInsightOperationstomonitorandtuneWebapplicationsrunningontcServerapplicationserversinproductionenvironments.


SupportedConfigurationsandSystemRequirementsSpringInsightOperationsrunsinJava6,7,and8environmentsandissupportedbytcServerStandardEdition2.1,2.5,2.6,2.7,2.8,2.9,and3.0.Java8issupportedasofversion1.9.2.SR6ofSpringInsightOperations.BothInsightOperationsDashboardandAgentsupporttheconfigurationsdescribedintcServerSupportedConfigurationsandSystemRequirements .Inaddition,InsightOperationsAgentcanruninTomcat7and8,inJBoss5.0.1,5.1.0,6.0.0and6.1.0,andinOracleWebLogicServer10.3.xand12.1.1.

RecommendedBrowsersSpringInsightOperationsperformsbestwhenyouusethefollowingbrowsersorIDE:

GoogleChrome

Safari5orlater

MozillaFirefox3.6orlater

SpringToolSuite

AlthoughSpringInsightwillworkwithMicrosoftInternetExplorer7and8,itsperformancewillnotbeoptimal.Ifyoucannotusearecommendedbrowser,youshouldinstalltheGoogleChromeFrame pluginforInternetExplorer.

StorageRequirementsTheInsightDashboardusesPivotalGemfireandtheJavaSQLdatabaseH2forpersistence.ThustheDashboardrequiresastorageconfigurationtowhichitcaneasilymakerandomreadsandwrites—eitheralocaldiskoraSAN.AlthoughInsightOperationsdoesnotrequirealargeamountofstoragespace,thereadandwritetimesmustbefasterthanthatsupportedbyNFSorotherstoragesolutionsusedtocheaplyconfigurestorageforover-provisionedhosts.

PlatformswhereInsightAgentwillrunrequiremulti-coreprocessors.

MemoryRequirementsfortcRuntimeInstancesSpringInsightmightrequireincreasedmemoryfortcRuntimeinstances.YoumightneedtoincreaseeitherthemaximumheaporthemaximumPermGensizeJVMoptions,orboth.WhenusingInsightwithOpenJDK,astacksizeofatleast256k(-Xss256k)shouldbeused.InOpenJDK1.6,theinstrumentationAPIrequiresalargerstacksizethanwiththeOracleJVM.PivotalisworkingwithOracletoresolvethisissue,butrecommendslargerstacksizesasageneralruleuntilthereisapermanentfix.InsightdoesnotofficiallysupporttheOpenJDK1.6.

ToincreasethememoryavailabletoatcServerinstance:

Editthe CATALINA_BASE/bin/setenv.sh|batfile

.CATALINA_BASEreferstotherootdirectoryofyourinstance,suchas

/opt/pivotal/pivotal-tc-server-standard-x.x.x.RELEASE/insight-instance .ThecommentsinthefileincludeexamplesofsettingtheJVMoptions.


http://tcserver.docs.pivotal.io/docs-tcserver/topics/about-suppconfigstcs.html

http://www.google.com/chromeframe?prefersystemlevel=true

OverviewofSpringInsightOperationsSpringInsightOperationsgivesyoureal-timevisibilityintowebapplicationandtcServerperformanceinproductionenvironments.InsightOperationsgraphsthehealthofapplicationsovertimeandrevealsapplicationandserverproblemsastheyoccur,withdetailedinformationaboutcontributingevents.

FordetailedinformationaboutwhatyoucandowithInsightOperations,seeUsingInsightOperations.

HowSpringInsightOperationsWorksSpringInsightOperationscapturesWebapplicationeventsknownastraces.Atracerepresentsathreadofexecution.ItisusuallystartedbyanHTTPrequestbutcanalsobestartedbyabackgroundjob.Atracecontainsoperations,whichrepresentsignificantpointsintheexecutionofthetrace,forexample,aJDBCqueryortransactioncommit.InsightOperationsusestracedatatocalculatesummaryinformationandtoleadyoutothespecificsofwhyyourapplicationisnotperformingaswellasitshouldbe.

InsightOperationshasatwo-tieredarchitecturethatconsistsofSpringInsightDashboardandSpringInsightAgent;botharewebapplications.SpringInsightAgentrunsineachtcRuntimeinstance(orothersupportedcontainer)wherewebapplicationsyouwanttomonitorrun.Theagentcollectstracedataandsendsittoasingle,dedicatedtcRuntimeinstancerunningSpringInsightDashboard.InsightDashboardenablesyoutomonitorapplicationsacrossallserversandtogetdetailedstatisticsfromindividualservers.Thetwo-tieredarchitectureseparatesthecollectionoftracedatabyInsightAgentfromtheInsightDashboarduserinterface,therebyensuringthatminimaloverheadisaddedtotcRuntimeinstancesthatexecutewebapplications.

HowInsightOperationsControlsDataCollectionandReducesOverheadInsightOperationsprovidesseveralcollectionstrategiestocontrolwhattracesanagentcollects,sothatyoucanreducethevolumeoftracedata,andhencereducetheoverheadofmonitoring:

Endpointsonly.Limitacertainpercentageoftracestoresourcesthatarepotentialendpoints.

Prefixinstrumentation.Selectivelyexcluderesourcesfrominstrumentationatthepackage,classes,ormethodlevel.

Minimumoperationduration.Excludeoperationswhosedurationislessthanaspecifiedthreshold.

CollectionstrategiescanbedefinedforeachInsightAgentinitspropertiesfile;youcanconfigureglobalcollectionstrategysettingsthataffectallagentsfromtheInsightDashboarduserinterface.Thisallowsyoutotemporarilyoverrideselectedcollectionsettingsofallagentsatrun-time.Uponagentrestart,thecollectionstrategiesdefinedinitspropertiesfileagaintakeeffect.SeeEnableandDisableCollectionStrategies.

Agent-DashboardCommunicationInsightOperationsnowsupportsthreedifferenttransportsforagent-dashboardcommunication:HTTP,whichisthedefault,ActiveMQ,andRabbitMQ.Theagentcanonlyuseonetransportatatime.Thedashboardcanusetwotransports,butonemustbeHTTPtransport.

ComparingSpringInsightOperationsandSpringInsightDeveloperSpringInsightOperationsisdesignedtobedeployedoveraclusteroftcRuntimeinstancesorothersupportedcontainersinproductionenvironments.Itiscommerciallysupported.YouinstallInsightAgentineachsupportedcontainerthatisrunningapplicationsyouwishtomonitor.TheInsightAgentcanruninsupportedversionsofJBoss,Tomcat,andWebLogicServer,aswellasintcServer.EachagentreportstoasingleInsightDashboardinstance,whichrunsonadedicatedinstanceoftcServerSpringEdition.ThisconfigurationisdifferentfromInsightDeveloper,inwhichthedashboard,thecollectioninstrumentation,andmonitoredapplicationsallruninthesamecontainer.

SpringInsightDeveloper,packagedasatemplateinPivotaltcServerDeveloperedition,isdesignedforapplicationdevelopment.Itisnotappropriateforproductiondeployments.UnlikeInsightOperations,InsightDeveloperdoesnothaveatwo-tieredarchitecture:asingleInsightapplicationrunsintcServeralongwithmonitoredapplication,andprovidesbothDashboardandcollectionfunctionality.InsightDeveloperplacesgreaterresourcedemandsonthetcRuntimeinstancethanatcRuntimeinstancerunningtheInsightAgentcomponentofSpringInsightOperations.

ThetwoSpringInsightproductshaveasimilardashboarduserinterfaceandcollectsimilarinformation,exceptthatSpringInsightOperationsalsoenablesyoutocollectandviewperformancebyserverandoverallforthecluster.

FordetailsaboutSpringInsightDeveloper,seetheSpringInsightDeveloperdocumentation.


InstallationandConfigurationProceduresThissectionprovidesinstructionsforinstallingandconfiguringSpringInsightOperations.

MasterProcess-InstallationandConfigurationStepsThispagelistsmainstepsintheInsightOperationsinstallationandconfigurationprocesswithlinkstodetailedprocedures.

1. PreparetoinstallInsightOperations.Reviewsystemrequirements.VerifythatthesystemswhereyouwillrunInsightcomponentsconformtothespecificationsinInsightOperationsSupportedConfigurationsandSystemRequirements.Configurelicensing.InsightOperationsislicensedunderPivotaltcServerSpringEdition.Understandtheprocess.SeeInstallationandConfigurationOverview.

2. InstallDashboardtemplate.Followtheprocedurethatappliestoyourarchiveformat:InstallDashboardTemplatefromZIPArchive.

3. CreateandstartDashboard.

4. Configureuseraccounts.EitherConfigureUserAccountsinInsightorConfigureUsersinLDAP.

5. ConfigureHTTPTransport.Configureyourownagentaccounts;setupSSLorproxy.

6. Configureanothertransport.Optional.EitherConfigureActiveMQTransportandConfigureRabbitMQTransport.

7. DashboardDataManagement.Ifdesired,youcantailortheDashboard’sdatamanagementandpurgepolicies.

8. ConfigureInsightAgentdatacollectionandprocessingbehaviors.Asdesired,editthepropertiesin agent.override.properties toconfigureavarietyofagentbehaviorsrelatedtotracecollectionandprocessing.SeeConfigureAgentDefaults.

9. DownloadandRunAgentInstallerInstallAgentUsingInstalleristherecommendedmethodforinstallingtheInsightAgent,asitpre-configurestheagentsperyourdashboardconfiguration.IfyouareusingPivotaltcServertodeployyourapplications,youcanInstallAgentontcServerUsingaTemplate.Inthismethod,theagentwillnotbepre-configuredtoconnecttoyourDashboard;rather,youspecifytherequiredconfigurationinteractivelywhenyoucreateorupdateatcServerinstancewiththeInsightAgenttemplate.

10. TailorInsightAgentconfiguration.Typically,itisunnecessarytoconfiguremostagentproperties.Ifyoudoneedtoeditanagent’spropertiesfiletochangeitsconfiguration,seeConfiguretheInsightAgentandInsightAgentProperties.

InstallationandConfigurationOverview

WhatInsightOperationcomponentsareinstalled,andhow.AnInsightOperationsenvironmentconsistsofanInsightOperationsDashboardandoneormoreInsightOperationsAgentsthatreporttothedashboard.Practicallyspeaking,bothdashboardandagentarewebapplicationsthatruninasupportedapplicationserverinstance.

ThefirstthingyoudoiscreatetheInsightOperationsDashboard—thatis,youcreateatcServerinstanceusingthe insight-dashboard template(whichyougetfromthetcServerdownloadspage).ThedashboardapplicationisautomaticallydeployedtothedashboardtcServerinstance.

Afterconfiguringdashboardandglobalagentbehaviors(settingsthatapplytoallagents)asdescribedjustbelow,youdownloadanagentinstallerfromthedashboardanduseittoinstallanagentthatispre-configuredtoconnecttothedashboardandbehaveasyouspecified.

WhatDashboardandglobalagentbehaviorsyoucanyouconfigure,andhow.ThekeydashboardconfigurationtasksarecreatingaccountsfordashboardusersandInsightAgents.Youneedtoconfigureadashboardkeystore,ifyouintendagentanddashboardtouseSSL.Optionally,youcanconfigureanalternatedashboard-agenttransportmechanism—youcanenabletheDashboardtouseeitherActiveMQorRabbitMQ,inadditiontothedefaultHTTPtransport.

Mostconfigurabledashboardbehaviorsarecontrolledinthedashboard’s insight.properties file.


Youcanalsopre-configuremanyagentbehaviorsinthedashboardpropertiesfile.Inadditiontopropertiesthatgoverndashboardbehavior,thedashboard’s insight.properties filealsocontainsglobalpropertiesthataffectallagents,anddashboardconnectionsettings—basedonhowyouconfiguresuchproperties,theagentinstallerwillconfigurecorrespondingpropertiesintheagent’s insight.properties file.Foralistofproperties,seeInsightDashboardProperties.

Theagentinstallerautomaticallyconfiguresanagent’stracecollectionandprocessingpropertiesbasedonthesettingsinthedashboard’sagent.override.properties file(in pivotal-tc-server-standard-x.x.x.RELEASE/myDashboard/insight/conf .So,ifyouwanttore-configurethesebehaviorsforallagents,editagent.override.properties inadditiontodashboard’s insight-properties file,beforedownloadingtheagentinstaller.

Afteryoueditthedashboard’s insight-properties and agent.override.properties files,youdownloadtheagentinstaller( insight-agent.jar )fromtheDashboarduserinterfacetoeachmachinewithcontainers(supportedversionsoftcServer,JBoss,Tomcat,orWebLogicServer)whereyouhaveapplicationsyouwanttomonitor.

Theagentinstallerrequiresnoinput;itconfigurestheagentbasedonthedashboardpropertiesfiles.Youcanhoweverruntheagentinstallerininteractivemodeifyouwishtosupplyconfigurationpropertiesatthecommandline.ForinstallerinstructionsInstallAgentusinginsight-agent.jar.

Afteragentinstallation,configurationpropertiescanbeviewedandedited,asappropriate,intheagentinstance’s insight/conf/insight.properties file.

Notes:

IntheabsenceofarunningDashboardfromwhichyoucandownloadtheagentinstaller,youcancreateanInsightOperationsAgentbycreateatcserverinstancewiththeagenttemplate.Insuchcases,theagentwillnotbepre-configuredbasedondashboardconfigurationsettings.AnagentcreatedwithatcServertemplatemustbemanuallyconfigured.

ThesectionsthatfollowprovideinstructionsprimarilyforconfigurationtasksthatarerequiredtogettheInsightDashboardandInsightAgentup,running,andtalkingtoeachotheraboutyourwebapplications.Detailedinstructionsarenotprovidedforalloptionalconfigurationtasks.Configurationstepsusuallyincludeeditingconfigurationproperties.ConfigurationpropertiesarelistedinInsightDashboardPropertiesandInsightAgentProperties.

DashboardInstallationandConfigurationTopicsThefollowingtopicsdescribehowtoinstallandconfiguretheSpringInsightdashboardintoaPivotaltcServerinstance:

InstallDashboardTemplatefromZIPArchive

CreateandStartDashboard

ConfigureUserAccountsinInsight

ConfigureUsersinLDAP

ConfigureHTTPTransport

ConfigureActiveMQTransport

ConfigureRabbitMQTransport

ConfigureDashboardDataManagement

ConfigureAgentDefaults

InsightDashboardProperties

InstallDashboardTemplatefromZIPArchiveTheSpringInsightOperationsZIParchivecontainsatemplateforcreatinganInsightDashboardtcServerinstance.Inthisprocedure,youunpackthepackageintothe templates directoryofadedicatedtcServerStandardEditioninstallation,andthencreatetheDashboardinstancewiththenewtemplate.(TheInsightAgentinstallerisbundledwiththedashboard.)

1. Ifyouhavenotalreadydoneso,installPivotaltcServerStandardEditiononthemachinewhereyouwillruntheInsightDashboard.(RefertotheappropriateinstallationtopicinGettingStartedwithPivotaltcServer.)YouwillruntheInsightDashboardinadedicatedtcServerinstance—notinthesamecontainerasyourmonitoredapplications,whichiswhereyouwillinstalltheInsightAgent.

2. OnthecomputeronwhichyouinstalledtcServerandonwhichyouwillrunInsightDashboard,loginas tcserver .OnUnix,ifyouhavedisabledinteractivelogin,loginasthe root useranduse su-tcserver tobecometheuser.

3. FromthePivotaltcServerproductpage .

4. DownloadtheSpringInsightOperationsDashboardZIPfile( insight-pivotal-tc-server-dashboard-version.zip ).


http://network.pivotal.io/products/pivotal-tcserver

5. UnpacktheInsightDashboardZIPfileintothe templates sub-directoryofthetcServerinstallationdirectory,suchas /opt/pivotal/pivotal-tc-server-standard-version .Thisinturnwillcreatean insight-dashboard sub-directorywhosefullpathnameissimilartothefollowing:/opt/pivotal/pivotal-tc-server-standard-version/templates/insight-dashboard

Afterinstallingthedashboardtemplate,CreateandStartDashboard.

CreateandStartDashboardInthisstepyoucreateatcServerinstanceusingthe insight-dashboard template.Theinstanceyoucreatehasthedashboardapplicationpre-deployed,andcontainsadownloadableagentinstaller.

Onthemachinewhereyouinstalledthe insight-dashboard template:

1. Inaterminalwindow,changetothetcServerhomedirectory.Forexample:

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

2. CreateatcServerinstancewith tcruntime-instance.sh (Unix)or tcruntime-instance.bat (Windows),usingthe insight-dashboard template.Forexample,tocreateaninstancenamed myDashboard onaUnixsystem:

prompt$./tcruntime-instance.shcreate-tinsight-dashboardmyDashboard

Usethe -idirectory optionof tcruntime-instance tospecifyadifferentinstancedirectoryfromthecurrentinstallationdirectory.Forexample:

prompt$./tcruntime-instance.shcreate-i/var/opt/pivotal/pivotal-tc-server-standard-tinsight-dashboardmyDashboard

Forinformationaboutthe tcruntime-instance commandandsupportedcommandoptions,seethe“ tcruntime-ctl CommandReference”sectioninGettingStartedwithtcServer.

3. StarttheSpringInsightDashboardinstancewiththe tcruntime-ctl.sh or tcruntime-ctl.bat command.OnUnixsystems:

prompt$./tcruntime-ctl.shmyDashboardstart

OnaWindowssystem,installaWindowsServicefortheinstancebeforeyoustartitthefirsttime.(Afterthat,youcancontroltheservicefromtheWindowsservicescontrolpanel.)Enterthesecommandstoinstallandstarttheservice:

prompt>tcruntime-ctl.batmyDashboardinstall

prompt>tcruntime-ctl.batmyDashboardstart

Forinformationaboutthe tcruntime-ctl commandandsupportedcommandoptions,seethe“ tcruntime-ctl CommandReference”sectioninGettingStartedwithtcServer.)

4. OpentheInsightDashboarduserinterfaceinawebbrowserat http://myDashboardHost:8080/insight .IfyourbrowserisonthesamecomputerastcServer,youcanuse http://localhost:8080/insight .

5. Loginusingoneofthepre-configureduseraccountswithausername-passwordcombinationlistedinthefollowingtable.The insight_admin roleisrequiredtousedashboardadministrativefunctionsandsupporttools,forexample,todownloadtheagentinstaller.Table1.InsightDashboardLoginInformation

Role UserName Password

insight_admin admin insight

insight spring insight

Aftercreatingthedashboard,proceedwithremainingconfigurationtasksonMasterProcess:InstallationandConfigurationSteps.

ConfigureUserAccountsinInsightThissectionhasinstructionsforconfiguringuseraccountswithinInsight.


(Alternatively,tosetupusersinLDAP,seeConfigureUsersinLDAP.)

Thedashboardbydefaultusesthe INSTANCE-DIR/conf/tomcat.users filetoauthenticateusers,where INSTANCE-DIR referstothetcServerinstancedirectoryintowhichtheInsightDashboardisinstalled,suchas /opt/pivotal/pivotal-tc-server-standard-version/myDashboard .Userscanberegularusers( insight role)oradministrators( insight_admin role).The insight_admin roleisrequiredtoperformsomeoperationsontheAdministrationpage.

YoushouldsecureyourSpringInsightOperationsinstallationbychangingthedefaultusersandpasswords.

1. Editthe INSTANCE-DIR/conf/tomcat.users file.Thisistheinitialcontentofthefile:

<?xmlversion="1.0"?><tomcat-users><rolerolename="insight"/><rolerolename="insight_admin"/><userpassword="insight"roles="insight"username="spring"/><userpassword="insight"roles="insight,insight_admin"username="admin"/></tomcat-users>

2. Editoradd <user> elementsfortheusersyouwishtoauthenticate,settingthe password , roles ,and username attributesforeachuser.Includetheinsight roleforallusersandaddthe insight_admin roleforuserswhoshouldhaveadministratorcapabilities.

3. Savechangesto tomcat.users ,thenrestarttheInsightDashboardwiththe tcruntime-ctlrestart command.

Aftercreatingdashboarduser,proceedwithremainingconfigurationtasksonMasterProcess:InstallationandConfigurationSteps.

ConfigureUsersinLDAPIfyouuseLDAP,youcanuseittoauthenticateInsightDashboardusers.TheprocedurebelowisforOpenLDAP.

1. Createadirectorycalled plugin-config inthe insight/dashboard-plugins directoryofyourDashboardtcRuntimeinstance.Forexample:

prompt$cd/opt/pivotal/pivotal-tc-server-standard-n.n.n.RELEASE/myDashboardprompt$mkdirinsight/dashboard-plugins/plugin-config

2. Copythe insight-dashboard-security-ldap-x.x.x.RELEASE.jar filefromthe insight/extras/ldap directorytothe insight/dashboard-plugins directoryofyourDashboardtcRuntimeinstance.Forexample:

prompt$cpinsight/extras/ldap/insight-dashboard-security-ldap-x.x.x.RELEASE.jarinsight/dashboard-plugins

3. Copythe insight-plugin-dashboard-security-ldap.xml filefromthe insight/extras/ldap directorytothe insight/dashboard-plugins/plugin-config/ directory.Forexample:

prompt$cpinsight/extras/ldap/insight-plugin-dashboard-security-ldap.xmlinsight/dashboard-plugins/plugin-config

4. Removethedefault insight-dashboard-security-tcserver.jar.

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

Note:The dashboard-plugins directorymaycontaineither insight-dashboard-security-tcserver.jar or insight-dashboard-security-ldap.jar ,butnotboth.

5. In insight/dashboard-plugins/plugin-config/insight-plugin-dashboard-security-ldap.xml ,checktoseeifthefollowingbeandefinitionsarepresent;iftheyarenot,addthem:

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

6. In insight/dashboard-plugins/plugin-config/insight-plugin-dashboard-security-ldap.xml ,modifybean contextSource topointtoyourownLDAPserver.


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

7. Add userDN and password propertiesthattheDirectoryManagerorotheruserwillusetoconnecttotheLDAPserver.Note:IftheLDAPserverallowsanonymousaccess,youdonotneedtoadd userDN and password properties.

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

8. Inthe insightAuthenticationProvider bean,modifythe userDnPatterns propertytospecifyyourUserBaseDN.

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

9. Modifythefirst <constructor-arg> elementofthe TransformingLdapAuthoritiesPopulator beantopointtoyourGroupBaseDN.

<beanclass="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator"><constructor-argref="contextSource"/><constructor-argvalue="ou=Groups,o=SpringInsight"/><propertyname="groupSearchFilter"value="(|(member={0})(member={1}))"/></bean>

10. SetupthetwoInsightrolesbymodifyingthe map elementofthesecond <constructor-arg> elementtospecifythegroupsforregularInsightusers(Operators)andInsightadministrators(Administrators).

<map><entrykey="Operators"value="insight"/><entrykey="Administrators"value="insight_admin"/></map>

AfterconfiguringLDAPauthentication,proceedwithremainingconfigurationtasksonMasterProcess:InstallationandConfigurationSteps.

ConfigureHTTPTransportBydefault,theInsightDashboardisconfiguredtocommunicatewithInsightAgentsoverHTTP.ThissectionhasinstructionsforoptionalHTTPtransportconfigurations.

Mostoftheinstructionstellyoutoupdatethefile insight.properties ,whichislocatedinthe INSTANCE-DIR/insight/conf directory,where INSTANCE-DIRreferstothedirectoryinwhichthetcServerinstanceislocated,suchas /opt/var/pivotal-tc-server-standard-version .

ConfigureAgentAccounts

WhenanInsightAgentconnectstotheInsightDashboard,itsuppliesausernameandpasswordthatmustmatchanaccountdefinedinthedashboard’sinsight.properties file.Whenyoucreatethedashboardinstanceusingthe insight-dashboard template,bydefaultitwillallowagentstologonoverthedefaultHTTPtransportusingtheusername“spring”andthepassword“insight”.

TocreateanewagentaccountforagentsusingthedefaultHTTPtransport,addthefollowingpropertiestotheINSTANCE-DIR/insight/conf/insight.propertiesfile,replacing username and password withdesiredvalues:

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


ConfigureSSLforHTTPTransport

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

1. Set agent.http.protocol to https .

2. Ifyoudonotwantthedashboardtoacceptself-signedcertificates,uncomment agent.http.ssl.allow.selfsigned andsetitto true

3. RestartthetcServerinstancethathoststheInsightDashboardtomaketheconfigurationeffective.Forexample:

prompt$cd/opt/pivotal/pivotal-tc-server-standard/prompt$./tcruntime-ctl.shmyDashboardrestart

ConfigureProxyServerforHTTPTransport

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

1. Set agent.http.use.proxy to true .

2. Use agent.http.proxy.host tospecifythehostnameoftheproxyserver.

3. Use agent.http.proxy.port tospecifythelistenportoftheproxyserver.

4. RestartthetcServerinstancethathoststheInsightDashboardtomaketheconfigurationeffective.Forexample:

prompt$cd/opt/pivotal/pivotal-tc-server-standard/prompt$./tcruntime-ctl.shmyDashboardrestart

SeeInsightDashboardPropertiesforoptionalproperties,prefixedby“http”,thatrelatetotheconfigurationoftheHTTPtransport.

Agent-DashboadConnectionURL

TheURLthattheagentusestoaccessthedashboardisformedfromtherelatedproperties,likethis:

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

ConfigureActiveMQTransportThissectionhasinstructionsforconfiguringtheActiveMQdashboard-agenttransport.

Bydefault,theInsightDashboardisconfiguredtocommunicatewithInsightAgentsoverHTTP.Youcanconfigureoneadditionaltransport—eitherActiveMQorRabbitMQ.Youcannotdefinemorethanoneadditionaltransport,andyoucannotdisabletheHTTPtransport.

Youconfiguretransportbehaviorinthedashboardpropertiesfile.Notethatthefilecontainsbothdashboardpropertiesandagentproperties(thelatterofwhichtheyet-to-be-downloadedagentinstallerwillusetopopulatetheagent’sownpropertiesfile.

1. Stopthedashboardinstance.Forexample:

prompt$cd/opt/pivotal/pivotal-tc-server-standardprompt$./tcruntime-ctl.shmyDashboardstop

2. Copythe insight-dashboard-agent-activemq-x.x.x.jar. pluginfromthe INSTANCE-DIR/insight/dashboard-plugins/extras/transports directorytothe INSTANCE-

DIR/insight/dashboard-plugins directory:INSTANCE-DIR referstothetcServerinstancedirectoryoftheInsightDashboard,suchas /opt/pivotal/pivotal-tc-server-standard-version/myDashboard .Note:Makesurethatthe INSTANCE-DIR/insight/dashboard-plugins doesnotcontainanyRabbitMQjars.

3. Thisexcerptfrom INSTANCE-DIR/insight/conf/insight.properties ,showsthedashboardandagentpropertiesrelatedtotheActiveMQtransport,uncommented:


#Dashboardproperties:ThesesettingsareusedbythedashboardtoprovideanActiveMQtransport#--------------------dashboard.activemq.protocol:niodashboard.activemq.host:0.0.0.0dashboard.activemq.port:21234dashboard.activemq.data.dir:\#{insightConfig.dataDir}/agentdashboard.activemq.agent.auth.agent:insight.........#Agentproperties:ThesesettingsaretoconnecttothedashboardviaActiveMQ#-----------------agent.activemq.protocol:nioagent.activemq.host:localhostagent.activemq.port:21234agent.activemq.username:agentagent.activemq.password:insight

a. UncommenttheActiveMQ-relatedproperties.b. DefinetheInsightDashboardinsight.propertiesFiledashboard.activemq.agent.auth.loginpropertytoconfigureanewagentaccountlogin

andpassword.(Thistellsthedashboardtoacceptloginsfromthatagentaccount.)c. Definethesamecredentialsfortheagentusingagentproperties:agent.activemq.usernameandagent.activemq.password.(Whenyou

downloadandusetheagentinstalleraftercompletingthisconfiguration,thesepropertieswillbewrittentotheinstalledagent’spropertiesfile.)

4. IfyouwanttouseSSLforagent-dashboardcommunication,proceedtothenextstep.OtherwiseskiptoStep7ofthisprocedure.

5. CreateKeystoreandSelf-SignedCertificateforthedashboard.Performthesestepstocreateakeystoreandcertificateusingthe keytool utilityincludedwiththeSunJDK.Youcanuseanothertool,suchasOpenSSL.Seethedocumentationforyourtoolforthecorrectcommandstouseinthefollowingprocedure.Note:Ifyouhaveauser-managedkeystoreandcertificateforthedashboardthatyouprefertouse,skipthissectionandproceedwithStep6ofthisprocedure.IfyouprefertouseaCA-signedcertificateratherthanaself-signedcertificate,purchaseonefromaCAsuchasVeriSignorThawte.ForhelpcreatingaCertificateSigningRequest(CSR)andimportingthesignedcertificateandtrustedcertificatesintoyourkeystore,seethedocumentationforkeytool .

a. Ifyoudonotalreadyhaveakeystorefile,createonewiththefollowingcommand:

prompt$keytool-genkey-aliasdashboard-keyalgRSA-keystoredashboard.keystore

b. Entertherequestedinformationattheprompts.Thisinformationisencodedintothecertificatethecommandcreates.Makeanoteofthekeypasswordforuseinlatercommands.Thecommandcreatesthefile dashboard.keystore containingoneentrywiththealias dashboard .

c. Exportthedashboardcertificate.

prompt$keytool-export-aliasdashboard-keystoredashboard.keystore-filedashboard_cert

d. Attheprompt,enterthekeystorepassword.Thefile dashboard_cert iscreatedinthecurrentdirectory.

e. Toenablethechanges,restartthetcRuntimeinstance.

6. Configurelocationofkeystore.

a. SettheJavasystempropertiestospecifythelocationofthe dashboard.keystore fileandthekeystorepassword.Itiseasiesttodothisinthe INSTANCE-DIR/bin/setenv.sh script.Editthe setenv.sh scriptandaddtheselinesabovethe 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"

b. AddtheSSL_OPTSenvironmentvariabletothe JAVA_OPTS variable.

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

c. IftheDashboardkeystoreisusermanaged,configurethedashboard’skeystoreandtruststorelocationsandpasswordsineachagent’spropertiesfilewith dashboard.connect.keyStore , dashboard.connect.trustStore , dashboard.connect.keyStorePassword ,and dashboard.connect.trustStorePassword .Restarteachagentaftereditingitspropertiesfile.

7. Restartthedashboardtomakethetransportconfigurationeffective.


http://download.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html


CompleteanyremainingconfigurationtasksonMasterProcess:InstallationandConfigurationStepsbeforedownloadingandrunningtheagentinstaller.

ConfigureRabbitMQTransportThissectionhasinstructionsforconfiguringtheRabbitMQdashboard-agenttransport.

Bydefault,theInsightDashboardisconfiguredtocommunicatewithInsightAgentsoverHTTP.Youcanconfigureoneadditionaltransport—eitherActiveMQorRabbitMQ.Notethatyoucannotdefinemorethanoneadditionaltransport,andyoucannotdisabletheHTTPtransport.

Youconfiguretransportbehaviorinthedashboardpropertiesfile.

1. Stopthedashboardinstance.Forexample:

prompt$cd/opt/pivotal/pivotal-tc-server-standardprompt$./tcruntime-ctl.shmyDashboardstop

2. Copy insight-dashboard-agent-rabbitmq-core-x.x.x.jar and insight-dashboard-agent-rabbitmq-standard-x.x.x.jar fromthe INSTANCE-DIR/insight/dashboard-plugins/extras/transports directorytothe INSTANCE-DIR/insight/dashboard-plugins directory.INSTANCE-DIR referstothetcServerinstancedirectoryoftheInsightDashboard,suchas /opt/pivotal/pivotal-tc-server-standard-version/myDashboard .Note:Makesurethatthe INSTANCE-DIR/insight/dashboard-plugins doesnotcontaintheActiveMQtransportjar.

3. In INSTANCE-DIR/insight/conf/insight.properties ,definethelocationandcredentialsoftheRabbitMQbrokerusingthefollowingproperties:

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

4. IfyouwanttouseSSLforagent-dashboardcommunication,proceedtothenextstep.OtherwiseskiptoStep6ofthisprocedure.

5. ToconfigurethedashboardforSSLcommunicationswiththeagent:

a. ConfiguretheRabbitMQbrokerforSSL.FormoreinformationseeSSLSupport intheRabbitMQdocumentation.b. DependingonyourRabbitMQconfiguration:

IfRabbitMQisconfiguredfor“trust-all”SSL,inthedashboard’spropertiesfile,set:rabbitmq.ssl.use:true

IftheRabbitMQbrokerisconfiguredtotrustonlycertificatesthatexistinthebrokerkeystore,inthedashboard’spropertiesfile,set::

rabbitmq.server.certrabbitmq.client.keyStorerabbitmq.client.keyStore.passwordrabbitmq.client.keyStore.format

c. SeeInsightDashboardPropertiesforoptionalproperties,prefixedby“rabbitmq”,thatrelatetotheconfigurationoftheRabbitMQtransport.

6. Restartthedashboardtomakethetransportconfigurationeffective.


CompleteanyremainingconfigurationtasksonMasterProcess:InstallationandConfigurationStepsbeforedownloadingandrunningtheagentinstaller.

ConfigureDashboardDataManagementThefollowingdashboardpropertiescontrolwherethedashboardsavesworkingdataanditspoliciesforpurgingtraces,metrics,andresourcesfromitsinternaldatabase:

SeepropertydetailsatInsightDashboardProperties.

insight.data.directory


http://www.rabbitmq.com/ssl.html

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

ConfigureAgentDefaultsUsethepropertiesin INSTANCE-DIR/insight/conf/agent.override.properties toconfigureagentbehaviorsrelatedtowhattracesarecollectedandreportedtothedashboard,where INSTANCE-DIR referstothetcServerinstancedirectoryoftheInsightDashboard,suchas/opt/pivotal/pivotal-tc-server-standard-version/myDashboard .Youcanthrottletracereporting,excludeapplicationsorportionsofapplications,andconfigureothermechanismstoreducethevolumeofdatacollectedandreported.

SeepropertydetailsatInsightDashboardProperties.

Anyconfigurationchangesyoumakeintheoverridesfilewillbereflectedintheagentinstaller.

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

InsightDashboardPropertiesYousetpropertiesforanInsightDashboardinstanceinthe insight.properties fileforthatinstance.Thepropertiesfileforthedashboardislocatedinthe/insight/conf directoryoftheruntimeinstancewhereitruns.Forexample:

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

Table2.InsightDashboardinsight.propertiesFile

AgentcommunicationusingActiveMQ.Thefollowingproperties,prefacedwith agent.activemq ,specifyhowanagentconnectstotheInsightDashboardusingActiveMQ.IfyouconfiguretheActiveMQ


transport,theagentinstallerwillwritethesesettingstotheagent’sinsight.properties file.Thecorrespondingdashboardproperties,prefacedwith dashboard.activemq ,aredefinedlaterinthistable.

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

AgentcommunicationusingHTTP.Thefollowingproperties,prefacedwith agent.http ,specifyhowanagentconnectstotheInsightDashboardusingthedefaultHTTPtransport.IfyouconfiguretheHTTPtransport,theagentinstallerwillwritethesesettingstotheagent’sinsight.properties file.

agent.http.conn.manager.timeout Default: 10 (inseconds)

agent.http.context.path

ContextpathfortheInsightDashboardWebapplication,used,forexample,intheURLtoinvokethedashboardinabrowser.Default:insight

agent.http.hostIPaddressornameofthehostserveronwhichtheInsightDashboardtcServerinstanceisrunning.Default: localhost

agent.http.max.conns.per.host Default: 5

agent.http.max.request.retries Default: 0

agent.http.password Default: insight

agent.http.portPortthattheInsightDashboardtcServerinstancelistenson.Default:8080 forHTTP, 8443 forHTTPS

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

AgentcommunicationusingRabbitMQ.Thefollowingproperties,prefacedwith agent.rabbitmq ,specifyhowanagentconnectstotheInsightDashboardusingRabbitMQ.IfyouconfiguretheRabbitMQtransport,theagentinstallerwillwritethesesettingstotheagent’sinsight.properties file.Thecorrespondingdashboardproperties,prefacedwith dashboard.rabbitmq ,aredefinedlaterinthistable.

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 trueorfalse

application.context.ignore.engine

Usetoglobally(acrossallInsightAgents)specifyapplicationcontextswhichshouldnotbeinstrumentedbyInsight.RemovingcontextsthatdonotneedInsightwillimprovestartuptimeoftheapplication.Youcanspecifyoneormoreentriesofthisform:application.context.ignore.Engine: Host|Context. Examples:

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

DashboardcommunicationusingActiveMQ.Thefollowingproperties,prefacedwith dashboard.activemq ,configureActiveMQdashboardsettings.Thecorrespondingagentproperties,prefacedwithagent.activemq ,aredefinedearlierinthistable.

dashboard.activemq.agent.auth.login

UncommentanddefinethispropertyiftheDashboardisconfiguredfortheActiveMQtransport.

Usernameandpasswordanagentinstanceusestologintoadashboardinstance.The login portionofthepropertyistheusername.Thevalueofthepropertyisthepassword.Thedefaultsettingspecifiestheloginnameagent andpassword insight .

Youcandefinemultipleusername/passwordpairsforagentsinthedashboard’spropertiesfile.Morethanoneagentcanusethesamelogcredentials.Usingdifferentaccountsfordifferentsetsofagentsisusefulformanagingaccesstothedashboard.

Theusernameanagentusestoconnecttothedashboardisnotthenamethatappearsforitinthedashboard.Forinformationabouttheagentname,seethe[agent.name.override](#install-properties-file-insight-agent__agent.name.override)property.

Default:

#dashboard.activemqagent.auth.agent:insight

(commentedout)

UncommentanddefinethispropertyiftheDashboardisconfiguredfor


dashboard.activemq.data.dir

theActiveMQtransport.

Default:

\#{insightConfig.dataDir}/agent

(commentedout)

dashboard.activemq.host


Default:

localhost

(commentedout)

dashboard.activemq.port


Default:

21234

(commentedout)

dashboard.activemq.protocol


Default:

nio

(commentedout)

DashboardcommunicationusingRabbitMQ.Thefollowingproperties,prefacedwith dashboard.rabbitmq ,configureRabbitMQdashboardsettings.Thecorrespondingagentproperties,prefacedwithagent.rabbitmq ,aredefinedearlierinthistable.

dashboard.rabbitmq.client.keystore

DefinethispropertyiftheRabbitMQbrokerisconfiguredtotrustonlycertificatesthatwereaddedtothebrokercertificate.TheSSLkeystorefortheRabbitMQbrokerclients.Forrelatedinformationsee“TrusttheClient’sRootCA”in[EnablingSSLSupportinRabbitMQ](http://www.rabbitmq.com/ssl.html#enabling-ssl)inRabbitMQdocumentation.

dashboard.rabbitmq.client.keystore.format

DefinethispropertyiftheRabbitMQbrokerisconfiguredtotrustonlycertificatesthatwereaddedtothebrokercertificate.Theclient’skeystoreformat.Forrelatedinformationsee“TrusttheClient’sRootCA”in[EnablingSSLSupportinRabbitMQ](http://www.rabbitmq.com/ssl.html#enabling-ssl)inRabbitMQdocumentation.

dashboard.rabbitmq.client.keystore.password

DefinethispropertyiftheRabbitMQbrokerisconfiguredtotrustonlycertificatesthatwereaddedtothebrokercertificate.Thepasswordfortheclientskeystore.Forrelatedinformationsee“TrusttheClient’sRootCA”in[EnablingSSLSupportinRabbitMQ](http://www.rabbitmq.com/ssl.html#enabling-ssl)inRabbitMQdocumentation.

dashboard.rabbitmq.command.queue.message.ttl

Optional

Commandstime-to-liveinmilliseconds.

Default:60000


dashboard.rabbitmq.exchange

Optional

Theexchangetheagentwillusetosenddatatothedashboard.

Default:defaultexchange

dashboard.rabbitmq.fanout.exchange

Optional

Thefanoutexchangethedashboardwillusetopublishcommandstotheagents.

Default:agent.command.exchange

dashboard.rabbitmq.host

Required(forRabbitMQtransport.)

RabbitMQbrokerhostnameorIPaddress.

dashboard.rabbitmq.multipleKeys.use

Optional

Default:agent.command.queue

false

dashboard.rabbitmq.password


PasswordforagentconnectingtotheDashboard.

dashboard.rabbitmq.port


RabbitMQbrokerportnumber.

dashboard.rabbitmq.routing.key

Optional

Theroutingkeywhichtheagentswillusetosenddatatothedashboard.

Default:

dashboard.rabbitmq.server.cert

DefinethispropertyiftheRabbitMQbrokerisconfiguredtotrustonlycertificatesthatwereaddedtothebrokercertificate.TheSSLcertificateusedbytheRabbitMQbroker.Forrelatedinformationsee“TrusttheClient’sRootCA”in[EnablingSSLSupportinRabbitMQ](http://www.rabbitmq.com/ssl.html#enabling-ssl)inRabbitMQdocumentation.

dashboard.rabbitmq.ssl.keystore

Optional

Dashboard’skeystore.

dashboard.rabbitmq.ssl.keystore.format

Optional

Default:

jks

dashboard.rabbitmq.ssl.keystore.password

Optional

Dashboard’skeystorepassword.


dashboard.rabbitmq.ssl.truststoreOptional

Dashboard’struststore.

dashboard.rabbitmq.ssl.truststore.format

Optional

Dashboard’struststoreformat.

Default:

jks

dashboard.rabbitmq.ssl.truststore.password

Optional

Dashboard’struststorepassword.

dashboard.rabbitmq.ssl.use

Optional

ConnecttotheRabbitMQbrokerusingaSSLschema.Toenable“trust-all”SSLconnectionsetthispropertyto true .Formoreinformationsee[EnablingSSLSupportinRabbitMQ](http://www.rabbitmq.com/ssl.html#enabling-ssl)inRabbitMQdocumentation.

Default:

false

dashboard.rabbitmq.username


UsernameforagentconnectingtotheDashboard.

dashboard.rabbitmq.vhost

Optional

RabbitMQvirtualhosttouse.

Default:defaultvirtualhost(/)

database.driverClassName

ClassnameoftheJDBCDriverthatInsightusestoconnecttoitsinternaldatabase.

Default:

org.h2.Driver

database.password

Passwordthatthedashboardusestoconnecttoitsinternaldatabase.

Default:

admin

database.url

URLofthedashboard’sinternaldatabase.

Default:

dbc\:h2\:\#{insightConfig.dataDir}

/dashboard/dashboard;

DB_CLOSE_DELAY\=-1;MVCC\=TRUE

Usernamethatthedashboardusestoconnecttoitsinternaldatabase.


database.usernameDefault:

insight

insight.agent.heartbeater.enabledTheDashboardheartbeaterisdisabledtoavoidconfusionwithanactualagent/analyzer.

insight.collection.global.excluded.resource.properties.list

Sensitiveresourcepropertiesfilterusedtoexcludetransmissionofspecificagentpropertiestothedashboard.Uncommentanddefine,asacomma-separatedlist,

Default:

a,b,c

(commentedout)

insight.collection.global.excluded.resource.patterns.list

Sensitiveresourcepropertiesfilter.Uncommentanddefine,asacomma-separatedlistofregularexpressions,toexcludetransmissionofmatchingpropertiesaspartofthereportedagentresourceproperties.

Default:

sysenv.*,sysprop.*

(commentedout)

insight.data.dir

PathtothedirectoryinwhichInsightsavesworkingdata.

Default:

INSTANCE_DIR/insight/data

insight.purge.interval.min

Numberofminutesbetweenpurges.

Default:

30

metric.max.granularity.sec

Largestgranularity,inseconds,forwhichInsightwillaggregatemetrics.Reducethevaluetothemaximumtimeframeforwhichyouwishtoviewaggregatedmetricvalues.

Default:

31536000 (oneyear)

resource.purge.batch

Numberofresourcesthatwillbepurgedatatime.

Default:

40

Tracesforapplicationrequeststhatyouwanttoexcludebasedontheirmatchingaspecifiedpattern.Insightwilldiscardtracesformatchingrequests.Thisallowsyoutoselectivelynotstoretracedatathatisofnointerest.

Includethisproperty(onalineofitsown)foreachpatternyouwishtodefine.


trace.exclude.path.type

Thedefaultsetting(shownbelow)excludesanumberofstaticresourcetypes.

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

Maximumamountofmemory,inMB,thatisavailablefortracestorage.Whenthisthresholdisreached,tracesarerandomlyremoved,witholdertracesremovedfirst.

Default:

40

trace.purge.batch

Numberoftracesthatthedashboardwillpurgeatatime.Default:

500

trace.purge.expiry.days

Default:

7

trace.purge.expiry.min

Default:

10800

trace.throughput.max

Maximumnumberoftracesthatthedashboardwillreceiveperminute.Ifthisvalue,dividedbythenumberofagentsreportingtothedashboardislessthanthevalueofanagent’s agent.traces.rate.initial property,thecalculatedvaluelimitsthenumberoftracesperminutesentbytheagenttothedashboard.

Default:

600

AgentInstallationandConfigurationTopicsThefollowingtopicsdescribehowtoinstalltheInsightAgentintoanapplicationserver(PivotaltcServer,JBoss,ApacheTomcat,orWebLogicServer)andhowtooptionallyconfigureit:

InstallAgentUsinginsight-agent.jar

AgentInstallerProperties

InstallAgentonWebLogicServer

InstallAgentontcServerUsingATemplate

ConfiguretheInsightAgent

InsightAgentProperties


InstallAgentUsinginsight-agent.jarThissectionhasinstructionsfordownloadingtheInsightAgentinstallerfromthedashboardandusingittoinstalltheagent.PerformthesestepsaftercompletingappropriateDashboardconfigurationtaskslistedinMasterProcess:InstallationandConfigurationSteps,sothattheinstallerwillbepre-configuredwithcorrecttransportandotherconfigurationoptions.

Performthisprocedureoneachmachinethathostsapplicationsyouwanttomonitor.Thisprocedureappliestoapplicationsthataredeployedononeofthefollowingapplicationservers:PivotaltcServer,JBoss,andApacheTomcat.IftheapplicationsyouwanttomonitoraredeployedonWebLogicServer,seeInstallAgentonWebLogicServer.

1. Ifyouhavenotalreadydoneso,installtheInsightDashboardinaPivotaltcServerinstanceandstarttheinstance.SeeInstallDashboardTemplatefromZIPArchive,CreateandstartDashboardasrequired.

2. OpentheInsightDashboardinawebbrowserusingthe hostname andportnumberappropriateforyourdashboard.Forexample:http://support.apps.example.com:8080/insight .

3. LoginasanInsightuserthathasthe insight_admin role.Thepre-configuredadministrationuseris admin withpassword insight .Ifyouhavecreatedadditionaladministrationusers,youcanusetheircredentialsinstead.

4. ClicktheAdministrationtabinthedashboarduserinterface.

5. OntheAdministrationpage,clicktheDownloadAgentoptionintheSupportToolssectionontheleft.

6. Ontheagentdownloadpage,clicktheDownloadAgentbutton,whichislocatedatthebottomofthepage.The insight-agent.jar isdownloaded.

7. Copy insight-agent.jar fromyourdownloadsdirectoryintooneofthefollowingdirectories,dependingontheapplicationserveryouareusingtohosttheapplicationsyouwanttomonitor:

PivotaltcServer:ThetcServerinstancedirectory,suchas /opt/pivotal/pivotal-tc-server-standard-version/myInstanceJBoss:The JBOSS_HOME directory.ApacheTomcat:The CATALINA_HOME directory.

Forexample,ifyouareusingPivotaltcServer:

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

8. Changedirectorytodirectoryintowhichyoucopiedthe insight-agent.jar .Forexample,fortcServer:

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

9. Runtheagentinstaller.

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

The --interactive specifiesthatyouwanttobepromptedforconfigurationinformation,suchashowtoconnecttotheInsightdashboard.Ifyouwanttheagentinstallationtotakealldefaultvalues,omitthe --interactive option.Alternatively,youcanprovidetheconfigurationvaluesatthecommandlinewhenyourruntheinstaller.AllcommandoptionsaredefinedinAgentInstallerCommandOptions.Itisassumedintheremainderofthisprocedurethatyouareusinginteractivemode.

10. EnterwhetheryouwanttoinstalltheInsightagentintothecurrentdirectory;ifyouhavealreadycopiedtheJARfileintothedirectoryappropriateforyourapplicationserver,pressEnter.Ifnot,enterNandthenenterthefulldirectoryofyourapplicationserver.

11. TheAgentinstallerpromptsyoutoenterthefollowingconfigurationinformationabouttheInsightDashboardandtheapplicationserverthatisdeployingtheapplicationsyouwanttomonitor;youcanoftentakethedefaultvalues:

WhetheryouuseaJavaservicewrappertostarttheapplicationserverthatisdeployingtheapplicationsyouwanttomonitor,andifso,thefullpathnameofthewrapperconfigurationfile.Confirmationaboutthetypeandversionoftheapplicationserver,suchasPivotaltcServer3.0.0.ThetypeoftransportprotocolthattheagentshouldusewhencommunicatingwiththeDashboard,suchasHTTPorHTTPS.TheIPaddress(orhostname)andportnumberwheretheInsightdashboardishosted.ThedefaultvaluescorrespondtotheInsightDashboardfromwhichyoudownloadedthe insight-agent.jar file.ThecontextpathoftheInsightDashboard,whichbydefaultis insightTheusernameandpasswordthattheInsightagentshouldusewhenconnectingtotheDashboard.Thedefaultvalueis spring/insight ,whichisoneofthetwopre-configureduserscreatedautomaticallywhenyouinstalltheInsightDashboard.Youmighthavecreatedadditionalusers.WhethertouseJSONserialization;defaultis N .WhethercommunicationswiththeInsightDashboardwillgothroughaproxyserver,andifso,itshostandportnumber.


IftheInsightagentinstallssuccessfully,youshouldseeoutputsimilartothefollowing:

Applyingpropertiesfromfileagent.override.propertiesInsightagentinstalledsuccessfullyontcServer2.9

Afterinstallingtheagent,seeMasterProcess:InstallationandConfigurationStepstodeterminewhetheryouwanttoperformadditionalagentconfigurationtasks.

AgentInstallerPropertiesThetablebelowdefinestheoptionssupportedbythe insight-agent.jar installer.

Table3.AgentInstallerCommandOptions

--activemq_host InsightIPaddressorhostname. localhost

--activemq_keystorePathtoagentkeyStore(requiredforSSLtransport).

--activemq_keystorepassPasswordtoagentkeyStore(requiredforSSLtransport).

--activemq_password AgentpasswordforconnectingtoInsight. insight

--activemq_port Portnumber. 21234

--activemq_protocolTransportprotocol[ nio, ssl, nio+ssl, tcp].

nio

--activemq_truststorePathtoagenttrustStore(requiredforSSLtransport).

--activemq_username AgentusernameforconnectingtoInsight. agent

--dispatch_accessorURLtoaccesstheanalyzer,forexample,http://host:port/insight-agent/dispatch.

--dispatch_encoder

URIoftheencodertobeusedfordispatcheddataAdminServeronly.Json://ignored?prettyPrint=false

--help Displayshelpforinstaller.

--http_context_path Insightcontextpath(forexample:insight). insight

--http_host InsightIPaddressorhostname. localhost

--http_password Insightpassword. insight

--http_port Insightportnumber.

HTTP: 8443

HTTPS: 8443

--http_protocol Insighttransportprotocol[ HTTP, HTTPS ]. http

--http_proxy_host ProxyIPaddressorhostname.

--http_proxy_port Proxyportnumber. 80

--http_send_json UseJSONserialization. false

--http_use_proxy Useproxy. false

--http_username Insightusername. spring

--https_allow_self_signed Allowself-signedSSLcertificates. false

--install Installsanewagent.

-i, --interactive Interactivemode.

WhenyouinstalltheagenttoaJbossinstance,specifiestheJBossconfigurationprofilefortheinstancetowhichtheInsightAgentisbeingdeployed.


--jboss_profile profile

Allowablevaluesinclude:

all

default

jbossweb-standalone

minimal

standard

Default:

default

default

--modeInstrumentationmode[standalone, integrated ]

integrated

--path

Suppliesthepathtotheruntimeinstancewhereyouwanttodeploytheagent.

Thisdirectorycontainstheruntime’sstandardsubdirectories: /conf , /logs , /webapps , /work ,and /temp .

currentdirectory

--rabbitmq_exchange Exchangenametobeused. <empty>

--rabbitmq_host RabbitMQnodeIPaddressorhostname.

--rabbitmq_keystore Pathtoagentkeystore.

--rabbitmq_keystorepass Passwordforagentkeystore.

--rabbitmq_keystorepass_format Agentkeystoreformat. JKS

--rabbitmq_message_delivery_modeMessagedeliverymode[NON_PERSISTENT, PERSISTENT ].

NON_PERSISTENT

--rabbitmq_no_ssl ConnecttoRabbitMQwithoutSSL.

--rabbitmq_password RabbitMQpassword.

--rabbitmq_port RabbitMQportnumber.

--rabbitmq_queue_prefix Agenttemporaryqueueprefix.

--rabbitmq_routing_key Routingkeyvalue. command.queue

--rabbitmq_truststore Pathtoagenttruststore.

--rabbitmq_truststorepass Passwordforagenttruststore.

--rabbitmq_truststorepass_format Agenttruststoreformat. JKS

--rabbitmq_use_ssl_certConnecttoRabbitMQoverSSLwithclientcertificate.

--rabbitmq_use_ssl_no_cert

ConnecttoRabbitMQoverSSLwithoutvalidatingthenodecertificate,andwithoutpresentinganyclientcertificate.

--rabbitmq_username RabbitMQusername.

--rabbitmq_vhost RabbitMQvirtualhostname.

--reinstallReinstallstheagent.Theinstallerremovestheexistingagentinstallation.

--secure-confLimitaccesstoinsight.propertiesfiletoowneronly.

--server_type

Servertype[jboss, tcserver, tomcat, tomcatwinsvc,weblogic

].

auto-detected

--server_version Serverversion. auto-detected

IfyouareinstallingtheagenttoaTomcatinstancethatrunsonWindows,providestheservicenameoftheTomcatinstance.


--service TomcatServiceName Todeterminetheservicename,selectRunfromtheWindowsStartmenu,enter services.msc ,andclickOK.

--target Targettype[agent,analyzer]. agent

--tmpdir

Specifiesthefullpathtothetempdirectoryfortheruntimeinstancetowhichyouareinstallingtheagent.

--tomcat_catalina_baseCATALINA_BASEdirectoryfullpath(Tomcatonly).

sameasinstallationpath- CATALINA_HOME

--transport Transporttype[ ActiveMQ, RabbitMQ, HTTP ]. HTTP

--uninstall Uninstallstheagent.

--update

Reconfiguresthelocationofthedashboard,credentialsforconnectingtotheagent,andthetransportprotocoltouseforcommunicatingwiththedashboard.Theinstallerpromptsforupdatedconnectioninformation.

--verbose Writelogmessagestoconsole.

--weblogic_config_xmlPathto config.xml fileifnotrunningfromdomainroot(WebLogiconly).

--weblogic_distributed Installondistributedmachine(WebLogiconly).

--weblogic_set_domain_envPathto setDomainEnv scriptfileifnotrunningfromdomainroot(WebLogiconly).

--weblogic_start_weblogic_xmlPathtostartWebLogicscriptifnotrunningfromdomainroot(WebLogiconly).

--weblogic_target_namesNamesoftargetinselecteddomaintoinstrument,separatedby’,’(WebLogiconly).

AdminServeronly

--wrapper_conf_fileFullpathtoJavaservicewrapperconfigurationfile.

InstallAgentonWebLogicServerThissectiondescribeshowtoinstalltheInsightOperationsAgentonWebLogicServer.

AbouttheInstallationProcess

Youperformtheinstallationusingthe insight-agent.jar installer.

ForagivenWebLogicdomain,youinstalltheagentonthemachinewheretheAdministrationServerruns,andonanyothermachinesthathostManagedServers(withinthedomainmanagedbytheAdministrationServer)withapplicationsthatyouwanttomonitor.ToinstalltheagentondistributedManagedServers(ManagedServersrunningonadifferentmachinethantheAdminServer),youinstalltheagentonthemachinethathostsManagedServers,usingthe --weblogic_distributed optiontopreventtheinstallerfromlookingforanAdministrationServer.

IfyouruntheinstallerwithoutsupplyinganycommandoptionsonamachinethathostsanAdministrationServer,theinstallerinstallstheagentontheAdministrationServer.ToinstalltheagentonManagedServersonthatsamehost,youspecifythematthecommandlineusingthe --weblogic_target_namesoption.Youcansupplyacomma-separatedlistofManagedServers,orthenameofaclusterthatcontainsthetargetservers.Notethattheagentwillonlybeinstalledontheclustermembersthatrunonthelocalmachine.

Ifyouruntheinstallerwiththe --interactive option,youarepromptedtospecifythetargetservers.

InstalleroptionsaredefinedinAgentInstallerProperties.

NotesRuntheinstallerfromtherootfolderoftheWebLogicServerDomain.

IfyouruntheinstallerwithnocommandqualifiersonamachinewithanAdministrationServerandManagedServers,theagentisinstalledonthe


AdministrationServer,butnotontheManagedServers,.

IfyouruntheinstallerwithnocommandqualifiersonamachinewithnoAdministrationServer,andsomeManagedServers,theinstallerwillnotdetecttheManagedServersoroffertheoptiontomonitorthem.

YoudonothavetomonitortheAdministrationServerforadomain.IfyouwanttomonitoronlyManagedServers,nottheAdministrationServer,supplythenamesofthetargetserverswiththe –weblogic_target_names commandlineoptionwhenyouruntheinstaller.

ActiveMQandRabbitMQtransportsaresupportedforagentsmanagingWebLogicServer.

Prerequisites

Beforerunning insight-agent.jar toinstalltheagent,makinganychangestotheinstallation,oruninstallingtheagent:

StoptheWebLogicserversonthemachinewhereyouareperformingtheinstallation.IfthemachinehoststheAdministrationServerforthedomain,stopit.IfithostsManagedServers,stopthem.

StoptheNodeManageronthemachinewhereyouareperformingtheinstallation.

MakesurethattheaccountyouusetoinstalltheagentontheAdministrationServermachinehaswritepermissionstofilesinthedomain’s /bin and/config folders.

Oneachmachinewhereyouwillinstalltheagent,verifythatfollowingpropertyvaluesin /WL_HOME/common/nodemanager/nodemanager.properties :

StartScriptEnabled=true

StartScriptName=startWebLogic.sh

Procedure-InstallAgentonWebLogicServer

Forinstructionsonrunningtheagentinstaller,seeInstallAgentUsinginsight-agent.jar.

1. VerifythatthetargetWebLogicServerinstancesareshutdown.

2. Onthecommandline,changedirectorytotherootfolderofthedomainontheAdministrationServermachine.

3. Runtheinstallerandspecifythenamesofthetargetstoinstrument,includinganydistributedservers.Youcanspecifythetargetnamesinteractively,ifyouruntheagentinstallerwiththe -i (interactive)option,oronthecommandlineifyousupplythe –weblogic_target_names argumentwhenyouruntheinstaller.Whenaclusternameisspecified,alllocalanddistributedservernamesintheclusterareincluded.Serversthatareaddedorremovedfromtheclusteratalatertimearenotaffected.

4. RestarttheAdministrationServerandtheNodeManagerservice. Verifythattheyhavecompletedtherestartprocess.

5. (Optional)RestarttheManagedServersthatresideontheAdministrationServermachine.

6. Usingthe --weblogic-distributed argument,runtheinstalleronanyothermachinesthathavedistributedserversthatyouspecifiedinStep3.Foreachdistributedmachine,specifyalltargetnamesthatarerelevanttothedistributedmachine.Ifyoupreviouslyspecifiedaclustername,youcanspecifyitagain,oryoucanspecifytheindividualservernamesthatarepartoftheclusterandresideonthismachine.

7. Restartthedistributedserversthatyoutargeted,usingtheWebLogicServerAdministrationConsole.

8. Theagentisnowinstalledonthetargetmachines.

Example

Inthefollowingexample,theagentinstallerisruninteractively.Twotargetserversarespecified,onevalid,andoneinvalid.Thedomain’sAdministrationServeriscalled MedRecServer .

Agentinstallerinvocation:

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

Installerdialog:

WouldyouliketoinstallInsightagentinthecurrentdirectory?(/Oracle/Middleware/wlserver_12.1/samples/domains/medrec)Yn:


Isajavaservicewrapperusedtostarttheserver?yN: DetectedaWebLogic12.1.1Server,isthiscorrect?Yn:

=============================================================== InstallingInsightonWebLogic12.1.1===============================================================

InstallerJVM:JavaHotSpot(TM)64-BitServerVM1.6.0_30

Pleaseenterthenamesofthetargetsinthisdomainthatyouwouldliketoinstrument,separatedby','[Default:MedRecServer]:MedRecServer,admin

Successfullyeditedconfig.xmlfile

Targetnamed:adminisnotvalid.Willnotinstrumentit.

Makesuretherearenotyposandthatthetargetiseitheroftype'server',orthatifitisoftype'cluster'thentheclustercontainsatleastoneserver.SuccesfullyeditedsetDomainEnvscript

1:HTTP 2:HTTPS

Pleaseselectatransportprotocol[Default:HTTP]:

PleaseentertheInsightIPaddressorhostname[Default:localhost]:10.23.197.123

PleaseentertheInsightportnumber[Default:8080]:8085

PleaseentertheInsightcontextpath[Default:insight]:

PleaseentertheInsightusername[Default:spring]:

PleaseentertheInsightpassword[Default:insight]:

UseJSONserializationyN:

UseproxyyN: InsightagentinstalledsuccessfullyonWebLogic12.1.1 root@adi-devu:/Oracle/Middleware/wlserver_12.1/samples/domains/medrec#

InstallAgentontcServerUsingATemplateThebestpracticeistoinstalltheInsightAgentusingthe insight-agent.jar installer,asdescribedinInstallAgentUsinginsight-agent.jar.However,ifyouaregoingtousePivotaltcServertodeploytheapplicationsthatyouwanttomonitor,youcanalsouseanInsightAgentTemplatetoinstalltheagentintoatcServerinstance.

ThefollowingproceduredescribeshowtocreateanewtcServerinstanceusingtheAgenttemplate.Whereappropriate,italsoshowshowtoupdateanexistingtcServerinstancetousetheInsightagenttemplate.

1. OnthecomputeronwhichyouwanttoinstalltheInsightagentintoatcServerinstance,loginas tcserver .OnUnix,ifyouhavedisabledinteractivelogin,loginasthe root useranduse su - tcserver tobecometheuser.

2. FromthePivotaltcServerproductpage .

3. DownloadtheSpringInsightOperationsAgentZIPfile( insight-pivotal-tc-server-agent-version.zip ).

4. UnpacktheInsightAgentZIPfileintothe templates sub-directoryofthetcServerinstallationdirectory,suchas /opt/pivotal/pivotal-tc-server-standard-version .Thisinturnwillcreatean insight-agent sub-directorywhosefullpathnameissimilartothefollowing:/opt/pivotal/pivotal-tc-server-standard-version/templates/insight-agent

5. Inaterminalwindow,changetothetcServerhomedirectory.Forexample:

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

6. CreateatcServerinstancewith tcruntime-instance.sh (Unix)or tcruntime-instance.bat (Windows)usingthe -tinsight-agent optiontospecifytheInsightagenttemplate.Alsospecifythe --interactive optiontobepromptedforagentconfigurationvalues,suchashowtoconnecttotheInsightdashboard;thisisnecessarywheninstallingtheInsightAgentfromatcServertemplatebecausethetemplatedoesnotcontaininformationaboutyourspecificInsightDashboardinstance.Forexample,tocreateaninstancenamed myAgent onaUnixsystem:

prompt$./tcruntime-instance.shcreate-tinsight-agent--interactivemyAgent

Usethe -idirectory optionof tcruntime-instance tospecifyadifferentinstancedirectoryfromthecurrentinstallationdirectory.Forexample:

prompt$./tcruntime-instance.shcreate-i/var/opt/pivotal/pivotal-tc-server-standard-tinsight-agent--interactivemyAgent


http://network.pivotal.io/products/pivotal-tcserver

IfyouhavepreviouslycreatedatcServerinstanceonwhichyouhavealreadydeployedapplicationsthatyounowwanttomonitorwithInsight,youcanuse tcruntime-instance.shapply-template toapplythe insight-agent templatetotheinstance:

prompt$./tcruntime-instance.shapply-template-tinsight-agent--interactivemyAgent

Forinformationaboutthe tcruntime-instance commandandsupportedcommandoptions,seethe“ tcruntime-ctl CommandReference”sectioninGettingStartedwithtcServer.

7. The tcruntime-instance commandininteractivemodepromptsyoutoenterthefollowingconfigurationinformationaboutthenew(orupdated)tcServerinstanceandtheInsightDashboardtowhichtheagentwillconnect:

(Unix)Theuserthatstartstheinstancewhenusing bin/init.d .Thedefaultvalueisthecurrentuser.(Promptappearsonlyfornewinstances;existinginstanceshasthisalreadyconfigured.)AcustomJMXpassword.Thedefaultgeneratedvalueisusuallyadequate.(Promptappearsonlyfornewinstances;existinginstanceshasthisalreadyconfigured.)Thenameofthesub-directoryofthenewtcServerinstancethatwillcontaintheInsightlogfiles.Youmustenteravalue.TheIPaddress(orhostname)andportnumberwheretheInsightdashboardishosted.ThetypeoftransportprotocolthattheagentshouldusewhencommunicatingwiththeDashboard,suchasHTTPorHTTPS.ThecontextpathoftheInsightDashboard,whichbydefaultis insightTheusernameandpasswordthattheInsightagentshouldusewhenconnectingtotheDashboard.Thedefaultvalueis spring/insight ,whichisoneofthetwopre-configureduserscreatedautomaticallywhenyouinstalltheInsightDashboard.Youmighthavecreatedadditionalusers.TheshutdownportofthenewtcServerinstance.(Promptappearsonlyfornewinstances;existinginstanceshasthisalreadyconfigured.)TheJMX,HTTP,andHTTPSportsthatthenewtcServerinstanceshoulduse.(Promptappearsonlyfornewinstances;existinginstanceshasthisalreadyconfigured.)

IfthetcServerinstancewascreated(orupdated)successfullywiththeInsightagenttemplate,youshouldthemessage InstanceCreated (or Templateapplied )andalistofpropertiesassociatedwiththeinstance.

8. StartthenewtcServerinstancewiththe tcruntime-ctl.sh or tcruntime-ctl.bat command.OnUnixsystems:

prompt$./tcruntime-ctl.shmyAgentstart

OnaWindowssystem,installaWindowsServicefortheinstancebeforeyoustartitthefirsttime.(Afterthat,youcancontroltheservicefromtheWindowsservicescontrolpanel.)Enterthesecommandstoinstallandstarttheservice:

prompt>tcruntime-ctl.batmyAgentinstall

prompt>tcruntime-ctl.batmyAgentstart

(Forinformationaboutthe tcruntime-ctl commandandsupportedcommandoptions,seethe“ tcruntime-ctl CommandReference”sectioninGettingStartedwithtcServer.)

9. DeployanapplicationonthenewtcServerinstanceandgenerateactivity.ChecktheassociatedInsightDashboard–iftheInsightAgentwascorrectlyconfigured,youshouldseetraceinformationabouttheapplicationactivitywithinashortperiodoftime.

ConfiguretheInsightAgent

AgentConfigurationOptions

Agentbehaviorsarecontrolledbythepropertiesintheagent’s insight-properties file.Typically,youdonotneedtoedittheagent’spropertiesfile.

WhenyouruntheInsightAgentinstaller( insight-agent.jar ),itcreatestheagent’s insight-properties fileinaccordancewiththepropertysettingsdefinedinthedashboard’sconfigurationfiles(its insight-properties file,andthe agent-override-properties fileatthetimeofinstallerdownload.

IfyouinstallanagentintoatcServerinstancebyusingtheinsightagenttemplate,youmightneedtomanuallyconfiguresomesettings,suchasSSL-relatedpropertiesifyouwanttoenabletheagenttocommunicatesecurelywiththedashboard.AprocedureformanuallyconfiguringSSLfortheagentisprovidedbelow.Forotheragentinstallationoptions,seethepropertieslistedonInsightAgentProperties.


ConfigureSSLforAgent

ThissectionhasinstructionsformanuallyconfiguringaSSLkeystoreandtruststoreforanInsightAgent.

Note:ThissetupisonlynecessaryonlyforagentsthatwerecreatedusingtheInsightagenttemplate,(ratherthantheInsightagentinstaller),andmustuseSSLtocommunicatewiththeDashboard.

TheinstructionsassumeyouhavealreadyperformedsetupSSLfortheInsightDashboard,asdescribedinConfigureActiveMQTransport.

1. Copythe dashboard_cert certificatefileyouexportedfromthedashboard’skeystoreontotheeachAgenthostcomputer,ormakeitavailableonanetworkdriveorathumbdrive.

2. ChangetothedirectorywhereyouwanttocreatetheInsightAgentkeystoreandtruststorefiles,forexample, CATALINA_BASE/conf .

3. Createakeystorefortheagent,ifonedoesnotalreadyexist.

keytool-genkey-aliasagent-keyalgRSA-keystoreagent.keystore

4. Whenprompted,entertherequestedinformation.TheidentificationinformationisencodedintotheAgent’scertificate.Makeanoteofthekeystorepasswordyoucreateforlatersteps.Thecommandcreatesthe agent.keystore fileinthecurrentdirectory.

5. Createatruststoreandimportthedashboardpubliccertificateintothekeystore.

keytool-import-aliasdashboard-keystoreagent.truststore-f/full/path/to/dashboard_cert

6. SettheJavasystempropertiestospecifythelocationofthe agent.keystore file,thelocationofthe agent.truststore file,andthekeystorepassword.Itiseasiesttodothisinthe INSTANCE-DIR/bin/setenv.sh script.Editthe setenv.sh scriptandaddthefollowinglinesbeforethe 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. AddtheSSL_OPTSenvironmentvariabletothe JAVA_OPTS variable.

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

8. Toenablethesechanges,restartthetcRuntimeinstance.

InsightAgentPropertiesYouconfigureanInsightAgentbyeditingits insight.properties file.

Thepropertiesfileisin /opt/pivotal/pivotal-tc-server-standard-n.n.n.RELEASE/myInstance/insight/.

Notethateachagenthasitsownpropertiesfile.

Table4.InsightAgentPropertiesFile

agent.heartbeat.interval

Frequency,inseconds,withwhichtheInsightAgentinstancesendsaheartbeattoInsightDashboard.

Default:

15

agent.http.conn.manager.timeout Default: 10 (inseconds)

agent.http.context.path

Default:

insight

Default:


agent.http.host 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

Youcanusethispropertytoassignaunique,fixedIDfortheInsightAgentinstance.Bydefault,anagent’snameisconstructedfromthehostnameandpidoftheAgent’sJVMprocess,soitsnameisdifferenteachtimetheJVMisrestarted.Thiscanbedesirableinenvironmentswithrapidlychangingclusters.IfyouprefertheagentnametostaythesameafterJVMrestart,use agent.name.override toassignafixedname.

Default:

none

agent.http.ssl.allow.selfsigned

Default:

false

agent.syncpropertiesbeat.intervalAgentSyncResourcePropertiesCommandinterval(inseconds)Default:1800

agent.trace.buffer

Maximumnumberoftracestostoreinmemorybeforeanalysis.Iftheagentisnotabletoprocesstracesquicklyenough,additionaltraceswillbedroppedandawarningissued.

Default:

20000

Numberofthreadsdevotedtoprocessingtracesfromwebapplications.Highervaluesmaymeanthattracesareprocessedmoreexpedientlybutthismaywasteresources.Lowervaluesriskanoverflowofagent.trace.buffer .


agent.trace.digesters Default:

1

agent.trace.queues

Numberofqueuesforprocessingtraces.(AnapplicationthreadsaddtracestoaqueueforInsighttoprocess.)Thetotalnumberoftracesinallqueuesshouldnotexceed agent.trace.buffer .Generally,foralltracestobeprocessedimmediately,thevalueof agent.trace.queues shouldbethesameorlessthanthevalueof agent.digester.threads .

Highervaluesmayreducecontentioninthetracequeuebetweenapplicationthreads.

Default:

1

agent.traces.rate.initial

Throttlestracereporting.Thispropertysetstheinitialmaximumnumberoftracestosendperminutetothedashboard.Thisvaluesetsthemaximumrateatwhichtheagentwillsendtracestothedashboard.

Notehowever,thatanagentmaysendfewertracedperminutethanspecifiedbythisproperty.Uponconnectiontothedashboard,theactualrateislimitedbydividingthevalueofthedashboard’s trace.throughput.maxpropertybythenumberofagentsreportingtothedashboard.Ifthecalculatedvalueislessthanthevalue agent.traces.rate.initial ,itsupersedesit.

Forexample,ifthedashboard’s trace.throughput.max is100,and4agentsareconnected,eachagentwillbethrottledtoamaximumof20tracesperminute.

Thisfilterrunsafterthe trace.filter.similar.per.hour filter.Ideallytherateortracereportingwillalwaysbelessthanthevalueof agent.traces.rate.initialbecausethepriorfiltershouldreducetracevolumebeeliminatingtracesthatprovide“redundant”informationaboutapplicationbehavior.

Determineanappropriatevalueforthispropertybydividingthevaluetrace.throughput.max bythenumberofagentsthatwillreporttothedashboard.

Default:

200

application.name.override

AssignthenamebywhichamonitoredapplicationisidentifiedintheDashboard,ratherthanthetruenameoftheapplication(whichisthenameof .war file,oranamespecifiedintheapplication’s web.xmlfile.)

Itisusefultoassignanoverridenametoanapplicationifyouaremonitoringmultipleinstancesofit—sothateachinstanceoftheapplicationhasauniquenameintheDashboarduserinterface.)

Overridestaketheform:

application.name.override.host|context:host|context

where:

Thefirst host|context specifiestheactualapplicationhostandapplicationcontextname.

Thesecond host|context arethehostnameandcontextnametosubstituteindataforwardedtoInsightDashboard

Stripoutforwardslashesfromcontextnames.Addaseparateproperty


definitionforeachapplicationinstanceyouwishtorename.

Default:

none

application.context.ignore.identifier

ApplicationcontextsthatyouwantInsighttoignore,andnotinstrument.(Instrumentationcanincreasethetimeittakesanapplicationtostart.)

Thedefaultvalue(shownbelow)excludestheInsightAgentfrombeinginstrumented.

Theformatforthispropertyisapplication.context.ignore.identifier:hostName|contextName

where:

identifier isavaluethatmakesthepropertynameuniqueinthepropertiesfile;Insightdoesnotusethevalue.Specifyanyidentifierthatismeaningfultoyou.

hostName identifiestheapplicationhost.

contextName istheURLcontextthatinvokestheapplication.ThisisgenerallyisthenameoftheWARfileinwhichtheapplicationispackaged,unlessitisotherwisespecifiedintheapplication’sweb.xml file.

ThefollowingexampleignorestheTomcatManagerapplication,whichhastheapplicationcontext manager .

application.context.ignore.mgr:localhost|manager

Default:

application.context.ignore.agent:localhost|insight-agent

dashboard.connect.keyStore

IftheagentwillcommunicateoverSSLwiththedashboard,andthedashboardkeystoreisuser-managed,usethispropertytospecifythefullpathtothedashboardkeystore.

Youdonotneedtospecifythispropertyifyouinsteadconfigureaself-signedSSLcertificateforthedashboard,asdescribedin[ConfigureActiveMQTransport](#install-configure-activemq).

dashboard.connect.trustStore

IftheagentwillcommunicateoverSSLwiththedashboard,andthedashboardkeystoreisuser-managed,usethispropertytospecifythefullpathtothedashboardtruststore.


dashboard.connect.keyStorePassword

IftheagentwillcommunicateoverSSLwiththedashboard,andthedashboardkeystoreisuser-managed,usethispropertytospecifypasswordfordashboardkeystore.


dashboard.connect.trustStorePassword

IftheagentwillcommunicateoverSSLwiththedashboard,andthedashboardkeystoreisuser-managed,usethispropertytospecifythepasswordforthedashboardtruststore.



insight.collection.aspect.enabled

Enablesordisablesspecificpluginaspects.ThisstrategydiffersfromthePrefixExcludeCollectionStrategy inthatitoperatesonaspectsasopposedtospecificinstrumentedclassesandmethods.Thisstrategyinteractswiththe AdviceErrorHandlingAspect toautomaticallydisablepluginsthatcreatedetectableproblems.Default: true

insight.collection.collapsing-frame-builder.threshold

Collapsingframebuildersettings.Thresholdwhentostart#collapsingframes.zero=disabled

Default:

0 (disabled)

insight.collection.global.excluded.resource.patterns.list

Afilterforexcludingsensitiveresourcepropertiesfromtransmissionstothedashboard.Thevalueisacomma-separatedlistofregularexpressions.

Default:

sysenv.*,sysprop.*

ThedefaultvaluematchesJavasystempropertiesprefixedwithsysprop ,andthecurrentenvironmentvariablevaluesprefixedwithsysenv .

insight.collection.global.excluded.resource.properties.listAfilterforexcludingsensitiveresourcepropertiesfromtransmissionstothedashboard.Thevalueiscomma-separatedlistofpropertiesnames/

insight.collection.global.filter-unknown-application-traces

FilterUnknownapplicationtraces.

Default:

false

insight.collection.min-operation-duration.enabled

EnablestheMinimumOperationDurationcollectionstrategyfortheagent,whichwhenenabled,causestheagenttocollecttracedataonlyforoperationswhosedurationexceedsthelengthspecifiedbyintheagent’s[insight.collection.min-operation-duration](#install-properties-file-insight-agent__insight.collection.min-operation-duration)property.

Default:

true

insight.collection.min-operation-duration

Whentheagent’s[insight.collection.min-operation-duration.enabled](#install-properties-file-insight-agent__insight.collection.min-operation-duration.enabled)propertyis yes ,thispropertyspecifiestheoperationdurationthreshold,inms.

Default:

0

insight.collection.only-endpoints.enabled

EnablestheEndpointOnlycollectionstrategyfortheagent,whichwhenenabled,causestheagenttocollectendpoint-onlytracedatainaspecifiedpercentageoftracesitperforms.Anend-pointonlytraceexcludestheactivityofresourcesinvolvedinarequestthatarenotpotentialend-points.(TheInsightplug-inthatmanagesaresourcetypedefineswhereornotthetypeisapotentialendpoint).

Theassociatedagentproperty, insight.collection.only-endpoints defineswhatpercentageoftraceswillbeendpoint-only,whenEndpointOnlytracingisenabled.

Default:

true


insight.collection.only-endpoints.percent

When[insight.collection.only-endpoints.enabled](#install-properties-file-insight-agent__insight.collection.only-endpoints.enabled)issetto yes ,thispropertygovernswhatpercentageoftheagent’straceswillbeendpoint-only.

Default:

10

insight.collection.plugins.spring-core.ComponentMethodOperationCollectionAspect.aspect.enabled

Disable@Componentbydefault,Default:false

insight.collection.prefix.instrument

Excludesapackage,class,ormethodfrominstrumentation.Youcanspecifythispropertymultipletimesinthepropertiesfile,onceforeachexcludetarget.

Specifythepropertyinthisformat:

insight.collection.prefix.instrument.package.class.method

whereyoucanspecify package onlytoexcludeacompletepackage,package . class toexcludeaclass,or package . class . method toexcludeaparticularmethod.Forexample:

insight.collection.prefix.instrument.

com.example excludesallclassesandmethodsinthe com.example

package.


com.example.myExampleClass excludesthe myExampleClass classinthecom.example package.


com.example.myExampleClassmyMethod excludesthe myMethod methodinthe myExampleClass classinthe com.example package.

Default:

none

insight.transport.type

Thetransportusedforcommunicationwiththeagent.Valuesmaybe:HTTP , ActiveMQ ,or RabbitMQ .

Default: HTTP

trace.exclude.path Pathstoexcludefromtracing(inantpathformat)

trace.filter.similar.per.hour

Limitshowtimesperhourtheagentwillsend“similar”tracestotheDashboard.(Twotracesaresimilariftheyhavethesameendpoint,errorstate,andasimilarresponsetime.)Throttlingtracevolumereducesthevolumeofretainedtracesthatprovideessentiallythemonitoringresults.

Withthedefaultsettingof12,anagentsendsatracewithagivensignatureoncewithina5minuteinterval.Ifyousetthevalueto4,theagentwillsendatracewithagivensignatureonlyonceduringa15minuteinterval.

Default:

12


UsingInsightOperationsInsightOperationsenablesyoutoseeataglancehowyourapplicationsandserversaredoing.Youcanimmediatelyseetheoverallhealthoftheclusterand,withafewclicks,viewtheperformanceofindividualapplications,endpoints,orservers.

InvokeSpringInsightinyourBrowser

BrowseallApplicationsandEndpoints

ViewRecentActivityofYourApplication

FilterTraceDetails

ImportandExportTraces

CustomizeEndpointThresholds

EnableandDisableCollectionStrategies

ViewSpringInsightDataInGoogleSpeedTracer

InvokeSpringInsightOperationsinYourBrowserInvokeSpringInsightOperationsinyourbrowser.

UseyourbrowsertobrowsetotheSpringInsightdashboardusingthefollowingURL:http://dashboardServer:port/insight

Replace dashboardServer withthenameorIPnumberofthehostrunningtheDashboardand port withtheHTTPlistenport,8080bydefault.IfyouhavesetupSSL,youcanalsouse https://dashboardServer :SSLport/insight.Replace SSLport withtheconfiguredSSLportnumber,8443bydefault.ThebrowserinvokesthemainSpringInsightdashboardontheBrowseResourcesscreen:

SpringInsighttracesallapplicationactivityanddisplaysitonthedashboard.Forexample,ifyouperformedanyJDBCqueries,eachoneisshownintheSpringInsightdashboardalongwithatimelineofrecentrequests.

BrowseallApplications,Servers,andEndPointsTheBrowseResourcesscreenshowsinformationforalltypesofapplications,butitisespeciallyeffective(andshowsthemostdetail)forSpring,Grails,andRooapplications.

Procedure1. FromthemainSpringInsightdashboard,clicktheBrowseResourceslink:


Ontheleft,theroottreenode,AllApplications,isselectedintheAPPLICATIONSpanelandAllInstancesisselectedintheINSTANCESpanel.TheAPPLICATIONSHEALTHTRENDpaneldisplaysagraphoftherecenthealthofallapplicationsonallservers.TheAPPLICATIONSpanelontheright,beneaththegraph,displaysalistoftheapplicationswithsomestatisticsfortheapplicationforthetimeperioddisplayedbythegraph:

TheHealthTrendcolumnshowsasimplesparklinethatgraphicallydescribestherecenthealthoftheapplication.TheThroughputcolumnshowshowmanyTracesperMinute(tpm)wereexecutedoverthecurrenttimewindow.TheErrorscolumnshowswhatpercentageofTracesresultedinanError(HTTPstatus500to600).

Thegraphicalortabularviewofallapplicationsisusefultoseewhichapplicationshavebeenbusiestandtocomparetheirrelativehealth.Clickinthegraphstoseetheapplication-specificinformation.Clickthecolumnheadersinthetabletosorttheinformationbasedonthevaluesinthecolumn.TheINSTANCESpanelatthebottomoftherightcolumndisplaysthesamestatisticsforeachserverinthecluster.Fromthislist,youcaneasilyidentifyunderperformingorfailingservers.

2. WithAllApplicationsselectedintheleftAPPLICATIONSpanel,clickonanindividualserverintheleftINSTANCESpanel.ThisviewdisplaysaHealthTrendgraphforallapplicationsrunningontheselectedserveranddetailedinformationfortheserver.

Theheadingofthegraphpanelchangestoidentifytheserveryouselected.TheVitalssectionofthegraphpaneldisplaysperformancestatisticsfortheserverforthetimeperioddepictedonthegraph:

Throughput:HowmanyTracesperMinute(tpm)wereexecutedduringthecurrenttimewindow.Invocations:Totalnumberofrequestsmadeduringthecurrenttimewindow.Errorrate:PercentageofinvocationsthatresultedinanHTTPerrorstatus.

ThePropertiessectionofthegraphpanellistssystempropertysettingsfortheserver:-catalina.base:HomedirectoryforthetcRuntimeinstance.-date.creation:DatethetcRuntimeinstancewascreated.-java.pid:ProcessIDoftheJavaVM.-system.net.connecting.ip:-system.net.default.route.ip:-system.net.ip:-system.net.name:Networknameofthehostcomputer.ExpandtheAllPropertieslistatthebottomtoseeacompletelistoftcServerandJavasystemproperties.

3. ClickonanapplicationintheleftAPPLICATIONSpanelandAllInstancesintheleftINSTANCESpanel.TherightpaneldisplaysinformationabouttheselectedapplicationanditsEndPointsacrossallserversinthecluster.TheENDPOINTSpaneldisplaystheEndPointsassociatedwiththeapplication;thesamelistappearsbelowthenameoftheapplicationintheleftAPPLICATIONSpanel.


TheVitalssectioninthegraphshowsasummaryofthehealthoftheapplication.EachrowintheEndPointstablerepresentsanendpoint,whichisareceptorforrequests.TheuniverseofpossibleHTTPURLsisunlimited.However,SpringInsightcangrouprequeststogetherbasedonthecontrollerwithwhichtherequestsareassociated.ForeachEndPoint,SpringInsightdisplaysthefollowinginformation:

Health:Showshowwelltheresponsetimemetriciskeptwithinatolerablethreshold,whereredislesshealthyandgreenismorehealthy.SeeCustomizingEndPointThresholdsforsettingthetolerablethreshold.EndPoint:DisplaysthenameoftheEndPoint.ThroughputTrend:DisplaysasimplesparklinethatshowstherecentmeanthroughputtimeoftheEndPoint.Throughput:ShowshowmanyTracesperMinute(tpm)wereexecutedoverthecurrenttimewindow.Errors:ShowswhatpercentageofTracesresultedinanError(HTTPstatus500to600).ResponseTime:Displaysthe99%responsetimeoverthegiventimerange.Thisvalueismostusefultodeterminetheworst-caserequest.Avalueof115msindicatesthat99%oftherequestscompletedwithin115milliseconds.TheresponsetimeofanHTTPrequestisdeterminedbythefulltimeittakesthecontainertoshiptheresponsetotheclient,andnotjustthetimespentinacontroller.

4. ClickonanyindividualserverintheleftINSTANCESpaneltoseethesameinformationdescribedinthepreviousstepforonlytheselectedserver.

5. ClickonaparticularEndPoint,eitherintheleftAPPLICATIONSpanelorintherightENDPOINTStableforaparticularapplication:

SpringInsightdisplaysthefollowingdetailedinformationabouttheEndPoint:Thechartshowsthethroughput,responsetime,anderrorratetrendsonthesamegraph.ResponsetimetrendreferstothemeanresponsetimeoftheEndPointoverthetimerange.ThroughputtrendreferstotherecentmeanthroughputtimeoftheEndPoint.ErrorrateisthepercentageoftracesresultinginanHTTPerror.Clickonmarkers(points)inthecharttoviewTracedatathatoccurredduringthattimerange.TheRESPONSETIMEHISTOGRAMisaninteractivegraphthatshowshowmanyinvocationsoccurredwithinagiventimeperiod.TheY-axisrepresentstheresponsetimeofaninvocation.TheX-axisrepresentsthenumberofinvocations.Usingthehistogramisaneasywaytoidentifyoutliersinyourdata.Thelongest-runninginvocationsarealwaysatthetopofthehistogram.Ifextremeoutliersexist,theyareindicatedbyredbars.TheHealthoftheEndPointisdeterminedbytheResponseTimeforrequestsmadeoverthegiventimeinterval.TheresponsetimesarebrokendownintovariousHealthZonessuchasfrustrated,toleratedorsatisfied.ClickonaparticularHealthZonetoseerepresentativetraceswithinthatzone.

6. ClickabarinthehistogramorononeofthemarkersintheThroughputorResponseTimeTrendgraphs.AREPRESENTATIVETRACESpanelshowsrepresentativetracesforsomeinvocationsthatoccurredduringtheselectedduration.


TheREPRESENTATIVETRACESpanelincludessimilardataasthatoftheRecentActivityscreen.Fromhereitiseasytodrillintotheshortestorfastestrunningtracestoseewhatmadethemdifferent.SeeViewingRecentActivityofYourApplicationfordetailedinformationabouttracesandtracedetails.

ViewRecentActivityofYourApplicationYoucangetanoverviewofrecentactivityforaparticularapplicationandforallapplicationscurrentlydeployed.Youcanalsodrilldowntothedetailsofparticularapplicationevent.

Procedure1. FromthemainSpringInsightdashboard,selecttheRecentActivitytab:

TheRecentActivityscreendisplaystracesfromyourapplication.Atraceisabreakdownoftheactivityofarequest.TheRecentActivityscreenanswersthequestionWhatjusthappened?

2. Intheapplicationselectordrop-downboxinthetop-rightoftheTraceHistorypanel,selectthenameofyourapplication.Usetheapplicationselectortoviewactivityforallapplicationsorforjustasingleone.TheTraceHistorypanelshowsatimelineofrecentactivityforyourapplicationasreal-timerequests,representedbybarsinthechart.Eachbarrepresentsallrequeststhatoccurredwithinatimeslice,asmeasuredbythechart.Thefulltimerangehas60timeslices.Theheightofthebarisequaltothelongestrequestthatoccurredduringthatwindow.TheTraceHistorygraphshowsactivitythatSpringInsighthasmonitoredoverthepastNminutes.WhenatraceiscapturedbySpringInsight,itshowsonthegraphasabarontheright-handside.Astimepasses,barsmoveleftuntiltheyfalloutofthetimerange.Clickonbarstodrilldeeper.

3. ClickonabarintheTraceHistorychart.TheTracespaneldisplaysalistoftracesthatexecutedduringthewindowoftime(ortimeslice),andthendetailsaboutaspecifictrace.InsightautomaticallyshowsdetailsaboutthefirsttraceintheTraceDetailspanel.Ifyouclickonadifferenttrace,Insightrefreshesthedetailspanelwithcorrespondinginformation.


YoucansortthetracesintheTracespanelbyDuration(howlongdidthetracetake?),Start(whendidthetracestart?),EndPoint(whatwastherequest?),orError(didtherequestresultinanerror?)

4. ClickonatraceintheTracespaneltoviewitsdetailsintheTraceDetailpanel.

TheTraceDetailpanelcontainsabreakdownofatrace’sactivityinatreeformat.Atraceconsistsofatop-leveloperation,usuallyaWebrequest,andallnestedoperations.SpringInsightuses“smartcollapse”todeterminehowtocollapsethetreeoftracedetailssothatyoudonotgetpagesandpagesoftraceinformation.Youcan,ofcourse,expandoperationstodrilldownintotheirdetails.Operationsarethefundamentalbuildingblocksoftraces.AnoperationcanrepresentaWebrequest,atransaction,acalltoanMVCcontroller,afileopening,aservicerequest,andsoon.Eachoperationmayhaveotheroperationsnestedwithinit.Thenestingstructureshowsthenormalstack-basedmethodinvocationpattern.Theoperationtiminggraphshowstwopiecesofinformation:

Whentheoperationexecutedinrelationtotheotheroperations.Thisinformationshowswhethertheoperationexecutedtowardstheendoftherequestorthebeginningbythelocationofthegreenbarinrelationtoitsborders.Howlongtheoperationtooktoexecute,indicatedbythewidthofthegreenbar.Becauseoperationscanbenestedwithinoperations,thegreenbarshowsonlyhowlongtheparticularoperationtook,notethesumofdurationofthenestedoperations.Thiswayyoucanscanallthenestedoperationsandfindtheparticularonethattookthelongesttime,basedonthewidthofitsgreenbar.

Clickonanoperation’slabel,ortheentirerow,todrillfurtherintotheoperationdetails.Thedetailsofthispanelarespecifictoeachtypeofoperation,andcontainthefinestgranularityofcollecteddata.ClickonFiltertofilterthetracedetailsshowninthepanel.SeeFilteringTraceDetailsforadditionaldetailsaboutthisfeature.ClickonRelatedTotonavigatetotheTrace’scorrespondingEndPointorapplicationintheBrowseResourcestab.Thisbuttonisusefulwhenyouwanttoseehowsimilarrequests(requeststothesameEndPointorapplication)haveperformedovertime.


Visualindicators:-Alightbulbicongivesavisualexplanationtohoweachtraceisclassifiedasbelongingtoaspecificendpoint. Forexample,inthescreenshotbelow,theframerepresentingthe HotelsController searchmethodisselectedasthemostimportantframeinthetrace.-Abarabovethetracedetailpanedisplaysdetailsofanhttprequestthatresultedinanerror.

5. Thebuttonsabovetheapplicationselectordrop-downboxhelpyoucontroltheinformationyouseeintheSpringInsightdashboardandperform

additionaladministrativetasks:Changetheglobaltimerangeusingthefirstdrop-downlist.ThetimerangespecifieshowmanyminutesworthofdatashowsupintheTraceHistorygraph.Playorpausethegraphmovementbyspecifying now or pause inthefirstdrop-downlist.IfthegraphisinPlaymode,theword Liveappearsundertherighthandsideofthegraph.Ifyouhavepausedthegraphmovement,thetimewhenyouclickedthepausebuttonappearsinstead.Clickthe << or >> buttonstorewindorfast-forward,basedonthespecifiedtimeranges.SpringInsightpersistsalltraceinformationaboutallyourapplicationstodisk,whichmeansyoucanrewindandlookattraceinformationfromwhenyoufirstbegantotracktheperformanceofyourapplication.Intheright-mostdrop-downlist,choose Refresh torefreshthetracehistorybyreloadingalldatawithintheTraceHistorygraph.

FilterTraceDetailsDependingonthenatureofaspecifictrace,thelistofoperationsinthecorrespondingTraceDetailpanemightbeverylong.SpringInsightusessmartcollapse,whichmeansitcollapsesthoseoperationsitthinksareunimportantbutexpandsoperationswhicharemostlikelyinterestingtoyou.However,theTraceDetailspanecouldstillbeverylarge.Inthiscase,youmightwanttofilterthelistofoperationssoastodisplayonlycertaintypesthatyouareinterestedin.

Thelistofavailablefiltersdependsontheplug-inscurrentlyinstalledinSpringInsightaswellasthetypeofoperationsinthecurrentlistoftracedetails.SpringInsighthasanumberofplug-insinstalledbydefault.ClicktheAdministrationtabonthemaindashboardthenCollectionPlug-Instoseethelist.Ifyoupreviouslyaddedyourowncustomplug-intoSpringInsightsoastodisplaycustomtracedetails,thenthisfiltermightalsobeavailable.

Thedefaultlistoffiltersisasfollows:

Database:Filtersoperationsbasedonwhethertheyarerelatedtogeneraldatabasecalls.Thiscouldincludetransactionsaswellasstandardcallstoarelationaldatabase,forexample.

JDBC:FiltersoperationsbasedonwhethertheyareJDBCcalls.TheresultsofthisfilterareasubsetoftheresultsoftheDatabasefilter.

Web:FiltersoperationsbasedonwhethertheyarerelatedtoWebcalls,suchasHTTPrequestsandresponses,renderingofHTMLpages,andsoon.

Filtersaretri-state—youcanseteachfiltertooneofthreedifferentstates:

Unselected–operationsareincludedintheresultsunlessoneormoreotherfiltersaresetto+(plus)

+(plussign)–onlytheseoperationsareincludedintheresults

-(minussign)-onlytheseoperationsareexcludedfromtheresults

Filtersaresticky,whichmeansthattheystayinplaceevenwhenyounavigateawayfromthepageinwhichyousetthefilter.ThisisusefulifyouwanttolookatmultipleapplicationsorEndPoints,searchingforJDBCcalls,becauseyoudonothavetoresetthefiltereachtimeyoulookatadifferenttrace.Youcanremovethefilteratanytime,asdescribedintheprocedurebelow.


ProcedureToapplyfilters,followthesesteps:

1. DisplaytheTraceDetailspaneforaparticulartraceyouareinterestedin.SeeViewingRecentActivityofYourApplication.

2. Inthetop-rightcorneroftheTraceDetailspane,clicktheFilterdrop-downlistandselectthefiltersyouwanttoapply.Youcanselectmultiplefilters;theresultsareasumoftheindividualfilterresults.Setthefilterto+(plus)toincludeonlythoseoperations,-(minus)toexcludetheoperations,orleavetheboxunselected.Ifyoudonotsetafilterto+or-,theoperationsareincludedunlessanotherfilterissetto+.

TheprecedinggraphicshowshowtoapplyaJDBCfilter.

3. ClicktotheleftoftheFilterdrop-downlisttoactuallyapplythefilter.AmessageappearsbelowtheTraceDetaillabelthatalertsthatafilterisbeingapplied.Afterapplyingthefilter,thetracedetailsnavigationtreeshouldgetsmaller,andtheonlydetailsthatarenowincludedarethoserelatedtothespecifiedfilter,suchasJDBCcallsinourexample.Becauseofthestickinessofthefilter,asyounavigateawayfromyourcurrentpageyou’llseethatSpringInsightcontinuestoapplythefilter.

4. Toremovethefilter,clickonthe X totheleftofthe Filterappliedtotrace alert.

ExportandImportTracesWiththisfeature,youcanexportatracetoafileandthenimportitintoeitherthesameordifferentinstanceofSpringInsight.ThisfeatureisusefuliftheInsightuserwhocapturedthetraceinrealtimewantstolookatitatalatertime,orhanditofftoanotherperson.

Forexample,assumethataQAengineeristestingaWebapplicationandgetsanerror,oranoperationtakestoolongtocomplete.TheQAengineerusesSpringInsighttotakealookatwhatjusthappenedbynavigatingtotherelevanttraceandviewingitsdetails.IftheQAengineerdecidestoopenabugabouttheproblem,theycanexportthetracetoafileandthenattachthisfiletothebugissuesothatthedevelopercantakealookatalaterdate.Thedeveloperdoesnotneedtoactuallydeploytheapplication;rather,theycansimplylookatthetracedetailstofigureoutwhichoperationcausedtheerror,wheretheexcessivetimeoccurred,andsoon.Thisisaneasywaytocaptureacompletesetoftraceinformationaboutanerrorevent,eveniftheeventisnotreliablyreproducible.

YoucanonlyimporttracesthatwerepreviouslyexportedfromaSpringInsightinstance.

ProcedureToexportatrace:

1. DisplaytheTraceDetailspanefortheparticulartraceyouwanttoexport.SeeViewRecentActivityofYourApplication.

2. Fromtheright-mostdrop-downlistintheTraceDetailspane ,selectExportTrace:


3. Savetheexportedtracetoafile.Thenameofthefilewillbeoftheform trace-identifier.insight .

Toimportatrace:

1. FromthemainSpringInsightdashboard,clicktheAdministrationtab.

2. Intheleftpane,clickImportTrace.

3. Intherightpane,usethebrowsebuttontobrowsethetraceyouwanttoimport;thenameofthefilewillbeoftheformtrace-identifier.insight .

4. ClickImport.SpringInsightimmediatelytakesyoutotheRecentActivitypagewiththetraceanditsdetailsdisplayed.

5. TolocatethetraceintheTraceHistorypane,gobackintimetowhenthetracewasoriginallyexported.

CustomizeEndPointThresholdsThehealthofanendpointisbasedonhowmanytracestooklongertoexecutethantheresponsetimethreshold.

Bydefault,SpringInsightusesaresponsetimethresholdof200ms.Intheresponsetimehistogram,theupperlimitofthey-axisis4-timesthethreshold,or800msbydefault.Thetimechunksofthey-axisarenotevenlydistributed,butrather,brokenupinawaytoshowthedistributionoftheresponsetimesoftherecentEndPointtraces.

If,foragiventraceorsubsetoftraces,youfindthatthedefaultthresholdistoohighortoolow,youcanchangeit.Forexample,ifyoufindthatallyourresponsetimesforthe .*show.* methodsarealmostalwaysbelow100ms,youmightwanttosetthisasthethreshold.Thehistogramwillthenhaveasmallerrange,andthusshowmorefinegrainedinformation.Similarly,ifyouhaveanendpointinwhichtheresponsetimesarealwaysover200ms,thehealthofthisendpointwillalmostalwaysshowas frustrated .Ifyoudecidethatitisacceptableifathresholdof300msisacceptable,thenyoucanchangeitforthisEndPointsoitwillshowasappropriatelyhealthy.

Inotherwords,ifyouchangetheresponsetimethresholdforanEndPoint,youchangethecriteriathatSpringInsightusestodecidewhetheritishealthyornot.

ThefollowinggraphicshowsthehealthandresponsetimehistogramforanEndPointwhosethresholdisthedefault(200ms):


Notetheupperlimitinthehistogramof800ms,andthe satisfied rangeisunder200ms.Aresponsetimeofover200msbutunder800msistolerated,butover800msisfrustrated,orunhealthy.

NotethatallresponsetimesareunderthedefaultthresholdsotheEndPointishealthy.Iftheresponsetimesareallsignificantlybelowthedefaultthreshold,itmightbeagoodcandidatetolowerthethresholdtogetmorefine-grainedresponsetimeinformation.

ProcedureTochangethethresholdforanEndPointorsetofEndPoints:

1. FromthemainSpringInsightdashboard,clicktheAdministrationtab.

2. ClickEndPointThresholdintheleftpane.

3. Intherightpane,clickNew:

4. IntheRulefield,enteraregularexpressionthatcorrespondstotheEndPointorEndPointsforwhichyouwanttochangethethreshold.Forexample,ifyouwanttospecifyall show methods,enter .*show.* :

5. Enterthenewthreshold.Asdescribedabove,thedefaultSpringInsightthresholdis 200 milliseconds.

6. ClickSave.TheMatchingEndPointscolumnautomaticallyshowsthenumberofEndPointsthatmatchthisrule;thenumberisalink.ClickonthislinktoseethelistofmatchingEndPoints.

7. ClicktheMakePermanenttoapplythechange.Thenewruleappearsinthetable:

8. Ifyouhavemorethanthreerules,youcanusetheupanddownarrowbuttonstochangetheorderinwhichSpringInsightappliestherules.Insightappliestherulesfromfirstinthelisttolast.Thedefaultrule( .* )shouldalwaysbelast.

9. Browsetoatracethatmatchestherule.Notethatthey-axisoftheResponseTimeHistogramnowhasanupperlimitof4-timesthenewthreshold.


ThehealthoftheEndPointisnowsatisfiedwhenitsresponsetimeisbelowthenewthreshold.Inourexample,thenewthresholdis100msandso

theupperlimitis400ms:

EnableandDisableCollectionStrategiesYoucanconfigureSpringInsightcollectionstrategiesforeachInsightAgent,initspropertiesfile,withthepropertiesthatareprefixedwithinsight.collection .Collectionstrategiesinclude:

Endpointsonly.Limitacertainpercentageoftracestoresourcesthatarepotentialendpoints.

Prefixinstrumentation.Selectivelyexcluderesourcesfrominstrumentationatthepackage,classes,ormethodlevel.

Minimumoperationduration.Excludeoperationswhosedurationislessthanaspecifiedthreshold.

OntheCollectionStrategiespage,availableontheAdministrationtab,youcanviewthecurrentcollectionsettingsacrossallagents.Youcanalsogloballyenableordisableacollectionstrategyfromtheuserinterface;forinstanceyoucoulddisableprefixinstrumentationforallagentsreportingtothedashboard.

Ifallagentsreportingtothedashboardhavethesamesettingforaconfigurationstrategy,thevaluethatisconfiguredisprefacedbythestring“global”,asisthecasefortheendpointsonlystrategyinthescreenshotbelow.Incontrast,notethattheminimumoperationdurationstrategyisenabledononeagentanddisabledontheother.

Toenableordisableacollectionstrategiesforallagentsimmediately,clickthepenciliconnexttoitontheCollectionStrategiespage.NotethattheCollectionStrategiespageenablesrun-timecontrolofcollectionstrategiesonly.Thenexttimeaagentisrestarted,itwillagainadheretothecollectionstrategyconfigurationdefinedinitspropertiesfile.

ViewingSpringInsightDataInGoogleSpeedTracerSpeedTracer isaGoogleChromeextensionthatanalyzeshowyourapplicationisperforminginsidethebrowser.Itmeasureshowlongthebrowsertakestorender,transformCSS,showimages,processevents,andsoon.


http://code.google.com/webtoolkit/speedtracer/

AlthoughSpeedTracerisagreattoolfordeterminingwhereCPUtimeisspentwithinthebrowserprocess,itcannotseeintowhattheapplicationitselfisdoinginthebackend.Forthat,itneedsInsight.ThetwoproductsarenowintegratedsothatyoucannowseeTracedatainterleavedwithSpeedTracer’sbrowsertimings.

ProcedureToseeInsightTracedatawithinSpeedTracerforanapplicationdeployedtoInsight:

1. DeployyourapplicationtoatcRuntimeinstancethatisconfiguredwithSpringInsight.

2. Ifyouhavenotalreadydoneso,downloadtheversionofGoogleChromethathasbeeninstrumentedforSpeedTracer,installtheSpeedTracerextension,andlaunchtheChromebrowserwiththeappropriateflag.Fordetails,seeGettingStartedwithSpeedTracer .

3. OpenuptheSpeedTracerconsolebyclickingonthestopwatchiconinthetop-rightcorneroftheGoogleChromebrowser.

4. UsingGoogleChrome,navigatetoapageofyourdeployedapplicationandperformsomeaction.

5. InSpeedTracer,clickontheNetwork(resources)timeline.Intheleftcolumn,searchforresourcesthathaveagreypillbox,withtooltipIncludes timing data from the server ;theseresourcesincludeInsightdataalongwiththestandardSpeedTracerdata.Seethegraphicinthenextstep.

6. ExpandtheresourcetoviewtheInsightdata,listedundertheServerTracesection.ThissectionincludesabriefsummaryoftheTraceframestackandallowseasynavigationintovariouspartsofSpringInsightrelatedtothegivenTrace.Toseemoredetailedinformation,selecttheTrace,EndPointorApplicationlinks,whichwilljumpintoInsightattheappropriatelocationsoyoucanfurtherdrilldown.


http://code.google.com/webtoolkit/speedtracer/get-started.html

AgentManagementAPITheagentmanagementAPIhascommandsformanagingagents,plugins,tracing,anduser-definedendpoints.TheAPIURLforanInsightAgentbeginswithinsight_url/services/agent-management/.

agents

GET/services/agent-management/agentsReturnsalistofagentsandtheirattributes.

Parameters

Table1.CommandOptions

pageNum

Pagenumbertoreturn,firstpageis1.

(Optional)1

pageSize

Sizeofeachpage.

(Optional) 20

ExampleRequest

GEThttp://localhost:8080/insight/services/agent-management/agents

{"agents":[{"name":"tal-ubuntu.local-27889","id":"42fbe22c-864d-408c-8d29-d0803a06020d","roles":["AGENT","ANALYZER","DASHBOARD"],"version":"1.9.0-CI-SNAPSHOT","status":"on","heartbeat":15,"licensed":true,"sameVersionAsDashboard":true,"througput":200,"lastHeartBeat":1339331100771,"clockSkew":0,"installPath":"/work/env/apache-tomcat-7.0.50","containerName":"Tomcat","containerVersion":"7.0.50","toggleUrl":"/services/agent-management/agents/status","toggleMethod":"PUT","toggleBody":"{\"status\":\"off\",\"agentId\":\"42fbe22c-864d-408c-8d29-d0803a06020d\"}"}]}

NotesYoucanusethepropertiesprefacedby toggle tostartorstopanagent.

Ifyouusethepagingoptions,theresultsincludepagedata:


{"agents":[{"name":"tal-ubuntu.local-27889",...}],"currentPage":2,"totalPages":20,"pageSize":10,"nextPage":"/services/agent-management/agents?pageSize=10&pageNum=3""prevPage":"/services/agent-management/agents?pageSize=10&pageNum=1"}

GET/services/agent-management/agents/{agentid}Returnsthedetailsforoneagent.

ExampleRequest

GEThttp://localhost:8080/insight/services/agent-management/agents/42fbe22c-864d-408c-8d29-d0803a06020d

{"name":"tal-ubuntu.local-27889","id":"42fbe22c-864d-408c-8d29-d0803a06020d","roles":["AGENT","ANALYZER","DASHBOARD"],"version":"1.9.0-CI-SNAPSHOT","status":"on","heartbeat":15,"licensed":true,"sameVersionAsDashboard":true,"througput":200,"lastHeartBeat":1339331160771,"clockSkew":0,"installPath":"/work/env/apache-tomcat-7.0.50","containerName":"Tomcat","containerVersion":"7.0.50","toggleUrl":"/services/agent-management/agents/status","toggleMethod":"PUT","toggleBody":"{\"status\":\"off\",\"agentId\":\"42fbe22c-864d-408c-8d29-d0803a06020d\"}"}

Notes-Youcanusethepropertiesprefacedby toggle tostartorstopanagent.

PUT/services/agent-management/agents/statusTurnsanagentonoroff.

ExampleRequest

PUThttp://localhost:8080/insight/services/agent-management/agents/status

Putbody:

{"status":"on","agentId":"42fbe22c-864d-408c-8d29-d0803a06020d"}

Response

200 forsuccess;otherwise 500 .


Settingmultipleagents’status

Setthevalueofmultipleagentswithonecallto /agents/status bysendingalistofstatusesinthe PUT body.ThisisespeciallyusefulforbatchoperationsinUIgrids.

[{"status":"off","agentId":"123"},{"status":"on","agentId":"456"}]

Plugins

GET/services/agent-management/pluginsReturnsalistofpluginsandtheirproperties.

Parameters


pageNum


(Optional)1

pageSize

Sizeofeachpage.

(Optional)20

ExampleRequest

GEThttp://localhost:8080/insight/services/agent-management/plugins

{"plugins":[{"name":"annotation","version":"1.9.0-CI-SNAPSHOT","href":"http://www.springsource.org/insight","publisher":"Pivotal","status":"on","toggleUrl":"/services/agent-management/plugins/status","toggleMethod":"PUT","toggleBody":"{\"pluginName\":\"annotation\",\"status\":\"off\"}"},{"name":"apache-httpclient3","version":"1.9.0-CI-SNAPSHOT","href":"http://www.springsource.org/insight","publisher":"Pivotal","status":"on","toggleUrl":"/services/agent-management/plugins/status","toggleMethod":"PUT","toggleBody":"{\"pluginName\":\"apache-httpclient3\",\"status\":\"off\"}"}]}

Notes-Youcanusethepropertiesprefacedby toggle tostartorstopaplugin.

Ifyouusethepagingoptions,theresultsincludepagedata:


{"plugins":[{"name":"tal-ubuntu.local-27889",...}],"currentPage":2,"totalPages":20,"pageSize":10,"nextPage":"/services/agent-management/plugins?pageSize=10&pageNum=3""prevPage":"/services/agent-management/plugins?pageSize=10&pageNum=1"}

PUT/services/agent-management/plugins/statusTurnsapluginonoroff.

ExampleRequest

PUThttp://localhost:8080/insight/services/agent-management/plugins/status

PutBody

{"status":"on","pluginName":"tomcat"}

Allowablevaluesfor“status”are“on”or“off”

Response


Settingmultiplepluginsstatus

Setthevalueofmultiplepluginswithonecallto/plugins/statusbysendingalistofstatusesinthePUTbody.ThisisespeciallyusefulforbatchoperationsinUIgrids.

[{"status":"off","pluginName":"tomcat"},{"status":"on","pluginName":"annotation"}]

CollectionStrategies

GET/services/agent-management/strategy/tracingGetthecrossservertracingratio.

ExampleRequest

GEThttp://localhost:8080/insight/services/agent-management/strategy/tracing

{"ratio":10}


PUT/services/agent-management/strategy/tracingSetthecrossservertracingratio.

ExampleRequest

PUThttp://localhost:8080/insight/services/agent-management/strategy/tracing

PutBody

{"ratio":10}

Validvaluesfor“ratio”are0-100.

Response


UserDefinedEndpointAnalyzers

GET/services/agent-management/userdefinedendpointsReturnsalistofalluserdefinedendpointanalyzers

Parameters


pageNum


(Optional)1

pageSize

Sizeofeachpage.

(Optional) 20

ExampleRequest

GEThttp://localhost:8080/insight/services/agent-management/userdefinedendpoints

{"user_defined_analyzers":[{"operationType":"spring_event_publish","className":"org.springframework.context.event.SimpleApplicationEventMulticaster","methodSignature":"multicastEvent","key":"51010fe51","deleteUrl":"/services/agent-management/userdefinedendpoints/delete","deleteMethod":"PUT","deleteBody":"{\"key\":\"51010fe51\"}"}]}


Note-

Todeleteauserdefinedendpointanalyzer,usethepropertiesprefacedby toggle .

PUT/services/agent-management/agents/userdefinedendpoints/createCreatesoneormoreuserdefinedendpointanalyzers.

ExampleRequest

PUThttp://localhost:8080/insight/services/agent-management/userdefinedendpoints/create

PutBody

[{"className":"org.springframework.context.event.SimpleApplicationEventMulticaster","methodSignature":"multicastEvent","operationTypeString":"spring_event_publish"}]

Response


PUT/services/agent-management/agents/userdefinedendpoints/deleteDeletesoneormoreuserdefinedendpointanalyzers.

ExampleRequest

PUThttp://localhost:8080/insight/services/agent-management/userdefinedendpoints/delete

PutBody

[{"key":"51010fe51"}]

Response


Deletingorcreatingmultipleuserdefinedendpointanalyzers

Youcandelete/createmultipleuserdefinedendpointanalyzerswithonecallbysendingalistinthePUTbody.

[{"key":"51010fe51"},{"key":"51010fe52"}]


table of contents - pivotal software · insight operations now supports three different transports...

Documents