table of contentstcserver.docs.pivotal.io/3x/docs/pdf/pivotal-tc-server-insight-dev-1.9.… · by...

1234711

TableofContents

TableofContentsAboutSpringInsightDeveloperSupportedConfigurationsandSystemRequirementsWhatIsSpringInsightDeveloper?InstallandConfigureInsightDeveloperUsingSpringInsight

©CopyrightPivotalSoftwareInc,2013-2016 1 1.9

AboutSpringInsightDeveloperSpringInsightDeveloperdescribesSpringInsightconceptsandprovidesinstructionsforconfiguringandusingSpringInsightDeveloperwithPivotaltcServer.SpringInsightDeveloperprovidesin-depthtracingandperformancemonitoringforWebapplicationsduringthedevelopmentandQAphases.

SupportedConfigurationsandSystemRequirements

WhatIsSpringInsightDeveloper?

InstallandConfigureInsightDeveloper

UsingSpringInsight

IntendedAudienceSpringInsightDeveloperisintendedforanyonewhowantstoinstall,configure,anduseSpringInsightDeveloperinaWebapplicationdevelopmentandtestingenvironment.


SupportedConfigurationsandSystemRequirementsSpringInsightDeveloperrunsinJava6,7,and8environmentsandissupportedbytcServerDeveloperEdition2.1,2.5,2.6,2.7,2.8,and2.9.Java8issupportedasofversion1.9.2.SR6ofSpringInsight.

SpringInsightDevelopersupportsthesameplatformconfigurationsastcRuntime.ThesystemrequirementsforInsightDeveloperarethesameasfortcRuntime.SeeSupportedConfigurationsandSystemRequirementsforPivotaltcServer.

RecommendedBrowsersSpringInsightDeveloperperformsbestwhenyouusethefollowingbrowsersorIDE:

GoogleChrome

Safari5orlater

MozillaFirefox3.6orlater

SpringToolSuite

AlthoughSpringInsightwillworkwithMicrosoftInternetExplorer7and8,itsperformancewillnotbeoptimal.Ifyoucannotusearecommendedbrowser,youshouldinstalltheGoogleChromeFrame pluginforInternetExplorer.


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

WhatIsSpringInsightDeveloper?SpringInsightDeveloperanswersthequestion“Whatjusthappened?”ItisaPivotalWebapplicationthatgivesyoureal-timevisibilityintoapplicationbehaviorandperformance.

Indevelopmentandtestingstages,developerscanuseSpringInsightDevelopertoverifyimmediatelywhethertheirnewly-writtencodeisbehavingasdesigned.QAengineerscanpinpointspecificcausesfor“whatjusthappened”andrelaydetailedinformationtodevelopers.

StresstestinganapplicationtypicallytellsyouwhichURLareasareslow.BycombiningSpringInsightDeveloperwithyourexistingtools(suchasJMeter),youcanseenotonlywhichURLsareslow,butwhy,thusacceleratingyourtimetoproduction.

SubtopicsWhatYouCanDowithSpringInsight

HowSpringInsightWorks

KeyConceptsandTerminology

WhatYouCanDowithSpringInsightThefollowingtopicsdiscussspecificusecases:

AgileDevelopment

QARearViewMirror

LoadandPerformanceTesting

BrowserPerformanceDatafromIntegrationwithGoogleSpeedTracer

AgileDevelopmentWebapplicationdevelopersrealizeamassiveincreaseinproductivitywhentheycanmakechangesandseetheeffectimmediately.Typically,adevelopermakeschangestoHTMLorJSPandreloadsthebrowsertoverifythatthemodifiedapplicationrendersthewebpageasdesired.However,developersoftenlackacentralizedtoolthatshowshowtheirchangesaffect:

JDBCqueries

Springbeaninteraction

Callstoexternalservices

Large,popularframeworkssuchasHibernateandSpringWebpushmuchofthecodethatdevelopersformerlywrotemanuallyintoaconvenientlibrary.Thisprocesssavestimeandimprovesmaintainability.Thedownsideisrelinquishingcontrol,whichmeansthatthedevelopermaynotknowexactlywhatisgoingonbehindthescenes:

Howmanydatabasetransactionsdidawebrequestcreate?

Howexpensiveisittousecomplexwebparameterbinding?

WhataretheHTTPheadersbeingsenttothedeveloper’sRESTapplication?

TheSpringInsightTraceviewsolvestheseproblems.Itallowsdeveloperstomakechangesandverifytheireffectivenessimmediately.

QARearViewMirrorSpringInsightgivesQAaricherpictureofanapplication’sperformance,eliminatingmuchoftheworkrequiredtodiagnoseproblems.AsQAtestsanapplication,typicalproblemsinclude:

Slow-loadingpages

Databasegrinding

Stacktraces


Astheseproblemsarise,QAengineerscanbrowsetotheSpringInsightdashboard,reviewallrecentoperations,andaccessin-depthinformationthathelpsthemtrackdownbugs.Thedashboardprovidesinformationsuchas:

Alistofalldatabasequeriesandtheirperformance

Adetaileddescriptionofthewebrequest,itsparameters,andheaders

Alistofcomponentmethodcallsandtheirparameters

AlistofallSpringcomponentsthatwereusedandtheirperformance

QAforwardsthisinformationtothedeveloper,thusimprovingtheturnaroundtimeforidentifyingandresolvingrootcauses.

LoadandPerformanceTestingWebapplicationsmustbeloadedandstressedbeforebeingdeployedinaproductionsetting.SpringInsightworkswithyourexistingload-testingtoolstoanswertwomainquestions:

Whatwasslow?

Whywasitslow?

Afterrunningaloadtest,SpringInsightdisplaysabreakdownofallrequeststoSpringWeb.Itshowsyou:

Theresponsetimetrendoveradesignatedperiod

Ahistogramthatidentifiesresponsetimepatternsandoutliers

Detailedstatistics,suchas95thpercentileresponsetime

Usingthisinformation,youcandrilldowntospecificinformationaboutwhyarequestwasslow:

Didtherequestexecuteanextremelyslowdatabasequery?

Diditmakeacalltoaremotesystemthatlockedup?

Diditspendalongtimerenderingtheresult?

TherequesttraceinformationthatyouaccessintheTraceviewisalsoavailablewhenyouanalyzeaperformancetest.

BrowserPerformanceDatafromIntegrationwithGoogleSpeedTracerSpeedTracerisaGoogleChromeextensionthatanalyzeshowyourapplicationisperforminginsidethebrowser.Itmeasureshowlongthebrowsertakestorender,transformCSS,showimages,andsoon.SpeedTracerintegratesSpringInsightdata,tyingbrowserperformancetobackendperformancewitharobustclient-serverapplicationperformancetool.IfyourwebapplicationusesAjaxandotherrichopenwebtechnologies,werecommendyoutrySpeedTracer withSpringInsight.

