APM Extensibility Guide

133 Pages·2016·0.97 MB·English

HPE Application Performance
Management
SoftwareVersion:9.30
APM Extensibility Guide
DocumentReleaseDate:July2016
SoftwareReleaseDate:July2016
APMExtensibilityGuide
Legal Notices
Warranty
TheonlywarrantiesforHewlettPackardEnterpriseproductsandservicesaresetforthintheexpresswarranty
statementsaccompanyingsuchproductsandservices.Nothinghereinshouldbeconstruedasconstitutingan
additionalwarranty.HPEshallnotbeliablefortechnicaloreditorialerrorsoromissionscontainedherein.
Theinformationcontainedhereinissubjecttochangewithoutnotice.
Restricted RightsLegend
Confidentialcomputersoftware.ValidlicensefromHPErequiredforpossession,useorcopying.Consistentwith
FAR12.211and12.212,CommercialComputerSoftware,ComputerSoftwareDocumentation,andTechnicalData
forCommercialItemsarelicensedtotheU.S.Governmentundervendor'sstandardcommerciallicense.
CopyrightNotice
©Copyright2005-2016HewlettPackardEnterpriseDevelopmentLP
TrademarkNotices
Adobe®andAcrobat®aretrademarksofAdobeSystemsIncorporated.
AMDandtheAMDArrowsymbolaretrademarksofAdvancedMicroDevices,Inc.
Google™andGoogleMaps™aretrademarksofGoogleInc.
Intel®,Itanium®,Pentium®,andIntel®Xeon®aretrademarksofIntelCorporationintheU.S.andothercountries.
iPodisatrademarkofAppleComputer,Inc.
JavaisaregisteredtrademarkofOracleand/oritsaffiliates.
Microsoft®,Windows®,WindowsNT®,WindowsServer®andWindowsVista™areeitherregisteredtrademarksor
trademarksofMicrosoftCorporationintheUnitedStatesand/orothercountries.
OracleisaregisteredtrademarkofOracleCorporationand/oritsaffiliates.
UNIX®isaregisteredtrademarkofTheOpenGroup.
Documentation Updates
Thetitlepageofthisdocumentcontainsthefollowingidentifyinginformation:
SoftwareVersionnumber,whichindicatesthesoftwareversion.
l
DocumentReleaseDate,whichchangeseachtimethedocumentisupdated.
l
SoftwareReleaseDate,whichindicatesthereleasedateofthisversionofthesoftware.
l
Tocheckforrecentupdatesortoverifythatyouareusingthemostrecenteditionofadocument,goto:
https://softwaresupport.hpe.com/group/softwaresupport/search-result?keyword=.
ThissiterequiresanHPEPassportaccount.Ifyoudonothaveone,clicktheCreateanaccountbuttonontheHPE
PassportSigninpage.
PDFVersionofOnlineHelp
ThisdocumentisaPDFversionoftheonlinehelp.ThisPDFfileisprovidedsoyoucaneasilyprintmultipletopics
fromthehelpinformationorreadtheonlinehelpinPDFformat.
Support
VisittheHPESoftwareSupportwebsiteat:https://softwaresupport.hpe.com
HPEApplicationPerformanceManagement(9.30) Page2of133
APMExtensibilityGuide
Thiswebsiteprovidescontactinformationanddetailsabouttheproducts,services,andsupportthatHPESoftware
offers.
HPESoftwareSupportprovidescustomerself-solvecapabilities.Itprovidesafastandefficientwaytoaccess
interactivetechnicalsupporttoolsneededtomanageyourbusiness.Asavaluedsupportcustomer,youcanbenefit
byusingthesupportwebsiteto:
Searchforknowledgedocumentsofinterest
l
Submitandtracksupportcasesandenhancementrequests
l
Downloadsoftwarepatches
l
Managesupportcontracts
l
LookupHPEsupportcontacts
l
Reviewinformationaboutavailableservices
l
Enterintodiscussionswithothersoftwarecustomers
l
Researchandregisterforsoftwaretraining
l
MostofthesupportareasrequirethatyouregisterasanHPEPassportuserandsignin.Manyalsorequirea
supportcontract.ToregisterforanHPEPassportID,gotohttps://softwaresupport.hpe.comandclickRegister.
Tofindmoreinformationaboutaccesslevels,goto:
https://softwaresupport.hpe.com/web/softwaresupport/access-levels
HPE Software Integrations,Solutionsand BestPractices
AccesstheHewlettPackardEnterpriseSoftwareSupportsite(https://softwaresupport.hpe.com/manuals)to
searchforawidevarietyofbestpracticedocumentsandmaterials.
HPEApplicationPerformanceManagement(9.30) Page3of133
APMExtensibilityGuide
Contents
ExtensibilityGuide Overview 8
Part1:Service Health 9
Chapter1:ServiceHealthRulesAPI 10
APIGroupandSiblingRule 11
APISampleRule 13
APIDuration-BasedSampleRule 14
CreatingRuleswiththeRulesAPI 15
HowtoDefineanAPIRuleintheCIIndicatorsTab 15
HowtoCreateaTextFile-BasedAPIRule 16
HowtoDefineanAPIRuleintheRuleRepository 20
HowtoWorkwithTooltipEntries 20
HowtoWritetoLogFilesFromtheRulesAPICode 21
HowtoIncludeaCIPropertyinRulesAPICalculations 22
Examples-APISampleRule 23
Example-AverageAvailabilityRule 23
Example-AveragePerformanceRule 24
Example-AveragePerformanceRuleUsingaRuleParameterFilter 24
Examples-APIGroupandSiblingRule 26
Example-WorstChildRule 26
Example-WorstSiblingStatusRule 27
Example-SpecificChildCIGroupRule 28
Example-SiblingRuleBasedonAvailabilityandPerformanceKPIs 29
Example-GroupAverageValuebyCIType 30
Example-WorstHealthIndicatorRule 30
Example-UsingGroovyClosure 31
Chapter2:ServiceHealthExternalAPIs 33
RetrieveIndicatorDataAPI 33
APISyntax 33
ReturnCodes 35
APISyntax 35
ReturnCodes 36
APISyntax 37
ReturnCodes 38
ResetHealthIndicatorStateAPI 38
ServiceHealthDatabaseQueryAPI 39
Part2:Service Level Management 42
HPEApplicationPerformanceManagement(9.30) Page4of133
APMExtensibilityGuide
Chapter3:SLMExternalAPI 43
GetSLAConfigurationData 43
APISyntax 43
ReturnCodes 45
GetSLACalculationResults 45
APISyntax 45
ReturnCodes 47
GetCalendars 47
APISyntax 47
ReturnCodes 48
GetTrackingPeriods 48
APISyntax 48
ReturnCodes 49
GetKPIs 50
APISyntax 50
ReturnCodes 51
GetIndicatorStatuses 51
APISyntax 51
ReturnCodes 52
Chapter4:SLMRulesAPI 53
APISimplifiedAverageRules 54
APIGroupandSiblingRule 55
AccessingaSpecificChildKPIintheKPIDefinitionPage 56
SampleRuleCalculationMechanism-Overview 57
SampleRules:CalculatingtheKPIBasedonSamples 57
SampleRules:CalculatingtheKPI'sAggregatedResults 58
WhentoUseSampleorDuration-BasedSampleRules 59
ExampleofAverageResponseTimeCalculation 59
APISampleRule 59
APIDuration-BasedSampleRule 61
Duration-BasedSampleContinuity 62
FilteringwiththeDuration-BasedSampleRule 63
APIOutagebySamplesRule 64
CreatingRuleswiththeRulesAPI 66
HowtoDefineanAPIRuleforaSpecificKPIorOutage 66
HowtoCreateaTextFile-BasedAPIRule 67
HowtoDefineanAPIRuleWithintheRuleRepository 70
HowtoWorkwithTooltipEntries 70
HowtoWritetoLogFilesFromtheRulesAPICode 72
HowtoIncludeaCIPropertyinRulesAPICalculations 73
Examples-APIGroupandSiblingRule 73
HPEApplicationPerformanceManagement(9.30) Page5of133
APMExtensibilityGuide
Examples-APISampleRule 73
Example-Sample-BasedAverageResponseTimeRule 74
Calculation-Sample-BasedAverageResponseTimeRule 75
Example-Sample-BasedAverageResponseTimeRulewithFilter 76
Calculation-Sample-BasedAverageResponseTimeRulewithFilter 77
Example-Sample-BasedMaximumResponseTimeRule 77
Calculation-Sample-BasedMaximumResponseTimeRule 78
Examples-APIDuration-BasedSampleRule 78
Example-Duration-BasedAverageResponseTimeRule 79
Calculation-Duration-BasedAverageResponseTimeRule 80
Example-Duration-BasedAverageResponseTimeRulewithisSampleValidMethodFilter 81
Calculation-Duration-BasedAverageResponseTimeRulewithisSampleValidMethod
Filter 81
Example-Duration-BasedAverageResponseTimeRulewithisSampleAndDurationValid
MethodFilter 82
Calculation-Duration-BasedAverageResponseTimeRulewith
isSampleAndDurationValidMethodFilter 82
Example-Duration-BasedAverageResponseTimeRulewithisSampleAndDurationValid
andisSampleValidMethodFilters 83
Examples-APIOutagebySamplesRule 84
Example-OutagebySamplesRuleandCalculationwithDefaultRuleParameters 84
Example-OutagebySampleCalculationwithMinimumDurationof900Seconds 86
Example-OutagebySampleCalculationwithMaximumDurationofOneHour 86
Example-OutagebySampleCalculationwithaSampleRepresentingTwoFailures 87
Chapter5:SLMWebServicesAPI 88
UsingtheSLMWebServices 88
SLMWebServices'Operations 89
Part3:UserManagement 93
Chapter6:UserAdminExternalAPI 94
GetAllGroups/Users 94
APISyntax 94
ReturnCodes 95
PostNewUser 96
APISyntax 96
ReturnCodes 97
GetSpecificUser 97
APISyntax 97
ReturnCodes 98
GetSpecificGroup 99
APISyntax 99
ReturnCodes 100
HPEApplicationPerformanceManagement(9.30) Page6of133
APMExtensibilityGuide
DeleteUserfromGroup 100
APISyntax 100
ReturnCodes 101
PostExistingUsertoaGroup 101
APISyntax 101
ReturnCodes 101
Part4:End UserManagement 103
Chapter7:EUMAdminOpenAPI 104
Part5:SiteScope 105
Chapter8:SiteScopePublicAPI 106
Part6:Service Health Analyzer 107
Chapter9:Groovy 108
GroovyForAnomalyDetection 108
GroovyforAnomalySeverity 110
GroovyforCustomDrilldownsfromtheSHAInvestigationUI 112
Part7:Downtime 117
Chapter10:DowntimeRESTService 118
DowntimeScheduleExamples 120
ExampleofaDowntimeSchedulewithOneOccurrence 120
ExampleofaWeeklyDowntimeSchedule 121
ExampleofaMonthlyDowntimeSchedule 121
DowntimeRESTExamplesusingJavaCode 121
DowntimeRESTExampleUsingGroovy 122
ImportExample 122
Part8:Reporting in APM 124
Chapter11:GenericReportingEngineAPI 125
DataReturned 126
QueryingwithaBrowser 126
UsingtheWebService 127
SupportedSQLSyntax 127
SupportedFunctions 128
QueryLimitations 129
Date-TimeValues 130
byTimeFunction 130
QueryExamples 131
Send Documentation Feedback 133
HPEApplicationPerformanceManagement(9.30) Page7of133
Extensibility Guide Overview
ThisguidedescribeshowtocustomizeApplicationPerformanceManagementapplications,extendtheir
functionality,anduseAPIstoperformoperations.Theguideisintendedforadministratorsandintegrators
whoneedtoestablishadvancedconfigurationsandextensions.Ifyouareanadministratorandneedtosetup
APM,firstrefertotheAPMApplicationAdministrationGuide.
Thisguideprovidesinstructionsforworkingwiththefollowing:
ServiceHealth.Fordetails,see"ServiceHealthRulesAPI"onpage10and"ServiceHealthExternal
l
APIs"onpage33.
ServiceLevel Management.Fordetails,see"SLMExternalAPI"onpage43,"SLMRulesAPI"onpage
l
53,and"SLMWebServicesAPI"onpage88.
EndUserManagement.Fordetails,see"EUMAdminOpenAPI"onpage104.
l
SiteScope.Fordetails,see"SiteScopePublicAPI"onpage106.
l
Downtime.Fordetails,see"DowntimeRESTService"onpage118
l
Reports.Fordetails,see"GenericReportingEngineAPI"onpage125.
l
HPEApplicationPerformanceManagement(9.30) Page8of133
Part 1: Service Health
HPEApplicationPerformanceManagement(9.30) Page9of133
Chapter 1: Service Health Rules API
Note:InAPMversions9.00andlater,therulesthatcalculateindicatorstatusesandvaluesbasedon
samples("APISampleRule"onpage13and"APIDuration-BasedSampleRule"onpage14)areusedto
calculatemetric-basedhealthindicators(HIs).
ThroughouttheRulesAPIdocumentation,youwillseereferencestovariousmethodsusedtocalculate
KPIs. InAPMversions9.00andlater, whencalculatingsample-basedvalues, thesemethodsare
usedtocalculatemetric-basedHIs.
ThischapterdescribeshowtousetheRulesAPItocreatenewbusinessrules.Businessrulesareusedto
calculateKeyPerformanceIndicators(KPIs).AKPImusthaveanassociatedbusinessrulethatdefineshow
theKPIiscalculated.ThedefaultServiceHealthrulesappearinthesectionUnderstandingtheService
HealthCalculationRulesintheAPMApplicationAdministrationGuide.
ItisrecommendedtocreateruleswiththeRulesAPI.TheRulesAPIenablesyoutocreaterulesusingthe
GroovyscriptinglanguagewithGroovyruntimeenvironment.UsersoftheRulesAPIshouldbefamiliarwith
GroovyandJava,andwithAPMadministrationandapplications.
TheRulesAPIclassesaredocumentedinJavadocformatintheHPRulesAPIReference.Thesefilesare
locatedinthefollowingfolder:
\\< GatewayServerrootdirectory>
\AppServer\webapps\site.war\amdocs\eng\doc_lib\API_docs\Rules_API\index.html.
Service Health API Rules
ThesearethetypesofServiceHealthAPIrules:
GroupandSiblingRule.ThisrulecalculatesKPIsbasedondatareceivedfromotherKPIs,ratherthan
l
fromoriginalsampledata.Fordetails,see"APIGroupandSiblingRule"onthenextpage.
SampleRule.ThisrulecalculatesKPIsbasedonoriginaldatatakenfromsamplefields;thenumberof
l
samplesincludedinthecalculationislimitedbyamaximumnumberofsamplesruleparameter.For
details,see"APISampleRule"onpage13.
Duration-BasedSampleRule.ThisrulecalculatesKPIsbasedonoriginaldatatakenfromsample
l
fields;adurationparameterdefineswhichsamplesareincludedinthecalculation.Fordetails,see"API
Duration-BasedSampleRule"onpage14.
Creating API Rules
RulescanbecreatedusingtheRulesAPIintheseways:
UsingtheCIIndicatorstabtocreatearuleforaspecificKPI.
l
UsingatextfiletocreateanewruleformultipleKPIs.
l
UsingacloneofanAPIruleintheRuleRepositorytocreateanewrule.
l
Thesewaysaredescribedin"CreatingRuleswiththeRulesAPI"onpage15.
Tooltips and Log Files
TodisplayKPIinformationintooltipswhenworkingwiththeRulesAPI,see"HowtoWorkwithTooltip
Entries"onpage20.
HPEApplicationPerformanceManagement(9.30) Page10of133