Fordetails,seeViewingSpringInsightDatainGoogleSpeedTracer.

HowSpringInsightWorksSpringInsightcapturesapplicationeventsknownastraces.Atracerepresentsathreadofexecution.ItisusuallystartedbyanHTTPrequestbutcanalsobestartedbyabackgroundjob.Atracecontainsoperations.Eachoperationrepresentsasignificantpointintheexecutionofthetrace,forexample,aJDBCqueryortransactioncommit.

Usingthisdata,SpringInsightcalculatessummaryinformationtoleadyoutothespecificsofwhyyourapplicationmaynotbeperformingaswellasitcould.

SpringInsightusesAspectJtointerceptoperationsintargetwebapplications.Targetwebapplicationsareloadedwithaspecialclassloaderthatdynamicallyinstrumentswebapplicationsatruntime.SpringInsightusessophisticatedalgorithmstokeepthememoryfootprintlow.However,SpringInsight-enabledserversrequiremorememory( -Xmx )thanastandardserver.

SpringInsightDeveloperandapplicationsruntogetheronasingletcServerruntimeinstance.SpringInsight’sleanframeworkkeepsdeveloperrequirementstoaminimum.DeveloperscandeployanativeapplicationtoaSpringInsightDeveloper-enabledtcRuntimeinstanceandimmediatelyseediagnostics.Thereisnodatabasetosetup,noinstrumentationtoperform.


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

KeyConceptsandTerminologyTargetapplication:AWebapplicationforwhichyouwanttomonitortherun-timeperformance.

Operation:Aninterface( Operation.java )thatplug-inscanimplementtostoreinformationaboutthecapturedworkbeingdone.AnOperationimplementationisanitemofwork,forexample,asocketopening,acachemiss,amethodcall,oraJDBCSELECT.Operationsaredefinedbyplug-insandcontainalltheinformationneededtocapturetheworkbeingdone.Note:OperationsmustbeserializableandcancontainonlyfieldsthatareclasseswithintheJDKortheplug-initself.

Frame:Representsaunitofexecutionwithinacallhierarchy.Typicallyaframeequatestoamethodcallinastack,butthisisnotalwaysnecessary.Aframecanbecreatedforanylogicaleventthataplug-indictates.Aframeholdsinformationaboutwhenaneventoccurredandabouttheframe’snestedrelationshiptootherframes.ThemeatoftheframelieswithintheOperation.

Trace:Arecordingofasinglethreadofexecutionforanapplication.Atracecanrepresentasinglewebrequest(andalltheworkitdid),oritcouldrepresentaJMSmessagelistener’sprocessingtimes.Atracecontainsanestedtreeofframes,whichcontainthedetailsoftheworkdone.

Endpoint:Logicalgroupingofsimilartraceswithinanapplication.HealthandresponsetimemetricsarecalculatedforEndPointsbasedonthetracesthatmatchthatEndPoint.EndPointsforagiventraceareidentifiedbyEndPointAnalyzersthatpost-processatraceafteritiscollected.AllEndPointAnalyzersknowntoInsightprocesseachtrace.Theanalyzerwiththehighestscore—thatis,theanalyzerthattheplug-indetermineshasmostcloselyidentifiedtheEndPoint—definesthetraceasbelongingtoaparticularEndPoint.EndPointsarevisibleintheInsightdashboardundertheBrowseResourcestab.Forexample,inaSpringMVCapplication,EndPointsaredefinedbythe@RequestMappingmethodthatreceivestherequestdispatch.AlltracesdispatchedtothesamemethodaremembersofthesameEndPoint.Inaproduction-readyapplication,atracepotentiallymatchesmultipleEndPoints.Forwebrequests,theSpringMVCcontrollerdefinesEndPoints,butnotallwebrequestsareprocessedbySpringMVC.TherawServlettowhichtherequestwasinitiallymappedcanalsodefineanEndPoint.Inthiscase,themorespecificEndPointcontainsthetrace;theSpringMVCEndPointtrumpstheServletEndPoint.

Aspect:PrimarymechanismusedbySpringInsightplug-instocollectruntimedataaboutauser’sapplication.AspectsinSpringInsighttypicallyhavetheroleofcollectingdataaboutthetargetapplicationandstoringitintoimplementationsofanOperation.

SpringInsight:TheentiretyofOperationcollection,EndPointanalysis,tracestorage,andtheuserinterface.


InstallandConfigureInsightDeveloperThissectionhasinstructionsforinstallingandconfiguringInsightDeveloper,anddocumentsthe inisght.properties file.

InstallInsightDeveloperToinstallSpringInsightDeveloper,youinstallPivotaltcServerDevelopereditionandthencreateanewtcRuntimeinstanceusingthe insight template.

1. FromthePivotaltcServerproductpage ,clickDownloads.

2. DownloadtcServerDeveloperedition.

3. CreateadirectoryfortcServer,forexample:/home/tcserver

4. UnpackthetcServerarchiveintothedirectorycreatedinthepreviousstep,suchthatthetcServerhomedirectoryisasub-directoryofit,forexample:

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

5. CreateatcServerinstancewhereInsightwillrun:

a. Inaterminalwindow,changetothetcServerhomedirectory.b. CreateatcServerinstancewith tcruntime-instance.sh or tcruntime-instance.bat ,usingthe insight template.

Forexample,tocreateaninstancenamed“Insight”,enterthefollowingcommand:

./tcruntime-instance.shcreateInsight-tinsight

6. StartthenewtcServerinstanceusingthe tcruntime-ctl.sh or tcruntime-ctl.bat command.OnUnix,tostartaninstancenamed“Insight”:

./tcruntime-ctl.shInsightstart

OnWindows,installaWindowsservicefortheinstancebeforeyoustartitthefirsttime(Afterthat,youcancontroltheservicefromtheWindowsservicescontrolpanel.)Toinstallaninstancenamed“Insight”asaWindowsservice,andthenstartit:

tcruntime-ctl.batInsightinstall

tcruntime-ctl.batInsightstart

7. DeployyourWebapplicationstotcServerbycopyingtheWARfilestothe webapps directoryofthetcruntimeinstance.Ifnecessary,updateconf/server.xml and conf/context.xml filestosupportthedeployedapplication.

8. AccesstheSpringInsightDashboardbyopening http://localhost:8080/insight inyourbrowser.

SeethePivotaltcServer3.xDocumentation formoredetailedinformationaboutinstallingandconfiguringtcServer.

ConfigureSpringInsightYouconfigureSpringInsightbyeditingthe insight.properties file,locatedinthe insight directoryofthetcRuntimeinstance.Forexample,thepropertiesfileforaninstancecalled insight-instance is tc-server/pivotal-tc-server-developer-x.x.x/insight-instance/insight/insight.properties .

Thepropertiesfilelistssupportedpropertiesin property:value form.Commentlinesbeginwith # .

Thefollowingtabledefinesthepropertiesyoucansetin insight.properties .

Table1.Propertiesoftheinsight.propertiesFile

(Optional)SpecifyapplicationcontextsthatyouwantSpringInsighttoignore,andnotinstrument.(Instrumentationcanincreaseapplicationstartuptime.)


http://www.pivotal.io/products/pivotal-tc-server

http://tcserver.docs.pivotal.io/docs-tcserver/topics/about-tc-server.html#about

application.context.ignore.identifier

Thedefaultvalue(shownbelow)excludestheInsightAgentfrombeinginstrumented.

Theformatforthispropertyis application.context.ignore.identifier:hostName|contextName

where:

identifier isavaluethatmakesthepropertynameuniqueinthepropertiesfile;Insightdoesnotusethevalue.Specifyanyidentifierthatismeaningfultoyou.

hostName identifiestheapplicationhost.

contextName istheURLcontextthatinvokestheapplication.ThisisgenerallyisthenameoftheWARfileinwhichtheapplicationispackaged,unlessitisotherwisespecifiedintheapplication’s web.xml file.

ThefollowingexampleignorestheTomcatManagerapplication,whichhastheapplicationcontext manager .

application.context.ignore.mgr:localhost|manager

Default:

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

database.driverClassName

SpecifiestheclassnameoftheJDBCDriverthatSpringInsightusestoconnecttothedatabase.

Default:

org.h2.Driver

database.password

SpecifiesthepasswordoftheuserthatconnectstothedatabasethatSpringInsightusestopersistitsdata.Default:

admin

database.url

SpecifiestheURLofthedatabasethatSpringInsightusestopersistitsdata.

Note:SpringInsightbundlestheH2JavaSQLdatabaseandusesitinternallytopersistitsdata.Bydefault,atcRuntimeinstanceconfiguredwithSpringInsightisconfiguredtousetheH2database.

Default:

jdbc\:h2\:\#{insightConfig.dataDir}/dashboard/dashboard;DB_CLOSE_DELAY\=-1;MVCC\=TRUE

database.username

SpecifiesthenameoftheuserthatconnectstothedatabasethatSpringInsightusestopersistitsdata.

Default:

insight

insight.data.dir

SpecifiesthefullpathnameofthedirectoryinwhichSpringInsightpersistsitsdata.

Default:

INSTANCE_DIR/insight/data .

insight.purge.interval.min

Specifies,inminutes,howfrequentlySpringInsightpurgestracesandresourcesfromthedatabase.

Default:


30

metric.max.granularity.sec

Specifies,inseconds,themaximumgranularityatwhichSpringInsightaggregatesmetrics.SpringInsightcollectsmetricsevery15seconds,andaggregatesmetricvaluesatvariousgranularitiesfromminuteuptothedefaultvalueofoneyear.

Default:

31,536,000 (oneyear)

trace.exclude.path.type

ThispropertyconfiguresSpringInsighttonotsavetracesforapplicationrequestswhoseperformanceyoudonotwishtotrack,suchasrequestsforstaticcontent.Youspecifytherequeststoignorebyspecifyingapattern(inantpathformat)againstwhichrequestsarematched.Insightdoesnotsavetracesthatmatchapathspecifiedby trace.exclude.path .

Specifyeachpathyouwishexcludedseparately,asshownintheexamplebelow.Thisexcerptfromthedefault insight.properties fileexcludestracesforrequestsforcontentofthefollowingtypes: .png , .gif , .jpg , .css .,and .js :

Default:

trace.exclude.path.png:/**/*.pngtrace.exclude.path.gif:/**/*.giftrace.exclude.path.jpg:/**/*.jpgtrace.exclude.path.css:/**/*.csstrace.exclude.path.js:/**/*.js

trace.purge.batch

SpecifieshowmanytracesSpringInsightpurgeseachtimeitperiodicallypurgestracesfromthedatabase.

Default:

500

trace.max.memory.mb

Themaximumamountofmemory,inMB,thatisavailablefortracestorage.Whenthisthresholdisreached,tracesarerandomlyremoved,witholdertracesremovedfirst.

Default:

40

trace.purge.expiry.days

SpecifieshowmanydaysSpringInsightsavestracesbeforepurgingthemfromthedatabase.

Default:

7

resource.purge.batch

SpecifieshowmanyresourcesSpringInsightpurgeseachtimeitperiodicallypurgesresourcesfromthedatabase.Notethat,regardlessofthevalueofthisproperty,SpringInsightonlypurgesresourcesthatarenotreferencedbyanytraces.

Default:

40

IncreasingMemorywhenUsingSpringInsight


WhenyoumonitoranapplicationwithSpringInsight,youneedtotakeintoaccountthememoryrequirementsofInsightitself.ItmaybenecessarytoincreasethememoryavailabletotcRuntimetoensureenoughmemoryisavailableforboththemonitoredapplicationandSpringInsight.Pivotalrecommends256MBpermgenforanapplication,dependingonthecomplexity.WiththeSunJVM,youincreasethesizeofthePermanentGenerationusingthe -XX-MaxPermSize JVMoption.

ToincreasethememoryusedbytcRuntime,editthe CATALINA_BASE/bin/setenv.sh|bat file,where CATALINA_BASE referstotherootdirectoryofyourinstance,suchas /home/tcserver/pivotal-tc-server-developer-2.x.x.x/insight-instance .ThecommentsinthefileitselfshowexamplesofsettingtheJVMoptions.


UsingSpringInsightSpringInsightDeveloperenablesyoutoseewhatyourapplicationisdoingunderthehoodof @annotated APIsorproxiedobjects.Popularframeworksoftodayhidetremendouspowerbehindfriendlyfacades.Forexample,asimple session.save(book) thatusesHibernatecanexecutehundredsofJDBCcalls,dependingonyourmapping.SpringInsightbringstheselow-levelperformance-orientedoperationstothescreenforquickevaluation.

BeforeYouBeginBeforeyoustartusingSpringInsight:

InstalltcServerDeveloperEditionandcreateatcRuntimeinstanceusingtheSpringInsighttemplate.SeeInstallingandConfiguringSpringInsight.

StartthetcRuntimeinstance,deployyourWebapplicationtotheinstance,configureallofitsresources(suchasanyrequiredJDBCdatasources),andmakesureyourapplicationisrunningandreadytobeused.

TodeployaWebapplicationtoatcRuntimeinstance,copyitsWARfileorexplodeddirectorytothedeploymentdirectory,whichbydefaultisCATALINA_BASE/webapps where CATALINA_BASE istherootdirectoryofthetcRuntimeinstance.

Forexample,assumethatyoucreatedaninstancecalled insight-instance usingtheprovided insight templateandthatyouhavealreadystartedtheinstance.Furtherassumethatthe CATALINA_BASE ofthisinstanceis /home/tcserver/pivotal-tc-server-developer/insight-instance andthatthefullpathnameofyourWebapplicationis /home/apps/myApp.WAR .TodeploythisapplicationtothetcRuntimeinstance,executethefollowingcommand:

prompt$cp/home/apps/myApp.WAR/home/tcserver/pivotal-tc-server-developer/insight-instance/webapps

ForcompletedocumentationabouttcServer,seethePivotaltcServer3.xDocumentation .

InvokeSpringInsightFollowthesestepstoinvokeSpringInsightinyourbrowserandtostartseeingtracedata.

1. BrowsetotheSpringInsightdashboardatthefollowingURL:http://localhost:8080/insight

Note:InSpringInsightDeveloper,youcanaccesstheSpringInsightdashboardonlyfromthe localhost .ThebrowserinvokesthemainSpringInsightdashboardontheBrowseResourcesscreen:

2. InitiateactivitybyusingyourWebapplication;theexactstepsdependonwhatyourapplicationactuallydoes.SpringInsighttracesallapplicationactivityanddisplaysitonthedashboard.Forexample,ifyouperformedanyJDBCqueries,eachoneisshownintheSpringInsightdashboardalongwithatimelineofrecentrequests.

BrowseApplicationsandEndPointsThefollowingproceduredescribeshowtobrowsetheapplicationsdeployedtothetcRuntimeinstanceandtheirEndPoints,andviewhealth,throughputtrends,responsetimetrends,andresponsetimehistograms.

TheBrowseResourcesscreenshowsinformationforalltypesofapplications,butprovidesmoredetailforSpring,Grails,andRooapplications.


http://tcserver.docs.pivotal.io/docs-tcserver/topics/about-tc-server.html#about

1. FromthemainSpringInsightdashboard,clicktheBrowseResourceslink:

TheApplicationspanelontheleftdisplaysatreecontrolofallapplicationsthathavereportedTraces;youcanexpandeachapplicationtoseeitslistofEndPoints.Thehealthoftheapplicationisdisplayednexttoitsnameandrepresentstheworst-performingEndPointwithintheApplication.EachEndPointalsodisplaysitshealth,whichisdescribedlateroninthisprocedure.SpringInsightloadstheresourcetreewhenitloadsthepage.IfyousubsequentlydeployanewapplicationorSpringInsightdetectsnewEndPoints,itautomaticallyaddstheseresourcesintotheresourcetree.TheApplicationsHealthTrendpanelontherightshowsagraphoftherecenthealthofallapplications.Thehealthofeachapplicationisgraphedinadifferentcolorsoyoucandifferentiatethem.Thetableinthelowerpanelpresentsthefollowinginformationforeachapplication:

HealthTrend—Sparklinethatgraphicallydescribestherecenthealthoftheapplication.Throughput—HowmanyTracesperMinute(tpm)wereexecutedoverthecurrenttimewindow.Errors—PercentageofTracesthatresultedinanError(HTTPstatus500to600).

Thegraphicalortabularviewofallapplicationsisusefultoseewhichapplicationshavebeenbusiestandtocomparetheirrelativehealth.Clickinthegraphstoseetheapplication-specificinformation.Clickthecolumnheadersinthetabletosorttheinformationbasedonthecolumn.

2. ClickonanapplicationintheleftApplicationspanel.Therightpaneldisplayssimilarinformationabouttheapplicationasintheprevioustable,butthistimethegraphcontainsinformationonlyaboutthespecificapplicationanditsEndPoints.TheEndPointspaneldisplaystheEndPointsassociatedwiththeapplication;thesamelistappearsbelowthenameoftheapplicationintheleftApplicationspanel.

TheVitalssectionshowsasummaryofthehealthoftheapplication.EachrowintheEndPointstablerepresentsanEndPoint,whichisareceptorforrequests.TheuniverseofallpossibleHTTPURLsisunlimited.However,SpringInsightcangrouprequeststogetherbasedonthecontrollerswithwhichtherequestsareassociated.ForeachEndPoint,SpringInsightdisplaysthefollowinginformation:

Health—Showshowwelltheresponsetimemetriciskeptwithinatolerablethreshold,whereredislesshealthyandgreenismorehealthy.SeeCustomizingEndPointThresholdsforhelpsettingthetolerablethreshold.EndPoint—ThenameoftheEndPoint.HealthTrend—SimplesparklinethatshowstherecenthealthoftheEndPoint.Throughput—NumberofTracesperMinute(tpm)executedoverthecurrenttimewindow.Errors—PercentageofTracesresultedinanError(HTTPstatus500to600).ResponseTime—The95%responsetimeoverthegiventimerange.Thisvalueisusefultodeterminetheworst-caserequest.Avalueof115msindicatesthat95%oftherequestscompletedwithin115milliseconds.TheresponsetimeofanHTTPrequestisthefulltimethecontainertakestosendtheresponsetotheclient,notjustthetimespentinacontroller.

3. ClickonaparticularEndPoint,eitherintheleftApplicationspanelorintherightEndPointstable:


SpringInsightdisplaysthefollowingdetailedinformationabouttheEndPoint:TheEndPointchartshowsthe

throughputtrend—therecentmeanthroughputtimeoftheEndPointoverthetimerangeresponsetimetrend—themeanresponsetimeoftheEndPointoverthetimerangeerrorrate—percentageoftracesthatresultedinanerror.Hoveroveranyspotinthecharttoviewdetailsforthetimeslicerepresentedbythatsectionofthechart.Clickonadatapointtoseetracedatathatoccurredduringthattimerange.

TheVitalssectiondisplaysthemeanthroughput,totalnumberofInvocations,anderrorsforallofthetracesinthetimerangerepresentedonthecurrentchart.TheResponseTimesectiondisplaysstatisticsabouttheresponsetimesforallofthetracesrepresentedonthecurrentchart.The95thPercentilestatisticindicatesthat95percentofrequestscompletedwithintheindicatedtimeperiod.TheMeanistheaverageresponsetime.TheStandardDeviationisameasureofthevariabilityofresponsetimes.Alargerstandarddeviationindicatesagreatervariabilityinresponsetimes.TheResponseTimeHistogramisaninteractivegraphthatshowshowmanyinvocationsoccurredwithinagiventimeperiod.TheY-axisrepresentstheresponsetimeofaninvocation.TheX-axisrepresentsthenumberofinvocations.Usingthehistogramisaneasywaytoidentifyoutliersinyourdata.Thelongest-runninginvocationsarealwaysatthetopofthehistogram.Ifextremeoutliersexist,theyareindicatedbyredbars.TheHealthoftheEndPointisdeterminedbytheResponseTimeforrequestsmadeoverthegiventimeinterval.TheresponsetimesarebrokendownintovariousHealthZones(suchasfrustrated,toleratedorsatisfied.ClickonaparticularHealthZonetoseerepresentativeTraceswithinthatzone.

4. ClickabarinthehistogramorononeofthemarkersintheThroughputorResponseTimeTrendgraphs.ARepresentativeTracespanelshowsrepresentativetracesforsomeinvocationsthatoccurredduringtheselectedduration.


TheRepresentativeTracespanelincludessimilardataasthatoftheRecentActivityscreen.Fromhereitiseasytodrillintotheshortestorfastestrunningtracestoseewhatmadethemdifferent.SeeViewingRecentActivityofYourApplicationfordetailedinformationabouttracesandtracedetails.

ViewingRecentActivityofYourApplicationThefollowingproceduredescribeshowtogetanoverviewoftherecentactivityofaparticularapplication,orforallapplicationscurrentlydeployed,andthenhowtodrilldowntothedetailsofaparticularapplicationevent.

1. FromthemainSpringInsightdashboard,clicktheRecentActivitytab:TheRecentActivityscreendisplaystracesfromyourapplication.Atraceisabreakdownoftheactivityofarequest.TheRecentActivityscreenanswersthequestionWhatjusthappened?

2. Inthetop-rightApplicationSelectordrop-downbox,selectthenameofyourapplication.UsetheApplicationSelectortoviewactivityforallapplicationsorforjustasingleone.ViewingallapplicationsatonceisusefulwhenyoudeploymanyWebapplicationsandareinterestedinactivityacrosstheentireset.Viewingasingleapplicationfiltersoutactivitynotrelatedtothatapplication.TheTraceHistorypanelshowsatimelineoftherecentactivityofyourapplicationasreal-timerequests,representedbybarsinthechart.Eachbarrepresentsallrequeststhatoccurredwithinatimeslice,asmeasuredbythechart.Thefulltimerangehas60timeslices.Theheightofthebarisequaltothelongestrequestthatoccurredduringthatwindow.TheTraceHistorygraphshowsactivitythatSpringInsighthasmonitoredoverthepastNminutes.WhenSpringInsightcapturesatrace,itdrawsanewbaronthegraphontheright-handside.Astimepasses,barsmoveleftuntiltheyfalloutofthetimerange.


Clickonbarstodrilldeeper.

3. ClickonabarintheTraceHistorychart.SpringInsightdisplaysalistoftracesintheTracespanelthatexecutedduringthewindowoftime(ortimeslice),andthendetailsaboutaspecifictrace.SpringInsightautomaticallyshowsdetailsaboutthefirsttraceintheTraceDetailspanel.Ifyouclickonadifferenttrace,SpringInsightrefreshesthedetailspanelwithcorrespondinginformation.TheSpringInsightdashboardshowstheTracesandTraceDetailpanels.

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

4. ClickonatraceintheTracespaneltoviewitsdetailsintheTraceDetailpanel.

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

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

Clickonanoperation’slabel,ortheentirerow,todrillfurtherintotheoperationdetails.Thedetailsofthispanelarespecifictoeachtypeofoperation,andcontainthefinestgranularityofcollecteddata.


ClickonFiltertofilterthetracedetailsshowninthepanel.SeeFilteringTraceDetailsforadditionaldetailsaboutthisfeature.ClickonRelatedTotonavigatetotheTrace’scorrespondingEndPointorapplicationintheBrowseResourcestab.Thisbuttonisusefulwhenyouwanttoseehowsimilarrequests(requeststothesameEndPointorapplication)haveperformedovertime.Visualindicators:-Alightbulbicongivesavisualexplanationtohoweachtraceisclassifiedasbelongingtoaspecificendpoint.Forexample,inthescreenshotbelow,theframerepresentingthe HotelsController search methodisselectedasthemostimportantframeinthetrace.-Abarabovethetracedetailpanedisplaysdetailsofanhttprequestthatresultedinanerror.

5. ThebuttonsabovetheApplicationSelectorhelpyoucontroltheinformationyouseeintheSpringInsightdashboardandperformadditional

administrativetasks: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.

FilteringTraceDetailsDependingonthenatureofaspecifictrace,thelistofoperationsinthecorrespondingTraceDetailpanemightbeverylong.SpringInsightusessmartcollapse,whichmeansitcollapsesthoseoperationsitthinksareunimportantbutexpandsoperationsthataremostlikelyinterestingtoyou.However,theTraceDetailspanecouldstillbeverylarge.Inthiscase,youmightwanttofilterthelistofoperationstodisplayonlycertaintypesthatinterestyou.

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

Thedefaultlistoffiltersisasfollows:

Database:Filtersoperationsbasedonwhethertheyarerelatedtogeneraldatabasecalls.Thiscouldincludetransactionsaswellasstandardcallstoarelationaldatabase,forexample.

JDBC:FiltersoperationsbasedonwhethertheyareJDBCcalls.TheresultsofthisfilterareasubsetoftheresultsoftheDatabasefilter.

Servlet:FiltersoperationsbasedonwhethertheyareServletoperations,includingoperationssuchasauthentication,sessionmanagement,andhandlingrequestsandresponses.

Web:FiltersoperationsbasedonwhethertheyarerelatedtoWebcalls,suchasHTTPrequestsandresponses,renderingofHTMLpages,andsoon.TheresultsofthisfilterareasubsetoftheresultsoftheServletfilter.

Filtersaretri-state—youcanseteachfiltertooneofthreedifferentstates:

Unselected–operationsareincludedintheresultsunlessoneormoreotherfiltersaresetto+(plus)

+(plussign)–onlytheseoperationsareincludedintheresults

-(minussign)-onlytheseoperationsareexcludedfromtheresults


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

Tousefilters,followthesesteps:

1. DisplaytheTraceDetailspaneforaparticulartraceyouareinterestedin.SeeViewingRecentActivityofYourApplication.

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

3. ClicktotheleftoftheFilterdrop-downlisttoactuallyapplythefilter.AmessageappearsbelowtheTraceDetaillabeltoalertthatafilterisbeingapplied.Afterapplyingthefilter,thetracedetailsnavigationtreeissmaller,andonlydetailsincludedmeetthespecifiedfilterconditions.Becauseofthestickinessofthefilter,asyounavigateawayfromyourcurrentpageyou’llnoticethatSpringInsightcontinuestoapplythefilter.

4. Toremovethefilter,clickonthe X totheleftofthe Filterappliedtotrace alert.

ExportingandImportingTracesWiththisfeature,youcanexportatracetoafileandthenimportitintoeitherthesameordifferentinstanceofSpringInsight.ThisfeatureisusefuliftheSpringInsightuserwhocapturedthetraceinrealtimewantstolookatitatalatertime,orhanditofftoanotherperson.

Forexample,assumethataQAengineeristestingtheircompany’sWebapplicationandrunsintoanerror,oranoperationtakesanexcessivetimetocomplete.TheQAengineerusesSpringInsighttotakealookatwhatjusthappenedbynavigatingtotherelevanttraceandviewingitsdetails.IftheQAengineerdecidestoopenabugabouttheproblem,theycanexportthetracetoafileandthenattachthisfiletothebugissuesothatthedevelopercantakealookatalaterdate.Thedeveloperdoesnotneedtoactuallydeploytheapplication;rather,theycanlookatthetracedetailstofigureoutwhichoperationcausedtheerror,wheretheexcessivetimeoccurred,andsoon.Thisisaneasywaytocaptureacompletesetoftraceinformationaboutanerrorevent,eveniftheeventisnotreliablyreproducible.

YoucanonlyimporttracesthatwerepreviouslyexportedfromaSpringInsightinstance.

Toexportatrace:

1. DisplaytheTraceDetailspanefortheparticulartraceyouwanttoexport.SeeViewingRecentActivityofYourApplication.

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.

5. SpringInsightimmediatelytakesyoutotheRecentActivitypagewiththetraceanditsdetailsdisplayed.TolocatethetraceintheTraceHistorypane,gobackintimetowhenthetracewasoriginallyexported.

CustomizingEndPointThresholdsThehealthofanEndPointisbasedonhowmanytracestooklongertoexecutethantheresponsetimethreshold.

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,whenyouchangetheresponsetimethresholdforanEndPoint,youchangethecriteriathatSpringInsightusestodecidewhetheritishealthyornot.

ThefollowinggraphicshowsthehealthandresponsetimehistogramforanEndPointwhosethresholdisthedefault(200ms):

Theupperlimitinthehistogramof800ms,andthesatisfied rangeisunder200ms.Aresponsetimeofover200msbutunder800msistolerated,butover800msisfrustrated,orunhealthy.

AllresponsetimesareunderthedefaultthresholdsotheEndPointishealthy.Iftheresponsetimesareallsignificantlybelowthedefaultthreshold,itmightbeagoodcandidatetolowerthethresholdtogetmorefine-grainedresponsetimeinformation.

TochangethethresholdforanEndPointorsetofEndPoints:

1. FromthemainSpringInsightdashboard,clicktheAdministrationtab.

2. ClickEndPointThresholdsintheleftpane.

3. Intherightpane,clickNew:


4. IntheRulefield,enteraregularexpressionthatcorrespondstotheEndPointorEndPointsforwhichyouwanttochangethethreshold.For

example,ifyouwanttospecifyall show methods,enter .*show.* :

5. Enterthenewthreshold.Asdescribedabove,thedefaultSpringInsightthresholdis 200 milliseconds.

6. Clickthepencilicon.Thenewruleappearsinthetable.TheMatchingEndPointscolumnshowsthenumberofEndPointsthatmatchthisrule;thenumberisalink.ClickonthislinktoseethelistofmatchingEndPoints.

7. ClickMakePermanenttoapplyyourchanges.

8. Ifyouhavethreeormorerules,youcanusetheupanddownarrowbuttonstochangetheorderinwhichSpringInsightappliestherules.SpringInsightappliestherulesfromfirstinthelisttolast.Thedefaultrule( .* )shouldalwaysbelast,sinceitmatchesallendpoints.

9. Browsetoatracethatmatchestherule.Notethatthey-axisoftheResponseTimeHistogramnowhasanupperlimitof4-timesthenewthreshold.ThehealthoftheEndPointisnowsatisfiedwhenitsresponsetimeisbelowthenewthreshold.Inourexample,thenewthresholdis100msandso

theupperlimitis400ms:

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

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

ToseeSpringInsightTracedatawithinSpeedTracerforanapplicationdeployedtoSpringInsight,followthesesteps:

1. DeployyourapplicationtoatcRuntimeinstancethatisconfiguredwithSpringInsight.

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


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

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

3. OpenuptheSpeedTracerconsolebyclickingonthestopwatchiconinthetop-rightcorneroftheGoogleChromebrowser.

4. UsingGoogleChrome,navigatetoapageofyourdeployedapplicationandperformsomeaction.

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

graphicinthenextstep.

6. ExpandtheresourcetoviewtheSpringInsightdata,listedundertheServerTracesection.ThissectionincludesabriefsummaryoftheTraceframestackandallowseasynavigationintovariouspartsofSpringInsightrelatedtothegivenTrace.Toseemoredetailedinformation,selecttheTrace,EndPointorApplicationlinks,whichwilljumpintoSpringInsightattheappropriatelocationsoyoucanfurtherdrilldown.

UsingAnnotationsToCustomizeSpringInsightDataForYourApplicationSpringInsightisimplementedasacollectionofplug-ins,eachofwhichexposesspecifictypesofmethodcalls.SpringInsightincludesadefaultsetofcoreplug-insthatexposeabroadsetofinformationaboutyourapplication.Forexample:

The insight-springcore plug-inallowsallmethodsinyourapplicationthathavebeenannotatedwiththeSpringFramework @Service or@Repository annotationstobetracedbySpringInsight.

The insight-jdbc plug-inallowsallcallsto PreparedStatement.execute() inyourapplicationtobetracedbySpringInsight.

SeeCorePlug-InReference forthefullsetofcoreplug-insthatareincludedbydefaultinSpringInsight.

ThedefaultsetofcoreSpringInsightplug-insexposesusefulinformationaboutapplicationsingeneral.However,theseplug-insmaynotprovideasmuchvisibilityintoyourparticularapplicationasyoumightlike.Inthiscase,youcanaddSpringInsight-specificannotationstotheJavasourceofyourapplicationtoinformSpringInsightthatitshouldtraceandexposeoneormoreparticularmethodsinyourapplication.Currently,SpringInsightsupportsthefollowingannotations:

@InsightCustomEndpoint

@InsightOperation

@InsightEndPoint

@InsightEndPointQualifier

@InsightObscure

@InsightSensitive

ForacodeexampleandascreenshotofSpringInsightannotationsinaction,seeExampleofUsingtheSpringInsightAnnotations.

Ifyouneedtoexposeevenmoredetailedinformationaboutyourapplication,usetheSpringInsightDeveloperKittocreateaplug-intailoredtotheexactneedsofyourapplication.Fordetails,seeOverviewofSpringInsightDevelopment .

@InsightCustomEndpointSpecifyan InsightCustomEndpointGenerator implementationthatgivesyoufullcontrolovertheendpointdetails(name,label,score,andsoon)andevenwhethertogenerateanendpointornot:


http://tcserver.docs.pivotal.io/docs-tcserver/topics/reference-plugin.html#reference-plugin

http://tcserver.docs.pivotal.io/docs-tcserver/topics/overview-plugin.html#overview-plugin

packagefoor.bar;

publicclassBaz{@InsightCustomEndpoint(MyBazEndpointGenerator.class)publicvoidmySuperDuperMethod(intn,Strings,Map<x,y>m){...}}

packagecom.springsource.insight.annotation;

/***Usedtogenerateacustomendpointanalysisfrominterceptedannotatedcall*/publicinterfaceInsightCustomEndpointGenerator{/***Usedtoinquirewhethertheinterceptedcallisgeneratingandendpoint*@paramtargetThetargetinstanceonwhichthemethodwasinvoked*@parammethodTheinvoked{@linkMethod}*@paramargsTheruntimeparametersvalues*@return<code>true</code>ifanendpointshouldbegenerated.*<B>Note:</B>if<code>false</code>thentheothermethodsarenotinvoked*/booleanisEndpoint(Objecttarget,Methodmethod,Object[]args);

/***Generatestheendpointnameidentifier*@paramdefaultNameThedefaultendpointnamegeneratedbytheframework*@paramtargetThetargetinstanceonwhichthemethodwasinvoked*@parammethodTheinvoked{@linkMethod}*@paramargsTheruntimeparametersvalues*@returnTheendpointnameidentifier-if<code>null/empty</code>then*thedefaultnameisused*/StringcreateEndpointName(StringdefaultName,Objecttarget,Methodmethod,Object[]args);

/***Generatestheendpointdisplaylabel*@paramdefaultLabelThedefaultlabelgeneratedbytheframework*@paramtargetThetargetinstanceonwhichthemethodwasinvoked*@parammethodTheinvoked{@linkMethod}*@paramargsTheruntimeparametersvalues*@returnTheendpointdisplaylabel-if<code>null/empty</code>then*thedefaultlabelisused*/StringcreateEndpointLabel(StringdefaultLabel,Objecttarget,Methodmethod,Object[]args);

/***@paramtargetThetargetinstanceonwhichthemethodwasinvoked*@parammethodTheinvoked{@linkMethod}*@paramargsTheruntimeparametersvalues*@returnTheendpointanalysisscore-if<code>null</code>,thenthedefault*frameworkscorewillbeused(i.e.,reverseddepth)*/IntegercalculateEndpointScore(Objecttarget,Methodmethod,Object[]args);}

@InsightOperationSpecifythatSpringInsightshoulddisplaytheannotatedmethodanditsargumentsintheSpringInsightTraces.Usetheoptional label and comment

attributestocustomizethedisplay,asdescribedinthefollowingtable.

Table1.Attributesof@InsightOperation

label

SpecifieswhatSpringInsightdisplaysintheTraceframestackforthismethod.AframeistherowintheTracethatyoucanexpandorcollapsesoastoviewmoreinformationaboutthemethodcall.

Ifyoudonotspecifythisattribute,SpringInsightusesthelabelClass#method ,suchas Hello#doGet .

comment

SpecifiesadditionalinformationthatyouwantSpringInsighttodisplaywhenyouexpandtheframe.Ifyoudonotspecifythisattribute,SpringInsightdoesnotdisplayanycomment.


@InsightEndPointLike @InsightOperation ,use @InsightEndPoint tospecifythatSpringInsightshoulddisplaytheannotatedmethodanditsargumentsintheSpringInsightTraces.Additionally,theannotatedmethodisdeclaredasanendpoint,whichmeansthatitshowsupintheBrowseResourcelistasanendpoint.Usetheoptional label and comment attributestocustomizethedisplay,asdescribedinthefollowingtable.Stringattributescancontainformattingmodifiersthatprovideaccesstotheinterceptedendpoint“context”.

packagefoor.bar;

publicclassBaz{@InsightEndPoint(name="{shortClassName}#{methodName}({signature})",label="Invoked{shortClassName}#{methodName}")publicvoidmySuperDuperMethod(intn,Strings,Map<x,y>m){...}}

Table2.Attributesof@InsightEndPoint

label

SpecifieswhatSpringInsightdisplaysintheTraceframestackforthismethod.AframeistherowintheTracethatyoucanexpandorcollapsesoastoviewmoreinformationaboutthemethodcall.

Ifyoudonotspecifythisattribute,SpringInsightusesthelabelClass#method ,suchas Hello#doGet .

commentSpecifiesadditionalinformationthatyouwantSpringInsighttodisplaywhenyouexpandtheframe.Ifyoudonotspecifythisattribute,SpringInsightdoesnotdisplayanycomment.

classNameFullyqualifiedclassnameoftheinterceptedendpointmethod,forexample, foo.bar.Baz

shortClassName Simpleclassnameoftheendpoint,forexample, Baz

methodName Interceptedendpointmethodname,forexample, mySuperDuperMethod

signature Methodparameters(simplified)types,forexample, int,String,Map.

n

Thevalueofthen-thparameter.Notes:

Thevalueofthen-thargumentcanbefurther“refined”byspecifyingabeanattribute,forexample, 0.name .

Thespecificationcanbe“cascaded”,forexample,0.name.firstName.alias.

Ifatanypointthespecifiedargumentdoesnotexist,doesnothavethespecifiedattribute,ornullisreturned,the“null”stringisused.

@InsightEndPointQualifierPlace @InsightEndPointQualifier onparametersofotherinterceptedAPIstoappenddatatothedefaultgeneratedendpointidentifier.Allstringattributesallowaccesstotheannotatedparametervalueviathe’.’(dot)notation—withthesamerefinementsasforthe @InsightEndPoint annotationformattingmodifierforaparametervalue.

packagefoor.bar;

publicclassBaz{@InsightEndPointpublicvoidmySuperDuperMethod(intn,@InsightEndpointQualifier(name="{.}",label="{.}")Strings,Map<x,y>m){...}}

@InsightObscure


Markvaluesthatshouldbeobscuredbeforeatraceistransmittedorstored.Toobscureaparameter,annotateit:

publicintlogin(Stringusername,@InsightObscureStringpassword){...dowork...}

Toobscureareturnvaluefromamethod,annotatethemethod:

@InsightObscurepublicintgetCCVNumber(AuthTokentoken){...returnccv;}

Obscuredvaluesarereplacedwith[xxx]or-1(fornumericvalues)withintheTrace.Iftwostringsthataretobeobscuredoverlap,thelongerstringswillbeobscuredfirst.e.g.“batman123”and“123456”aresensitive.Thevalue“batman123456”willbechangedto“[xxx]456”

@InsightSensitiveReferenceUse @InsightSensitive tomarkamethodthatprocessessensitivedata.TraceexecutionsincludingthisannotationwillnotbestoredorvisibleintheInsightDashboard.Metricsabouttheendpointwillstillbecollected.

@InsightSensitivepublicintlogin(Stringusername,Stringpassword){...dowork...}

ExampleofUsingSpringInsightAnnotationsThefollowingcodesnippetshowshowtousethe @InsightOperation and @InsightEndPoint annotationsinasimple Hello servletJavaclass;onlyrelevantcodeisshown(inbold):

packageexamples;...

importcom.springsource.insight.annotation.InsightOperation;importcom.springsource.insight.annotation.InsightEndPoint;

/***SimpleHelloservlet.*/

publicfinalclassHelloextendsHttpServlet{

@InsightOperation(comment="ThisistheInsightOperationcomment",label="doGetmethodofHelloclass")@InsightEndPoint(comment="ThisistheInsightEndPointcomment",label="doGetmethodofHelloclass")

publicvoiddoGet(HttpServletRequestrequest,HttpServletResponseresponse)throwsIOException,ServletException{...

Theexampleshowshowtoimportthe com.springsource.insight.annotation.InsightOperation and com.springsource.insight.annotation.InsightEndPoint annotations,thenusethemonthe doGet method.ThefollowinggraphicshowshowthecommentsandlabelsshowupintheTraceDetailssectionofSpringInsightaftertheannotatedmethodisexecuted:


GettingtheAnnotationJARFileTheSpringInsightcontainerprovidesthe insight-annotation-version.jar fileatruntime,soyoudonothavetopackagethisJARfileinyourapplication.However,youdoneedthisJARfileatcompiletimesoyoucansuccessfullycompiletheJavaclassesinyourapplicationthatusestheSpringInsightannotations.

IfyouuseMaventobuildyourapplication,addthefollowingXML(showninboldinthesnippet)toyourpom.xml filetomaketheJARfileavailabletoyourproject:

<repositories><repository><id>spring-release</id><name>SpringRepository</name><url>http://maven.springframework.org/release</url></repository>...</repositories>

<dependencies><dependency><groupId>com.springsource.insight</groupId><artifactId>insight-annotation</artifactId><version>1.8.3.RELEASE</version><scope>provided</scope></dependency>...</dependencies>

Notethattheprecedingexampledependsonversion 1.8.3.RELEASE oftheSpringInsightJAR;whenanewversionreleases,youshouldmakethecorrespondingchangeinyour pom.xml file.

IfyouuseabuildsystemotherthanMaven,youcandownloadtheannotationJARfilefromtheSpringSourcecommunity pageandthenaddthefiletoyourcompile-timeCLASSPATHvariable.

CreatingDynamicConcreteAspectsThissectiondescribeshowtoinstrumentclassesandmethodsthatarenotcoveredbyplugins.Youcreatedynamicconcreteaspectsbyeditingtheinsight/collection-plugins/custom-aop/META-INF/aop.xml file.

<?xmlversion="1.0"encoding="UTF-8"?><aspectj><aspects><concrete-aspectname="foo.bar.BazAspect"extends="com.springsource.insight.collection.method.custom.CustomConcretizedOperationCollectionAspect"><pointcutname="collectionPoint"expression="execution(*foo.bar.Baz.mySuperDuperMethod(..))"/></concrete-aspect></aspects></aspectj>

Thefollowingexamplesillustratedifferentdefinitionsofthe expression andtheeffectachievedbyeach.


http://www.springsource.org/insight/develop

Example1Monitorallpublicmethodsfromanyclassthatisannotatedwith @MyClassAnnotation :

execution(*(@foo.bar.MyClassAnnotation*).*(..))

Example2Monitorallpublicmethodsfromanyclassendingin Impl thatresidesinthefoo.barpackageoranyofitssub-packages:

execution(*foo.bar..*Impl.*(..))

Example3Monitorallpublicmethodsthatareannotatedwith @MyMethodAnnotation fromanyclass:

execution(@foo.bar.MyMethodAnnotation**(..))

Example4MonitorallpublicloginmethodsthataccepttwoStringparametersandthatareimplementedby MyClass oranyclassthatextendsit:

execution(*foo.bar.MyClass+.login(java.lang.String,java.lang.String))

Notes-Theprecedingsamplesarejustexamplesoftheinstrumentationyoucanimplementwithdynamicconcreteaspects.SeeAspectJdocumentationformoreinformation.

Youcannotrefertothevaluesofinterceptedmethodsarguments,formatthem,orparsethem.Norcanthesevaluesbeformattedandparsedforextrausefulinformation(atleastnotviathismechanism;lookattheInsightannotationsforthispurpose).

Instrumentonlypublicmethodswiththistool.Donotinstrumentconstructorexecutions,staticinitializers,orfieldaccess,eventhoughAspectJenablesthis.Theresultofstrayingfromthisrecommendationisunknown.

Youcandefineseveralaspectsinthisfile,eachaseparate<concrete-aspect>element.

Itispossibletoassignascoretotheendpointsgeneratedbytheaspectbyusingacollectionsettingnamedinsight.collection.custom-aop.XXX.score,whereXXXisthesimpleaspectname(ineffect,thenameafterstrippingthepackagename).Thesupportedvaluesare:

default .Theendpoint’sscoreisbasedonitslocationinthetracetree.ThehigherupthetreetheinterceptedAPIisfoundthehigheritsscore,anditismorelikelytobecometherepresentativeendpointforthetrace.Thisalsothedefaultscoringifnosettingisspecified.minimum .A“catch-all”scorethatindicatesthatifnoother“better”endpointisfound,thentheinterceptedAPIistheendpoint.top .Trumpstheminimumscore.ceiling .Trumpsthetopscore.nnnn .Afixedintegervalue;ifpositive,ittrumpsanyoftheotherscores(exceptotherhigherpositiveones).Note:Negativevaluesarereservedfor

internaluseandshouldnotbeused.

Youcamcontrolthegeneratedendpointname,label,andexamplestringsoftheendpointanalysisphaseusingtheinsight.collection.custom-aop.XXX.endPoint , insight.collection.custom-aop.XXX.resourceLabel andinsight.collection.custom-aop.XXX.example collectionsettings.Thesevaluescanalsoincludedynamicmodifiers,suchastheclass/method

name,signatureandargumentvalues.SeetheUsingInsightAnnotationsfortheavailablemodifiersandtheirmeanings.

AnychangetotheXMLfilerequiresrestartingthemonitoredapplication.


table of contentstcserver.docs.pivotal.io/3x/docs/pdf/pivotal-tc-server-insight-dev-1.9.… · by...

Documents