Features7777dd

OpenLiberty2020OpenLibertyRuntimeGuideBuildanddeploycloudnativeapplicationswithOpenLibertyLastUpdated:2020-11-20OpenLiberty2020OpenLibertyRuntimeGuideBuildanddeploycloudnativeapplicationswithOpenLibertyLegalNoticeCopyright2020IBMCorpCodeandbuildscriptsarelicensedundertheEclipsePublicLicensev1DocumentationfilesarelicensedunderCreativeCommonsAttribution-NoDerivatives4.
0International(CCBY-ND4.
0)AbstractThesetopicsprovideabriefintroductiontoOpenLibertyandlinkstoin-depthdocumentationresources.
TableofContentsCHAPTER1.
WHATISOPENLIBERTY1.
1.
OPENLIBERTYVERSIONINGCHAPTER2.
ZERO-MIGRATIONARCHITECTURE2.
1.
USERCONFIGURATIONFILES2.
2.
OPENLIBERTYFEATURES2.
2.
1.
Considerationsforusingnewfeatures2.
3.
EXCEPTIONSTOZEROMIGRATIONCHAPTER3.
DEPLOYMENTONOPENSHIFT3.
1.
RUNNINGAPPLICATIONSONOPENSHIFT3.
2.
OPENLIBERTYOPERATOR3.
3.
SEEALSOCHAPTER4.
FEATUREOVERVIEW4.
1.
USINGFEATURES4.
2.
ZERO-MIGRATION4.
3.
COMBININGFEATURES4.
4.
SUPERSEDEDFEATURESCHAPTER5.
SERVERCONFIGURATIONOVERVIEW5.
1.
CONFIGURATIONFILES5.
1.
1.
server.
env5.
1.
2.
jvm.
options5.
1.
3.
bootstrap.
properties5.
1.
4.
server.
xml5.
2.
VARIABLESUBSTITUTION5.
3.
CONFIGURATIONMERGING5.
3.
1.
Mergingsingletonconfiguration5.
3.
2.
Mergingfactoryconfiguration5.
4.
INCLUDEPROCESSING5.
5.
CONFIGURATIONREFERENCES5.
6.
DYNAMICUPDATES5.
7.
LOGMESSAGESCHAPTER6.
OPENLIBERTYOPERATOR6.
1.
WHATISTHEOPENLIBERTYOPERATOR6.
2.
OPERATORCAPABILITIES6.
3.
SERVICEABILITYANDOBSERVABILITYWITHTHEOPENLIBERTYOPERATOR6.
4.
OPERATORINSTALLATIONANDCONFIGURATION6.
5.
SEEALSOCHAPTER7.
DEVELOPMENTMODE7.
1.
RUNOPENLIBERTYINDEVMODE7.
1.
1.
Detect,recompile,anddeploycodechanges7.
1.
2.
Rununitandintegrationtestsondemand7.
1.
3.
Attachadebuggertotherunningserver7.
1.
4.
VSCodeextensionfordevmode7.
2.
SEEALSOCHAPTER8.
THREADPOOLTUNING8.
1.
THREADPOOLTUNINGBEHAVIOR8.
1.
1.
Hangresolution4455555777788899111111121213131515161617171719191920202021212121222222232324TableofContents18.
2.
MANUALTHREADPOOLTUNING8.
3.
SEEALSOCHAPTER9.
LOGGINGANDTRACING9.
1.
LOGGINGCONFIGURATION9.
2.
EXAMPLELOGGINGCONFIGURATION9.
2.
1.
Managinglogfilestorage9.
2.
2.
JSONlogging9.
2.
3.
ConfiguringloggingforaDockerimage9.
2.
4.
Binarylogging9.
3.
CONFIGURATIONSETTINGSBYSOURCECHAPTER10.
TRUE-TO-PRODUCTIONINTEGRATIONTESTING10.
1.
DEVELOPMENTANDPRODUCTIONPARITY10.
2.
WRITINGINTEGRATIONTESTSWITHTHEMICROSHEDTESTINGLIBRARY10.
3.
SEEALSOCHAPTER11.
DEBUGGING11.
1.
MANAGINGBUILDPROCESSESWITHTHEOPENLIBERTYMAVENPLUG-IN11.
2.
TRACINGREQUESTSCHAPTER12.
MONITORINGOPENLIBERTY12.
1.
MONITORINGWITHMETRICS12.
1.
1.
MicroProfileMetricsandthe/metricsendpoint12.
1.
2.
JMXmetrics12.
1.
3.
Bothtypesofmetricscombined12.
2.
HEALTHCHECKSFORMICROSERVICES12.
2.
1.
MicroProfileHealthendpointsandannotations12.
2.
2.
Seealso:APPENDIXA.
ADDITIONALOPENLIBERTYRESOURCES2424252525252526262734343435363636373737383838384041OpenLiberty2020OpenLibertyRuntimeGuide2TableofContents3CHAPTER1.
WHATISOPENLIBERTYOpenLibertyisalightweightJavaruntimeforbuildingcloud-nativeapplicationsandmicroservices.
WithOpenLiberty,it'seasytoaddandremovemodularfeaturesfromthelatestversionsofJakartaEEandEclipseMicroProfile.
Thismodularstructuresimplifiesmicroservicedevelopment,enablingyoutorunJustenoughApplicationServertosupportthefeaturesthatyourapplicationneeds.
Furthermore,withOpenLibertyzeromigrationarchitecture,youcanupgradetothelatestversionwithminimalimpacttoyourcurrentapplicationsandconfigurations.
OpenLibertyiscompatiblewiththeJakartaEE8FullPlatformandWebProfilespecificationsandwithMicroProfile3.
0.
Formoreinformation,seetheOpenLibertywebsite.
ForthelatestupdatesaboutOpenLibertyfeaturesandcapabilities,seetheOpenLibertyblogandOpenLibertydocs.
OpenLibertyisoneoftheJavaruntimesavailableonOpenShift,andsupportisprovidedaspartofaRedHatsubscription.
RunOpenLibertyonOpenShifttobuildanddeploycloud-nativeapplicationswiththebenefitsoftheOpenShiftplatform.
FormoreinformationaboutusingOpenLibertywithOpenShift,seeDeployingmicroservicestoOpenShift.
1.
1.
OPENLIBERTYVERSIONINGTraditionalversioningfollowssomevariationofthemajor.
minor.
microscheme,wheresignificantnewfunctionisonlydeliveredinamajorrelease.
Thesemajorreleasescontainkeynewcapabilities,buttheyalsomakebehaviorchangesthatrequireapplicationmigrationandsignificantregressiontestingtoadopt.
Asaresult,multiplemajorversionsaresupportedatanyonetime.
ThemodularfeaturearchitectureofOpenLiberty,incombinationwithzeromigration,allowsthedeliveryofnewfunctionincrementally,withoutfollowingamajor.
minor.
microversioningscheme.
Insteadofmajorreleases,eachOpenLibertyreleaseisconsideredamicro,orpatchrelease.
Thesepatchreleasesfollowayy.
0.
0.
nnversionscheme.
Thefirsttwodigitsindicatetheyearofreleaseandthelasttwodigitsindicatethenumberofthereleasewithinthatyear.
Eventhoughthefirstsetofdigitschangeseachyear,thereleasesareofequalstanding.
Forexample,thedifferencebetween20.
0.
0.
1(thefirstreleaseof2020)and19.
0.
0.
12(thelastreleaseof2019)isidenticaltothedifferencebetween19.
0.
0.
10and19.
0.
0.
11.
Thelackofmajorreleasestreamsisunusualforserverruntimes,butiscommonfordesktopandmobileapplications.
Somepublicationsystemsexpectsoftwaretohaveamajorversion.
Asaresult,incaseswhereamajorversionisneeded,theyearofpublicationisusedasastand-in.
Forexample,OpenLibertydocumentationthatispublishedforthisguidein2019usestheyear2019astheversionnumber.
However,thisdocumentationisasapplicabletoreleasesin2020asitistoreleasesin2019.
OpenLiberty2020OpenLibertyRuntimeGuide4CHAPTER2.
ZERO-MIGRATIONARCHITECTUREZero-migrationarchitectureisacoredesignprincipleofOpenLiberty,whichsupportsfullcompatibilitybetweenruntimeversions.
Withzero-migrationarchitecture,youcanmovetothelatestversionofOpenLibertywithminimalimpacttoyourcurrentapplicationsandconfigurations.
Oneofthemajorchallengesforteamsthatworkwithruntimeserversistheneedtocontinuallyupdatetothelatestreleaseoftheruntime.
Theseupdatesareoftenrequiredtoresolvesecurityvulnerabilitiesorbugsthatcancauseoutages.
UpdatingtheruntimeversioncanbedifficultbecausenewreleasesalsointroduceAPIorbehaviorchanges,sometimesforfunctionsthatarenotcriticalforyourparticularapplications.
BoththeOpenLibertyruntimeandOpenLibertyfeaturesarereleasedinnumberedversions.
ChangesinbehaviorandAPIsupportaredeliveredinnewfeatureversions,whichyoucandecidewhethertoadoptaccordingtoyourneeds.
Withzeromigration,yourexistingAPIsandbehaviorsaresupportedinnewruntimeversions,andnewAPIsandbehaviorsareaddedinnewfeaturesandfeatureversions.
Yourexisting,unmodifiedconfigurationandapplicationfilesworkwithanupdatedversionofOpenLiberty,withoutunexpectedchangesinapplicationbehavior.
2.
1.
USERCONFIGURATIONFILESIfalltheconfiguredfeaturesareinstalled,asinglesetofconfigurationfilesworksacrossmultipleversionsofOpenLibertywithoutmodifications.
Userconfigurationfilesdonotrequiremodificationwhentheruntimeisupdatedtoanewversion.
OpenLibertyignoresanyconfigurationsettingsthatdonotapplytotheactiveversionoftheruntime.
2.
2.
OPENLIBERTYFEATURESOpenLibertyfeaturesareencodedintotheserverconfiguration,whichdoesnotchangeduringanupgrade.
Whenbehaviorchangesareintroduced,suchaswhenaJavaspecificationmandatesabehaviorchange,thechangeisintroducedinanewversionofthefeature.
Existingapplicationsandtheirconfigurationcancontinuetousetheoldbehaviorwiththeolderfeatureversion,whilenewapplicationscanusenewerfeatureversionswiththenewbehavior.
Forexample,OpenLibertysupportsboththeServlet3.
1andServlet4.
0specifications.
TheServlet4.
0specificationincludesclarificationstopreviousservletversionsthatcanresultinchangesinapplicationbehavior.
OpenLibertyrestrictsanysuchbehaviorchangestotheservlet-4.
0featureandretainstheexistingbehaviorintheservlet-3.
1feature.
IfyourapplicationisconfiguredfortheServlet3.
1specification,youcancontinuetousetheservlet-3.
1featureacrossruntimeupdates,regardlessofhowmanyotherservletspecificationlevelsaresupported.
Youdon'tneedtochangeyourapplicationunlessyoudecidetoconfiguretheservlet-4.
0featureinstead.
Formoreinformation,seeFeatureoverview.
2.
2.
1.
ConsiderationsforusingnewfeaturesUpgradingtoanewversionofafeaturethatyouarealreadyusingmightimpactyourexistingapplications.
Forexample,ifyoucurrentlyusetheservlet-3.
1featureandyouwanttousetheservlet-4.
0feature,yourexistingservletapplicationsmightrequiremodificationtoworkcorrectlywiththeservlet4.
0feature.
Alternatively,youcankeeptheapplicationinaserverthatisconfiguredwiththeoriginalversionandcreateadifferentserverconfigurationwiththenewfeatureversionfornewapplications.
Somefeaturesinteractcloselywithotherfeaturesandrequirethatyouenableaparticularfeatureversionwhentheyarebothconfiguredinthesameserver.
Somefeaturesrequirespecificversionsofprerequisitesoftware,forexample,theJavaSDK.
2.
3.
EXCEPTIONSTOZEROMIGRATIONCHAPTER2.
ZERO-MIGRATIONARCHITECTURE5AlthoughOpenLibertyisdesignedtoensurethatnobreakingchangesoccurbetweenruntimeversions,insomerarecasestheyareunavoidable.
Suchexceptionstozeromigrationfallintooneofthefollowingcategories:SecurityfixesIfyourapplicationrequiresasecurity-relatedfixthatcannotbesafelyimplementedinthecontextofexistingbehavior,thenyoumightneedtomodifyyourapplicationorconfiguration.
Third-partyAPIrequirementsOpenLibertydoesnotcontrolAPIsfromthethird-partyclassloaderconfiguration.
Asaresult,updatestothird-partycomponentsarenotguaranteedtobecompatiblewithanearlierversionoftheruntime.
UndocumentedconfigurationpropertiesSomeconfigurationoptionsforOpenLibertyarenotpartoftheruntimedocumentation.
Theseconfigurationoptionscanbedeterminedbylookingatthesourcecode,orthroughtrialanderror,basedonexternalsourcesofinformation.
IfoptionsarenotdocumentedasapartofOpenLiberty,thentheyarenotconsideredpartofOpenLiberty.
Suchoptionsmightnotbefullyimplementedandmightcauseissuesiftheyareused.
Sincetheyarenotdocumented,theycanberemovedorchangedatanytimeandarenotcoveredbyzeromigration.
IncompatibleJavachangesHistorically,newJavaSEversionsmakefewincompatiblechangestotheJavalanguage.
IntherarecasethatabreakingchangeisincludedinanewJavaversion,OpenLibertyattemptstominimizetheimpactofthesechangesonapplications.
However,theseattemptsmightnotalwaysbesuccessfulandbreakingJavachangescansometimesadverselyaffectyourapplication.
Zero-migrationarchitecturesavesdevelopersandenterprisestimeandmoneybyavoidingtheneedtomigrateexistingconfigurationandapplicationfiles.
Developerscanfocusontheirapplications,ratherthanmanagingruntimeupdates,whiletheycontinuetobenefitfromimprovedperformanceandadministrationfortheirexistingserverconfigurations.
OpenLiberty2020OpenLibertyRuntimeGuide6CHAPTER3.
DEPLOYMENTONOPENSHIFTOpenShiftisaKubernetes-basedcontainerapplicationplatformthatyoucanusetobuild,containerize,anddeployyourapplicationssothatthey'rehighlyavailableandscalable.
YoucanalsousetheOpenLibertyOperatortosimplifydeployingandmanagingyourapplicationsinthecloud.
Afteryoudevelopandcontainerizeyourapplications,yourcontainersneedtocommunicatewithothercontainersthatarerunningdatabases,securitysystems,orothermicroservices.
Containersalsoneedtoscaleasservicesareneeded.
OpenShiftprovidesfeaturesthatautomateandmanagecontainerstomeettheneedsofdevelopersandoperationsteams.
3.
1.
RUNNINGAPPLICATIONSONOPENSHIFTOneofthebenefitsofrunningyourapplicationsonOpenShiftisthatyoucandeploythemtoacloud-hostedInfrastructureasaService(IaaS)solution,ortoyourcurrenton-premisesstructure.
YoucanusetheOpenShiftCLIorOpenShiftDoCLItodevelopyourapplications.
Then,containerizeapplicationsinOpenLibertycontainersanddeploythemtoanOpenShiftcluster.
Forastep-by-steptutorialondeployingmicroservicestoOpenShift,seetheDeployingmicroservicestoOpenShiftguide.
TolearnmoreabouthowyourapplicationsonOpenLibertycanbeusedwiththedifferentOpenShiftdeploymentoptions,seetheOpenShiftdocumentation.
3.
2.
OPENLIBERTYOPERATOROperatorsareextensionstoKubernetesthatarecustomizedtoautomatetasksbeyondtheinitialautomationthatKubernetesorOpenShiftprovide.
TheOpenLibertyOperatorhasacapabilityleveloffive,whichmeansthatithasthehighestlevelofenterprisecapabilities,includingauto-scaling,servicebinding,OpenShiftcertificatemanagementintegration,andKubernetesApplicationNavigator(kAppNav)integration.
WiththeOpenLibertyOperator,youcanmakeapplicationshighlyavailablebyconfiguringhorizontalauto-scaling,whichcreatesordeletesapplicationinstancesbasedonresourceavailabilityandconsumption.
TheOperatoralsohelpsmanageapplicationdeployments.
Forexample,afteryouuploadanewcontainertagforanewversionofanapplication,updatetheapplicationImagefieldintheOperatordeploymentfilewiththenewcontainertag.
Then,theOperatorupdatestheapplicationonarollingbasis.
ThisOperatoralsooffersotherproduction-gradecapabilities,includingsimpleconfigurationofpersistentoradvancedstorageandtheabilitytodelegatesingle-signon(SSO)toexternalproviders.
TheOperatorautomatesupdatesofbindinginformationamongapplications,meaningthatitconnectsapplicationsandmaintainsinformationaboutwhetheraparticularapplicationproducesorconsumesaservice.
YoucaninstalltheOpenLibertyOperatorfromOperatorHubforuseonKubernetesorOpenShift.
TheOperatorisalsoavailableasaRedHat-certifiedOperatorfromOpenShiftContainerPlatform(OCP).
3.
3.
SEEALSOGuide:DeployingmicroservicestoKubernetesCHAPTER3.
DEPLOYMENTONOPENSHIFT7CHAPTER4.
FEATUREOVERVIEWFeaturesarethediscreteunitsoffunctionalitybywhichyoucontrolthepiecesoftheruntimeenvironmentthatareloadedintoaparticularserver.
Byaddingorremovingfeaturesfromyourserverconfiguration,youcancontrolwhatfunctionstheservercanperform.
Featuresprovidetheprogrammingmodelsandservicesthatapplicationsrequire.
Youcanspecifyanyfeatureintheserverconfigurationfiles.
Somefeaturesincludeotherfeatureswithinthem,andthesamefeaturemightbeincludedinoneormoreotherfeatures.
Whentheserverisstarted,theJVMislaunchedandcontrolispassedtotheOpenLibertykernel.
TheconfigurationisloadedasdescribedintheServerconfigurationoverview.
Whentheconfigurationisparsed,thefeaturemanagergainscontrolandprocessesthefeatureManagerconfigurationtoloadtherequestedfeaturesintotheserverandstarttherequiredcomponents.
Finally,theapplicationsarestarted.
Whentheconfigurationischanged,thefeaturemanagerreevaluatesthecodethatisrequiredforthenewlyrequestedfeaturesbystartingandstoppingpartsoftheruntimeasnecessarywithoutrestartingtheserver.
Changestoapplicationsareprocessedinasimilarway.
4.
1.
USINGFEATURESFeaturesarespecifiedinthesystemconfigurationfilesthataretheserver.
xmlfileandanyotherincludedfiles.
ThefeaturemanagerisconfiguredbyusingthefeatureManagerelementintheserver.
xmlfile.
Eachfeaturethatisrequiredisconfiguredbyusingthefeatureelement.
Thefollowingexampleconfigurestheservlet-4.
0andjdbc-4.
3features:Theruntimecontainsdefaultconfigurationsettingssothattheconfigurationyouneedtospecifyiskepttoaminimum.
Youspecifythefeaturesthatyouneed,alongwithanyadditionsoroverridestothedefaultsettings,intheserver.
xmlfile.
Fordetailsabouttheserverconfiguration,seetheServerconfigurationoverview.
4.
2.
ZERO-MIGRATIONWiththeOpenLibertyzero-migrationarchitecture,youcanmovetothelatestversionofOpenLibertywithminimalimpacttoyourcurrentapplicationsandconfigurations.
Zero-migrationarchitecturemeansthatyoucanuseexisting,unmodifiedconfigurationandapplicationfileswithanupdatedversionoftheOpenLibertyruntimeenvironmentwithoutunwantedorunexpectedchangeinbehavior.
WiththeuseofpluggablefeaturesintheOpenLibertyruntimeenvironment,yourexistingAPIsandbehaviorsaresupportedinnewproductversions,andnewAPIsandbehaviorsareaddedinnewfeatures.
Forexample,boththeServlet3.
1and4.
0specificationsaresupported.
ChangesinAPIbehavioronlyhappeninnewfeatureversions,soyoucanchoosetheappropriatefeatureversionforyourapplication.
TheseversionedfeaturescontinuetobesupportedacrossOpenLibertyupdates.
Ifyoucontinuetousethesamefeatureversion,youneverneedtomigrateyourapplication.
Forexample,ifyourapplicationusesServlet3.
1,theOpenLibertyserverthatrunstheapplicationmusthavetheservlet-3.
1feature.
YoucanupdateOpenLibertyandcontinuetousetheservlet-3.
1featureindefinitely,regardlessofhowmanyotherServletspecificationlevelsaresupported.
Youneedtomigrateyourapplicationsonlyifyouchoosetousetheservlet-4.
0featureinstead.
servlet-4.
0jdbc-4.
3OpenLiberty2020OpenLibertyRuntimeGuide84.
3.
COMBININGFEATURESIfyoutrytoconfigureaservertohavedifferentversionsofafeature,anerrorisreportedbecauseOpenLibertydoesn'tsupportcombiningdifferentversionsofthesamefeature.
ThismeansthatmostOpenLibertyfeaturesaresingletonfeatures.
Asingletonfeatureisafeatureforwhichyoucanconfigureonlyoneversionforuseinaserver.
Ifyouhaveapplicationsthatneeddifferentversionsofthesingletonfeature,youmustdeploythemindifferentservers.
Ifyourserverconfigurationincludesmultipleversionsofasingletonfeature,eitherthroughdirectconfigurationintheserver.
xmlfile,orthroughfeaturedependencies,thatconfigurationisinerrorandneitherversionofthatfeatureisloaded.
Toresolvethisproblem,ensurethattheconfiguredfeaturesallspecify,ortolerate,thesameversionofthatsingletonfeature.
Ifyouhavehardrequirementsonbothfeatureversions,youmustmovesomeofyourapplicationstoadifferentserver.
Libertydoesn'tsupportcombiningfeaturesfrombothJavaEE7andJavaEE8,exceptwhentheJavaEE7andJavaEE8specificationsshareacomponentspecificationversion.
IfyoucombineJavaEE7andJavaEE8featuresinaserverconfiguration,theserverreportserrorsatstartup.
ThefollowingfeaturesareincludedinbothJavaEE7andJavaEE8:appClientSupport-1.
0batch-1.
0concurrent-1.
0ejb-3.
2j2eeManagement-1.
1jacc-1.
5jaxws-2.
2jca-1.
7jcaInboundSecurity-1.
0jdbc-4.
2jdbc-4.
3jms-2.
0wasJmsClient-2.
0wasJmsSecurity-1.
0wasJmsServer-1.
0ForacompletelistoffeaturesthatsupportJavaEE7,seethejavaee-7.
0feature.
ForacompletelistoffeaturesthatsupportJavaEE8,seethejavaee-8.
0feature.
4.
4.
SUPERSEDEDFEATURESIfafeatureissuperseded,anewfeatureoracombinationoffeaturesmightprovideanadvantageoverthesupersededfeature.
ThenewfeatureorfeaturesmightnotcompletelyreplacethefunctionoftheCHAPTER4.
FEATUREOVERVIEW9supersededfeature,soyoumustconsideryourscenariobeforeyoudecidewhethertochangeyourconfiguration.
Supersededfeaturesremainsupportedandvalidforuseinyourconfiguration,butyoumightbeabletoimproveyourconfigurationbyusingthenewerfeatures.
Occasionally,afeaturethatincludesotherfeaturesissupersededbyanewversionofthefeaturethatdoesnotincludeallthosefeatures.
Thefeaturesthatarenotincludedinthenewversionareconsideredtobeseparated.
Ifyourapplicationdependsonthefunctionsofaseparatedfeature,youmustexplicitlyaddtheseparatedfeaturetoyourconfiguration.
ThefollowingtableliststheOpenLibertyfeaturesthataresuperseded:SupersededfeatureSupersedingfeatureDependentfeatureremovedappSecurity-1.
0appSecurity-2.
0TheldapRegistryandtheservlet-3.
0featurewereremovedfromthedefinitionoftheappSecurity-2.
0feature.
jmsMdb-3.
2jms-2.
0andmdb-3.
2Together,thejms-2.
0andmdb-3.
2featuresprovidethesamefunctionasthejmsMdb-3.
2feature.
ssl-1.
0transportSecurity-1.
0Thessl-1.
0andtransportSecurity-1.
0featuresarefunctionallyequivalent.
However,ssl-1.
0impliesthataninsecurenetworkprotocolisused,sotransportSecurity-1.
0supersedesit.
OpenLiberty2020OpenLibertyRuntimeGuide10123CHAPTER5.
SERVERCONFIGURATIONOVERVIEWTheOpenLibertyserverconfigurationismadeupofonemandatoryfile,theserver.
xmlfile,andasetofoptionalfiles.
Theserver.
xmlfilemustbewell-formedXMLandtherootelementmustbeserver.
Whentheserver.
xmlfileisprocessed,anyelementsorattributesthatarenotunderstoodareignored.
Thisexampleserver.
xmlfileconfigurestheservertodothefollowingthings:SupporttheJavaServerPages2.
3featureListentoincomingtraffictolocalhostonport9080AutomaticallyexpandWARfileswhentheyaredeployedThetermserverconfigurationcanbeusedtorefertoallofthefilesthatmakeuptheserverconfigurationorspecificallytotheconfigurationthat'sintheXMLfiles.
Ifit'snotclearincontext,thetermserverXMLconfigurationmightbeusedtorefertotheconfigurationintheXMLfiles.
5.
1.
CONFIGURATIONFILESTheserverconfigurationfilesareprocessedinthefollowingorder:1.
server.
env-Environmentvariablesarespecifiedinthisfile.
2.
jvm.
options-JVMoptionsaresetinthisfile.
3.
bootstrap.
properties-ThisfileinfluencesthestartupoftheOpenLibertyserver.
4.
server.
xml-Thismandatoryfilespecifiestheserverconfigurationandfeatures.
5.
1.
1.
server.
envTheserver.
envfilesareoptional.
Thesefilesarereadbythebin/servershellscriptandspecifyenvironmentvariablesthatareprimarilyusedtoinfluencethebehaviorofthebin/serverscript.
server.
envfilesarereadfromthefollowinglocationsinorder:1.
${wlp.
install.
dir}/etc/2.
${wlp.
user.
dir}/shared/3.
${server.
config.
dir}/Ifthesamepropertyissetinmultiplelocations,thenthelastvaluefoundisused.
jsp-2.
313CHAPTER5.
SERVERCONFIGURATIONOVERVIEW11Themostcommonuseofthesefilesistosetthefollowingenvironmentvariables:JAVA_HOME-IndicateswhichJVMtouse.
Ifthisisnotset,thesystemdefaultisused.
WLP_USER_DIR-IndicatesthelocationoftheusrdirectorythatcontainstheserverconfigurationThiscanonlybesetintheetc/server.
envfilebecausetheotherlocationsarerelativetotheusrdirectory.
WLP_OUTPUT_DIR-Indicateswheretheserverwritesfilesto.
Bydefault,theserverwritestothedirectorystructurethattheconfigurationisreadfrom.
However,insomesecureprofilestheserverconfigurationneedstoberead-onlysotheservermustwritefilestoanotherlocation.
Theserver.
envfileisinKEY=valueformat,asshowninthefollowingexample:Keyvaluesmustnotcontainspaces.
Thevaluesareinterpretedliterallysoyoudon'tneedtoescapespecialcharacters,suchasspaces.
Thesefilesdon'tsupportvariablesubstitution.
5.
1.
2.
jvm.
optionsThejvm.
optionsfilesareoptional.
Thesefilesarereadbythebin/servershellscripttodeterminewhatoptionstousewhentheJVMislaunchedforOpenLiberty.
jvm.
optionsfilesarereadfromthefollowinglocationsinorder:1.
${wlp.
user.
dir}/shared/jvm.
options2.
${server.
config.
dir}/configDropins/defaults/3.
${server.
config.
dir}/4.
${server.
config.
dir}/configDropins/overrides/Ifnojvm.
optionsfilesexistintheselocations,thentheserverscriptlooksforthefilein${wlp.
install.
dir}/etc,ifsuchadirectoryexists.
Commonusesofjvm.
optionsfilesinclude:SettingJVMmemorylimitsEnablingJavaAgentsthatareprovidedbymonitoringproductsSettingJavaSystemPropertiesThejvm.
optionsfileformatusesonelineperJVMoption,asshowninthefollowingexample:Youdon'tneedtoescapespecialcharacters,suchasspaces.
OptionsarereadandprovidedtotheJVMinorder.
Ifyouprovidemultipleoptions,thentheyareallseenbytheJVM.
Thesefilesdonotsupportvariablesubstitution.
5.
1.
3.
bootstrap.
propertiesJAVA_HOME=/opt/ibm/javaWLP_USER_DIR=/opt/wlp-usr-Xmx512m-Dmy.
system.
prop=Thisisthevalue.
OpenLiberty2020OpenLibertyRuntimeGuide12Thebootstrap.
propertiesfileisoptional.
ThisfileisreadduringOpenLibertybootstraptoprovideconfigurationfortheearlieststagesoftheserverstartup.
Itisreadbytheserverearlierthantheserver.
xmlfilesoitcanaffectthestartupandbehavioroftheOpenLibertykernelfromthestart.
Thebootstrap.
propertiesfileisasimpleJavapropertiesfileandislocatedin${server.
config.
dir}.
Acommonuseofthebootstrap.
propertiesfileistoconfigureloggingbecauseitcanaffectloggingbehaviorbeforetheserver.
xmlfileisread.
Thebootstrap.
propertiesfilesupportsaspecialoptionalproperty,bootstrap.
include,whichspecifiesanotherpropertiesfiletoalsobereadduringthebootstrapstage.
Forexample,thisboostrap.
includefilecancontainacommonsetofbootstrappropertiesformultipleserverstouse.
Setthebootstrap.
includefiletoanabsoluteorrelativefilepath.
5.
1.
4.
server.
xmlThemostimportantandonlyrequiredconfigurationfileistheserver.
xmlfile.
Theserver.
xmlfilemustbewell-formedXMLandtherootelementmustbeserver.
Theexactelementsthataresupportedbyaserverdependonwhichfeaturesareconfigured,andanyunknownconfigurationisignored.
OpenLibertyusesaprincipleofconfigurationbyexception,whichallowsforsuccinctconfigurationfiles.
Theruntimeenvironmentoperatesfromasetofbuilt-inconfigurationdefaultsettings.
Youonlyspecifyconfigurationthatoverridesthosedefaultsettings.
Serverconfigurationfilesarereadfromthefollowinglocationsinorder:1.
${server.
config.
dir}/configDropins/defaults/2.
${server.
config.
dir}/server.
xml3.
${server.
config.
dir}/configDropins/overrides/The${server.
config.
dir}/server.
xmlfilemustbepresent,buttheotherfilesareoptional.
Youcanflexiblycomposeconfigurationbydroppingserver-formattedXMLfilesintodirectories.
FilesarereadinalphabeticalorderineachofthetwoconfigDropinsdirectories.
5.
2.
VARIABLESUBSTITUTIONYoucanusevariablestoparameterizetheserverconfiguration.
Toresolvevariablereferencestotheirvalues,thefollowingsourcesareconsultedinorder:1.
server.
xmlfiledefaultvariablevalues2.
environmentvariables3.
bootstrap.
properties4.
Javasystemproperties5.
server.
xmlfileconfiguration6.
variablesdeclaredonthecommandlineVariablesarereferencedbyusingthe${variableName}syntax.
Specifyvariablesintheserverconfigurationasshowninthefollowingexample:CHAPTER5.
SERVERCONFIGURATIONOVERVIEW13Defaultvalues,whicharespecifiedintheserver.
xmlfile,areusedonlyifnoothervalueisspecified:Youcanalsospecifyvariablesatstartupfromthecommandline.
Ifyoudo,thevariablesthatarespecifiedonthecommandlineoverrideallothersourcesofvariablesandcan'tbechangedaftertheserverstarts.
Environmentvariablescanbeaccessedasvariables.
Asofversion19.
0.
0.
3,youcanreferencetheenvironmentvariablenamedirectly.
Ifthevariablecannotberesolvedasspecified,theserver.
xmlfilelooksforthefollowingvariationsontheenvironmentvariablename:Replaceallnon-alphanumericcharacterswiththeunderscorecharacter(_)ChangeallcharacterstouppercaseForexample,ifyouenter${my.
env.
var}intheserver.
xmlfile,itlooksforenvironmentvariableswiththefollowingnames:1.
my.
env.
var2.
my_env_var3.
MY_ENV_VARForversions19.
0.
0.
3andearlier,youcanaccessenvironmentvariablesbyaddingenv.
tothestartoftheenvironmentvariablename,asshowninthefollowingexample:Variablevaluesarealwaysinterpretedasastringwithsimpletypeconversion.
Therefore,alistofports(suchas80,443)mightbeinterpretedasasinglestringratherthanastwoportnumbers.
Youcanforcethevariablesubstitutiontosplitonthe,byusingalistfunction,asshowninthefollowingexample:Simplearithmeticissupportedforvariableswithintegervalues.
Theleftandrightsidesoftheoperatorcanbeeitheravariableoranumber.
Theoperatorcanbeor/,asshowninthefollowingexample:Thereareanumberofpredefinedvariables:wlp.
install.
dir-thedirectorywheretheOpenLibertyruntimeisinstalled.
wlp.
server.
name-thenameoftheserver.
OpenLiberty2020OpenLibertyRuntimeGuide14wlp.
user.
dir-thedirectoryoftheusrfolder.
Thedefaultis${wlp.
install.
dir}/usr.
shared.
app.
dir-thedirectoryofsharedapplications.
Thedefaultis${wlp.
user.
dir}/shared/apps.
shared.
config.
dir-thedirectoryofsharedconfigurationfiles.
Thedefaultis${wlp.
user.
dir}/shared/config.
shared.
resource.
dir-thedirectoryofsharedresourcefiles.
Thedefaultis${wlp.
user.
dir}/shared/resources.
server.
config.
dir-thedirectorywheretheserverconfigurationisstored.
Thedefaultis${wlp.
user.
dir}/servers/${wlp.
server.
name}.
server.
output.
dir-thedirectorywheretheserverwritestheworkarea,logs,andotherruntime-generatedfiles.
Thedefaultis${server.
config.
dir}.
5.
3.
CONFIGURATIONMERGINGSincetheconfigurationcanconsistofmultiplefiles,itispossiblethattwofilesprovidethesameconfigurationInthesesituations,theserverconfigurationismergedaccordingtoasetofsimplerules.
InOpenLiberty,configurationisseparatedintosingletonandfactoryconfigurationeachofwhichhasitsownrulesformerging.
Singletonconfigurationisusedtoconfigureasingleelement(forexample,logging).
Factoryconfigurationisusedtoconfiguremultipleentities,suchasanentireapplicationordatasource.
5.
3.
1.
MergingsingletonconfigurationForsingletonconfigurationelementsthatarespecifiedmorethanonce,theconfigurationismerged.
Iftwoelementsexistwithdifferentattributes,bothattributesareused.
Forexample:istreatedas:Ifthesameattributeisspecifiedtwice,thenthelastinstancetakesprecedence.
Forexample:istreatedas:CHAPTER5.
SERVERCONFIGURATIONOVERVIEW15Configurationissometimesprovidedbyusingchildelementsthattaketext.
Inthesecases,theconfigurationismergedbyusingallofthevaluesspecified.
Themostcommonscenarioisconfiguringfeatures.
Forexample:istreatedas:5.
3.
2.
MergingfactoryconfigurationFactoryconfigurationmergesusethesamerulesassingletonconfigurationexceptelementsarenotautomaticallymergedjustbecausetheelementnamesmatch.
Withfactoryconfigurationitisvalidtoconfigurethesameelementandmeantwodifferentlogicalobjects.
Therefore,eachelementisassumedtoconfigureadistinctobject.
Ifasinglelogicalobjectisconfiguredbytwoelements,theidattributemustbesetoneachelementtoindicatetheyarethesamething.
Variablesubstitutiononanidattributeisnotsupported.
Thefollowingexampleconfigurestwoapplications.
Thefirstapplicationismyapp.
war,whichhasacontextrootofmyawesomeapp.
Theotherapplicationismyapp2.
war,whichhasmyapp2asthecontextroot:5.
4.
INCLUDEPROCESSINGInadditiontothedefaultlocations,additionalconfigurationfilescanbebroughtinbyusingtheincludeelement.
Whenaserverconfigurationfilecontainsanincludereferencetoanotherfile,theserverprocessesthecontentsofthereferencedfileasiftheywereincludedinlineinplaceoftheincludeelement.
Inthefollowingexample,theserverprocessesthecontentsoftheother.
xmlfilebeforeitprocessesthecontentsoftheother2.
xmlfile:servlet-4.
0restConnector-2.
0servlet-4.
0restConnector-2.
0OpenLiberty2020OpenLibertyRuntimeGuide16Bydefault,theincludefilemustexist.
Iftheincludefilemightnotbepresent,settheoptionalattributetotrue,asshowninthefollowingexample:Whenyouincludeafile,youcanspecifytheonConflictattributetochangethenormalmergerules.
YoucansetthevalueoftheonConflictattributetoIGNOREorREPLACEanyconflictingconfig:Youcansetthelocationattributetoarelativeorabsolutefilepath,ortoanHTTPURL.
5.
5.
CONFIGURATIONREFERENCESMostconfigurationinOpenLibertyisself-containedbutitisoftenusefultoshareconfigurationForexample,theJDBCdriverconfigurationmightbesharedbymultipledatasources.
Youcanrefertoanyfactoryconfigurationelementthatisdefinedasadirectchildoftheserverelement.
Areferencetoconfigurationalwaysusestheidattributeoftheelementthatisbeingreferenced.
TheconfigurationelementthatmakesthereferenceusesanattributethatalwaysendswithRef,asshowninthefollowingexample:5.
6.
DYNAMICUPDATESTheservermonitorstheserverXMLconfigurationforupdatesanddynamicallyreloadswhenchangesaredetected.
Changestonon-XMLfiles(server.
env,bootstrap.
properties,andjvm.
options)arenotdynamicbecausetheyareonlyreadatstartup.
AnyserverXMLconfigurationfileonthelocaldiskismonitoredforupdatesevery500ms.
YoucanconfigurethefrequencyofXMLconfigurationfilemonitoring.
Forexample,toconfiguretheservertomonitorevery10minutes,specify:TodisablefilesystempollingandreloadonlywhenanMBeanisnotified,specify:5.
7.
LOGMESSAGESWhentheserverruns,itmightoutputlogmessagesthatreferenceconfiguration.
ThereferencesintheCHAPTER5.
SERVERCONFIGURATIONOVERVIEW17Whentheserverruns,itmightoutputlogmessagesthatreferenceconfiguration.
ThereferencesintheloguseanXPath-likestructuretospecifyconfigurationelements.
Theelementnameisgivenwiththevalueoftheidattributeinsidesquarebrackets.
Ifnoidisspecifiedintheserverconfigurationanidisautomaticallygenerated.
BasedonthefollowingserverXMLconfigurationexample,thedataStoreelementandthechilddataSourceareidentifiedinthelogsasdataStore[myDS]anddataStore[myDS]/dataSource[default-0].
OpenLiberty2020OpenLibertyRuntimeGuide18CHAPTER6.
OPENLIBERTYOPERATOROperatorsareextensionstoKubernetesthatarecustomizedtoautomatetasksbeyondtheinitialautomationthatKubernetesorOpenShiftprovides.
TheOpenLibertyOperatorhelpsyoudeployandmanageapplicationsonKubernetes-basedclusters.
6.
1.
WHATISTHEOPENLIBERTYOPERATORWhenyoudeployanapplicationwiththeOpenLibertyOperator,theoperatorwatchesOpenLibertyresourcesandcomparesthecurrentstateofresourcestothestateofresourcesthatyouconfigured.
Whenadiscrepancyexistsbetweenthecurrentstateofresourcesandthestatethatyouconfigured,theoperatorcreates,updates,ordeletesKubernetesresourcestoreturntothestatethatyouconfigured.
TheseKubernetesresourcesmightincludedeployments,services,orroutes.
Withouttheoperator,youmustmanuallycreatedeployments,services,routes,andotherKubernetesresources,whichcaninvolveatime-consuminglearningcurve.
Withtheoperator,youcanspecifydetailsforyourapplication,includingyourapplicationimage,serviceport,andwhethertoexposetheapplicationoutsidethecluster.
Then,theoperatorcreatesandmanagesallKubernetesresources.
Now,youmanageonlyasingleOpenLibertyApplicationresourceinsteadofmanyresources.
Inaddition,theoperatorcontinuouslymonitorstheeventsthatarerelatedtotheapplicationintheclusterandtakesnecessaryactionstosynchronizedataandresources.
BecausetheoperatorhelpsyoumanageKubernetesresources,youcanfocusonyourapplicationwhiletheoperatorhandlesmanyoftheclouddeploymentdetails.
TheOpenLibertyOperatorisbasedontheRuntimeComponentOperator,whichisagenericoperatorthatcanbeimportedintoruntime-specificoperatorstoprovidestandardizedenterprisecapabilities.
Assuch,commonfunctionalityexistsbetweenthesetwooperators,suchastheuseofimagestreamsandtheabilitytorunmultipleinstancesofyourapplicationforhighavailability.
WhenyouusetheOpenLibertyOperator,theoperatorcontainerandcontrolleraredeployedtoaKubernetespod,andtheoperatorlistensforincomingresourceswiththekind:OpenLibertyApplicationstatement.
WhenyoucreateanOpenLibertyApplicationcustomresource(CR),theoperatormanagestheKubernetesresourcesthattheapplicationneedstorunonyourcluster.
6.
2.
OPERATORCAPABILITIESTheOpenLibertyOperatorhasacapabilityleveloffive,whichmeansthatithasthehighestlevelofenterprisecapabilities,includingthefollowingcapabilities:Highavailabilitythat'sprovidedbyhorizontalauto-scalingYoucanconfigurehorizontalauto-scalingtocreateanddeleteinstancesofyourapplicationbasedonresourceconsumption.
Thisabilitytorunmultipleinstancesofyourapplicationandauto-scalethemmeansthatyourapplicationismadehighlyavailable.
EnhanceddeploymentmanagementWiththeOpenLibertyOperator,youcanmoreeasilymanageapplicationsthataredeployedtoKubernetes.
Forexample,intheoperatordeploymentfile,youcanspecifyanimagestreamintheapplicationImagefield.
Then,afteryouuploadanewcontainertagforanewversionofanapplication,theoperatorupdatestheapplicationonarollingbasis.
AutomatedservicebindingTheoperatorautomatesupdatesofbindinginformationamongapplications,meaningthatitconnectsapplicationsandmaintainsinformationaboutwhetheraparticularapplicationproducesorconsumesaservice.
Withthisinformation,theoperatorautomaticallyhandlesKubernetes-leveldetails,includingcreatingandinjectingKubernetesSecrets,sothatyourapplicationscanconnecttorequiredserviceswithoutinterruption.
CHAPTER6.
OPENLIBERTYOPERATOR19Singlesign-on(SSO)delegationWithOpenLiberty,youcandelegateSSOauthenticationtoexternalproviders.
TheOpenLibertyOperatorenableseasierconfigurationandmanagementofSSOinformationforyourapplications.
OpenShiftServerless(Knative)integrationYoucanintegratetheoperatorwithKnative.
WhentheoperatorisintegratedwithKnative,youdeployyourserverlessruntimecomponentbyusingasingletoggle.
TheoperatorconvertsallofitsgeneratedresourcesintoKnativeresources,whichallowsyourpodtoautomaticallyscaletozerowhenit'sidle.
KubernetesApplicationNavigator(kAppNav)integrationTheoperatorcanautomaticallyconfigureintegrationwithkAppNav.
Withthisintegration,youcanmonitorresourcesofyourapplicationandreceivealertswhenthehealthstatusofacomponentchanges.
Fromanintegratedpane,youcanalsoaccessoperations-focusedcapabilities,suchasenablingtraceforacomponentandviewingKibanaorGrafanadashboards.
OpenShiftcertificatemanagementintegrationTheoperatortakesadvantageofthecert-managertool,ifit'sinstalledontheKubernetescluster.
Thecert-managertoolallowstheoperatortoautomaticallyprovisionTransportLayerSecurity(TLS)certificatesforpodsandroutes.
CertificatesaremountedintocontainersfromaKubernetesSecretsothatthecertificatesareautomaticallyrefreshedwhenthey'reupdated.
6.
3.
SERVICEABILITYANDOBSERVABILITYWITHTHEOPENLIBERTYOPERATORYoucanenablepersistenceforyourapplicationbyspecifyingonlythesizeofstorageandwhereyouwantthestoragetobemounted.
Then,theoperatorcreatesandmanagesthestorageclaimforyou.
Anadvancedmodeisavailablethatallowstheconfigurationofextradetailsofthepersistentvolumeclaim.
Youcanalsoconfigureanduseasinglestorageforserviceability-relatedoperations,suchasgatheringservermemorydumpsandservertraces.
Formoreinformationaboutgatheringservermemorydumpsandservertraces,seeDay-2operations.
Afteryouconfiguretheoperator,youcanintegrateOpenLibertywithloggingandmonitoringtoolsforobservabilityintheKubernetescluster.
YoucanselectdifferenttypesofOpenLibertydatathatyouwanttomonitor.
Tovisualizeandtrackloggingevents,deployoneoftheprovidedOpenLibertyKibanadashboards.
YoucanmonitorOpenLibertymetricsbyusingMicroProfileMetrics,Prometheus,andGrafanatogather,scrape,andvisualizemetricdata.
YoucanalsoenableMicroProfileHealthtoperformlivenesschecksandreadinesscheckssothatKubernetescancheckthehealthofyourcontainers.
6.
4.
OPERATORINSTALLATIONANDCONFIGURATIONYoucaninstalltheOpenLibertyOperatorfromOperatorHubforuseonKubernetesorOpenShift.
TheoperatorisalsoavailableasaRedHat-certifiedoperatorfromOpenShiftContainerPlatform(OCP).
TheOpenLibertyOperatordocumentationprovidesdetailsaboutconfiguringtheoperator,includingbasicconfiguration,CustomResourceDefinition(CRD)parameters,OpenLibertyconsoleloggingenvironmentvariables,andpersistentstoragespecifications.
6.
5.
SEEALSOGuide:DeployinganapplicationtoOpenShiftbyusingKubernetesOperatorsTroubleshootingtheOpenLibertyOperatorOpenLiberty2020OpenLibertyRuntimeGuide20CHAPTER7.
DEVELOPMENTMODEWhenyourunOpenLibertyindevelopmentmode,youcanrapidlycode,deploy,test,anddebugapplicationsdirectlyfromyourintegrateddevelopmentenvironment(IDE)ortexteditor.
Youcanenabledevelopmentmode,knownasdevmode,toworkwitheitherMavenorGradlebuildautomationtools.
Withdevmode,youcanquicklyiterateonchangestoyourcodeandgetimmediatefeedbackfromon-demandorautomaticunitandintegrationtests.
Youcanalsoattachadebuggertostepthroughyourcodeatanytime.
DevmodeisavailableasagoaloftheOpenLibertyMavenplug-inorasataskoftheLibertyGradleplug-in.
ItintegratesasetofcapabilitiesforOpenLibertysothatyoucaneditandmonitoryourapplicationinrealtime,withoutrestartingyourrunningserver.
Devmodeaddressesthreeprimaryfocusareas:deployingchanges,runningtests,anddebugging.
7.
1.
RUNOPENLIBERTYINDEVMODETorunOpenLibertyindevmode,enabletheOpenLibertyMavenplug-inortheOpenLibertyGradleplug-inandrunoneofthefollowingcommands:Maven:mvnliberty:devGradle:gradlelibertyDev7.
1.
1.
Detect,recompile,anddeploycodechangesDevmodecanautomaticallydetect,recompile,anddeploycodechangeswheneveryousaveanewchangeinyourIDEortexteditor.
Devmodeautomaticallydetectsthefollowingchangestoyourapplicationsource:JavasourcefileandtestfilechangesResourcefilechangesConfigurationdirectoryandconfigurationfilechangesNewdependencyadditionstoyourpom.
xmlfileforMavenusersorbuild.
gradlefileforGradleusersNewfeatureadditionsintheOpenLibertyserverconfigurationResourcefile,configurationfile,andconfigurationdirectorychangesarecopiedintoyourtargetdirectory.
Newdependenciesinyourpom.
xmlfileorbuild.
gradlefileareaddedtoyourclasspath.
Newfeaturesareinstalledandstarted.
Somechanges,suchasaddingcertainconfigurationdirectoriesorfiles,donottakeeffectuntilyourestartdevmode.
Toenablethesechanges,restartdevmodewhenprompted.
Torestart,firstexitdevmodebypressingCTRL+C,orbytypingqandpressingEnter.
Then,runthemvnliberty:devcommandorthegradlelibertyDevcommandtorestart.
Aftertheserverrestarts,thechangesaredetected,recompiled,andpickedupbytherunningserver.
Youcanconfigurehowdevmodehandleschangestoyourcodebyspecifyingparameterswhenyoustartdevmode.
Formoreinformationaboutconfigurationparameters,seethedevgoaloftheOpenLibertyMavenplug-inorthelibertyDevtaskoftheOpenLibertyGradleplug-in.
7.
1.
2.
RununitandintegrationtestsondemandCHAPTER7.
DEVELOPMENTMODE21YoucanrununitandintegrationtestsondemandbypressingEnterinthecommandwindowwheredevmodeisrunning.
Devmoderunstheunittestsandintegrationteststhatareconfiguredforyourproject.
Ifyouaddatesttoyourproject,devmodecompilesandincludesitthenexttimethatyouruntests.
Youcangetimmediatefeedbackonyourchangesbyconfiguringdevmodetorunhottests.
Hottestsareunitorintegrationteststhatrunautomaticallywheneveryoustartdevmodeormakeacodechange.
Toconfigurehottesting,specifythehottestparameterwhenyoustartdevmode,asshowninthefollowingexamples:Maven:mvnliberty:dev-DhotTestsGradle:gradlelibertyDev--hotTestsYoucanalsoaddparameterstospecifywhethertoskiptests.
ForMaven,youcanaddparameterstoskipunittests,skipintegrationtests,orskipalltests.
ForGradle,youcanaddaparametertoskipalltests.
Formoreinformationaboutconfigurationparameters,seethedevgoaloftheOpenLibertyMavenplug-inorthelibertyDevtaskoftheOpenLibertyGradleplug-in.
7.
1.
3.
AttachadebuggertotherunningserverYoucanattachadebuggertotherunningservertostepthroughyourcodeatanytime.
Youcanspecifybreakpointsinyoursourcecodetolocallydebugdifferentpartsofyourapplication.
Thedefaultportfordebuggingis7777.
Ifthedefaultportisnotavailable,devmodeselectsarandomporttouseastheportfordebugging.
7.
1.
4.
VSCodeextensionfordevmodeWiththeOpenLibertyToolsVSCodeextension,youcanstartdevmode,makedynamiccodechanges,runtests,anddebugyourapplication,allwithoutleavingtheVSCodeeditor.
AfteryouinstalltheextensionandenableeithertheMavenorGradleplug-in,youcanselectyourprojectundertheLibertyDevDashboardintheVSCodesidebar.
Youcanaccessdevmodefunctionsbyright-clickingyourprojectnameandselectingacommandfromthemenu.
7.
2.
SEEALSOThedemo-devmodesampleproject(MavenandGradleusers)Guide:GettingstartedwithOpenLiberty(Mavenusers)OpenLiberty2020OpenLibertyRuntimeGuide22CHAPTER8.
THREADPOOLTUNINGOpenLibertyprovidesaself-tuningalgorithmthatcontrolsthesizeofitsthreadpool.
Althoughyoudonotneedtomanuallytunethethreadpoolformostapplications,insomecasesyoumightneedtoadjustthecoreThreadsandmaxThreadsattributes.
AlltheapplicationcodeinOpenLibertyrunsinasinglethreadpoolthatiscalledthedefaultexecutor.
Thesizeofthispoolissetbyaself-tuningcontroller,whichcanmanageawiderangeofworkloads.
Thedefaultexecutorpoolisthesetofthreadswhereyourapplicationcoderuns.
OpenLibertyusesotherthreadsfortaskslikeservingtheOSGiframework,collectingJVMgarbage,andprovidingJavaNIOtransportfunctions.
However,thesethreadsarenotdirectlyrelevanttoapplicationperformanceandmostofthemarenotconfigurable.
8.
1.
THREADPOOLTUNINGBEHAVIORTheOpenLibertythreadpoolself-tuningprocessrunsevery1.
5seconds.
Thethreadpoolcontrollermaintainsasetofdataaboutthethreadpoolperformancefromthetimetheserverstarted.
Thethroughputisdeterminedbythenumberoftasksthatarecompletedbythecontrollereachcycle.
Thecontrollerrecordsthethroughputforthevariouspoolsizesthatwerepreviouslytried.
Thishistoricalthroughputdataisthencomparedtothroughputforthecurrentcycletodecidetheoptimalpoolsize.
Ateachcycle,thepoolsizecanbeincrementallyincreasedordecreased,orleftunchanged.
Insomecases,nohistoricaldataisavailabletoguidethedecision.
Forexample,ifthepoolisgrowingwitheachcycleandthecurrentcycleisatthelargestsizesofar,nodataexistsaboutthroughputforlargerpoolsize.
Insuchacase,thecontrollerdecidesatrandomwhethertoincreasethesizeofthepool.
Then,itreadjustsforthenextcyclebasedontheresultsofthatdecision.
Thisprocessisanalogoustoahumanthreadpooltunerwhotriesvariousthreadpoolsizestoseehowtheyperformanddecidesonanoptimalvaluefortheconfigurationandworkload.
Duringeach1.
5-secondcycle,thethreadpoolcontrollerrunsthroughthefollowingself-tuningoperations:1.
Wakesupandcheckswhetherthethreadsinthepoolarehung.
Iftasksareinthequeueandnotaskswerecompletedinthepreviouscycle,thecontrollerconsidersthethreadstobehung.
Inthiscase,thecontrollerincreasesthethreadpoolsizeasspecifiedbysettingsandskipstostep5.
2.
Updatesthehistoricaldatasetwiththenumberoftasksthatcompletedinthemostrecentcontrollercycle.
Performanceisrecordedasaweightedmovingaverageforeachpoolsize.
Thisperformancereflectshistoricalresultsbutadjustsquicklytochangingworkloadcharacteristics.
3.
Useshistoricaldatatopredictwhetherperformancewouldbebetteratsmallerorlargerpoolsize.
Ifnohistoricaldataexistsforthesmallerorlargerpoolsize,thethreadpoolcontrollerdecideswhethertoincreaseorshrinkthesizeofthepool.
4.
Increasesordecreasesthepoolsizewithintheboundsthatarespecifiedinsettings,orleavesitunchanged,basedonpredictedperformance.
5.
Goesbacktosleep.
VariousfactorsotherthanthethreadpoolsizecanaffectthroughputintheOpenLibertyserver.
Therelationshipbetweenpoolsizeandobservedthroughputisnotperfectlysmoothorcontinuous.
Therefore,toimprovethepredictionsthatarederivedfromthehistoricalthroughputdata,thecontrollerconsidersnotjusttheclosestlargerandsmallerpoolsize,butalsoseveralincrementsineachdirection.
CHAPTER8.
THREADPOOLTUNING238.
1.
1.
HangresolutionInsomeapplicationscenarios,allthethreadsinthepoolcanbecomeblockedbytasksthatmustwaitforotherworktofinishbeforetheycanrun.
Inthesecases,theservercanbecomehungatacertainpoolsize.
Toresolvethissituation,thethreadpoolcontrollerentersahangresolutionmode.
Hangresolutionaddsthreadstothepooltoallowtheservertoresumenormaloperation.
Hangresolutionalsoshortensthecontrollercycledurationtobreakthedeadlockquickly.
Whenthecontrollerobservesthattasksarebeingcompletedagain,normaloperationresumes.
Thecontrollercyclereturnstoitsnormalduration,andpoolsizeisadjustedbasedontheusualthroughputcriteria.
8.
2.
MANUALTHREADPOOLTUNINGInmostenvironments,configurations,andworkloads,theOpenLibertythreadpooldoesnotrequiremanualconfigurationortuning.
Thethreadpoolself-tunestodeterminehowmanythreadsareneededtoprovideoptimalserverthroughput.
ThethreadpoolcontrollercontinuallyadjuststhenumberofthreadsinthepoolwithinthedefinedboundsforthecoreThreadsandmaxThreadsattributes.
However,insomesituations,settingthecoreThreadsormaxThreadsattributesmightbenecessary.
Thefollowingsectionsdescribetheseattributesandprovideexamplesofconditionsunderwhichtheymightneedtobemanuallytuned.
coreThreadsThisattributespecifiestheminimumnumberofthreadsinthepool.
Theminimumvalueforthisattributeis4.
OpenLibertycreatesanewthreadforeachpieceofofferedworkuntilthenumberofthreadsequalsthevalueofthisattribute.
IfthecoreThreadsattributeisnotconfigured,itdefaultstoamultipleofthenumberofhardwarethreadsavailabletotheOpenLibertyprocess.
IfOpenLibertyisrunninginasharedenvironment,thethreadpoolcontrollercannotaccountforotherprocesseswithwhichitissharingtheavailableCPUs.
Inthesecases,thedefaultvalueofthecoreThreadsattributemightcauseOpenLibertytocreatemorethreadsthanisoptimal,consideringtheotherprocessesthatarecompetingforCPUresources.
Inthissituation,youcanlimitthecoreThreadsattributetoavaluethatreflectsonlytheproportionoftheCPUresourcesthatOpenLibertyneedstorun.
maxThreadsThisattributespecifiesthemaximumnumberofthreadsinthepool.
Thedefaultvalueis-1,whichisequaltoMAX_INT,oreffectivelyunlimited.
Someenvironmentssetahardlimitonthenumberofthreadsthataprocesscancreate.
Currently,OpenLibertyhasnowaytoknowwhethersuchacapapplies,orwhatthevalueis.
IfOpenLibertyisrunninginathread-limitedenvironment,theoperatorcanconfigurethemaxThreadsattributetoanacceptablevalue.
TheOpenLibertythreadpoolcontrollerisdesignedtohandleawiderangeofworkloadsandconfigurations.
Insomeedgecases,youmightneedtoadjustthecoreThreadsandmaxThreadsattributes.
However,trythedefaultbehaviorfirsttomakesureyouneedtomakeadjustments.
8.
3.
SEEALSOExecutorManagementOpenLiberty2020OpenLibertyRuntimeGuide24CHAPTER9.
LOGGINGANDTRACINGOpenLibertyhasaunifiedloggingcomponentthathandlesmessagesthatarewrittenbyapplicationsandtheruntime,andprovidesFirstFailureDataCapture(FFDC)capability.
LoggingdatawrittenbyapplicationsusingSystem.
out,System.
err,orjava.
util.
logging.
Loggerarecombinedintotheserverlogs.
Therearethreeprimarylogfilesforaserver:console.
log-Thisfileiscreatedbytheserverstartcommand.
ItcontainstheredirectedstandardoutputandstandarderrorstreamsfromtheJVMprocess.
Thisconsoleoutputisintendedfordirecthumanconsumptionsolackssomeinformationusefulforautomatedloganalysis.
messages.
log-Thisfilecontainsallmessagesthatarewrittenorcapturedbytheloggingcomponent.
AllmessagesthatarewrittentothisfilecontainadditionalinformationsuchasthemessagetimestampandtheIDofthethreadthatwrotethemessage.
Thisfileissuitableforautomatedloganalysis.
ThisfiledoesnotcontainmessagesthatarewrittendirectlybytheJVMprocess.
trace.
log-Thisfilecontainsallmessagesthatarewrittenorcapturedbytheloggingcomponentandanyadditionaltrace.
Thisfileiscreatedonlyifyouenableadditionaltrace.
ThisfiledoesnotcontainmessagesthatarewrittendirectlybytheJVMprocess.
9.
1.
LOGGINGCONFIGURATIONTheloggingcomponentcanbecontrolledthroughtheserverconfiguration.
Theloggingcomponentcanbefullyconfiguredinserver.
xmlusingtheloggingelement.
However,loggingisinitializedbeforeserver.
xmlhasbeenprocessedsoconfiguringloggingthroughserver.
xmlcanresultinearlylogentriesusingadifferentlogconfigurationfromlaterones.
Forthisreasonitisalsopossibletoprovidemuchoftheloggingconfigurationusingboostrap.
propertiesandinsomecasesusingenvironmentvariables.
9.
2.
EXAMPLELOGGINGCONFIGURATIONSomecommonloggingconfigurationexamplesaregiveninthefollowingsections.
9.
2.
1.
ManaginglogfilestorageTheconsole.
logfileiscreatedbyredirectingtheprocessstdoutandstderrtoafile.
Asaresult,Libertyisunabletoofferthesamelevelofmanagement,likelogrollover,asitoffersformessages.
log.
Ifyouareconcernedabouttheincreasingsizeoftheconsole.
logfile,youcandisabletheconsole.
logfileandusethemessages.
logfileinstead.
Allthelogmessagessenttoconsole.
logarewrittentothemessages.
logfile,andyoucanconfigurefilerollover.
Todisabletheconsolelog,andconfiguremessages.
logtorolloverthreetimesat100Mb,usethefollowingconfiguration:9.
2.
2.
JSONloggingWhenfeedinglogfilesintomodernlogaggregationandmanagementtoolsitcanbeadvantageoustocom.
ibm.
ws.
logging.
max.
file.
size=100com.
ibm.
ws.
logging.
max.
files=3com.
ibm.
ws.
logging.
console.
log.
level=OFFcom.
ibm.
ws.
logging.
copy.
system.
streams=falseCHAPTER9.
LOGGINGANDTRACING25WhenfeedinglogfilesintomodernlogaggregationandmanagementtoolsitcanbeadvantageoustohavethelogfilesstoredusingJSONformat.
Thiscanbedoneinoneofthreeways:Usingthebootstrap.
propertiesfile:Usingenvironmentvariables:Usingtheserver.
xmlfile:Whenusingserver.
xmltoconfigurejsonformatsomeloglinesarewritteninthedefaultnon-JSONformatpriortoserver.
xmlstartupwhichcancauseissueswithsometools.
Forexample,jqwouldhavetroubleunderstandingthelogfiles.
9.
2.
3.
ConfiguringloggingforaDockerimageItiscommoninDockerenvironmentstodisablemessages.
logandinsteadformattheconsoleoutputasJSON.
Thiscanbedoneusingenvironmentvariables:Thiscanbesimplysetwhenrunningthedockerruncommandbyusing-etosettheenvrionmentvariables:dockerrun-e"WLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc"-e"WLP_LOGGING_CONSOLE_FORMAT=json"-e"WLP_LOGGING_CONSOLE_LOGLEVEL=info"-e"WLP_LOGGING_MESSAGE_FORMAT=json"-e"WLP_LOGGING_MESSAGE_SOURCE="open-liberty9.
2.
4.
BinaryloggingLibertyhasahighperformancebinarylogformatoptionthatsignificantlyreducestheoverheadofwritingtracefiles.
Generally,whenconfiguringbinarylogging,theconsole.
logisdisabledforbestperformance.
Thismustbeenabledusingbootstrap.
properties:ThebinaryLogcommandlinetoolcanbeusedtoconvertthebinarylogtoatextfile:com.
ibm.
ws.
logging.
message.
format=jsoncom.
ibm.
ws.
logging.
message.
source=message,trace,accessLog,ffdc,auditWLP_LOGGING_MESSAGE_FORMAT=jsonWLP_LOGGING_MESSAGE_SOURCE=message,trace,accessLog,ffdc,auditWLP_LOGGING_MESSAGE_FORMAT=jsonWLP_LOGGING_MESSAGE_SOURCE=WLP_LOGGING_CONSOLE_FORMAT=jsonWLP_LOGGING_CONSOLE_LOGLEVEL=infoWLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc,auditwebsphere.
log.
provider=binaryLogging-1.
0com.
ibm.
ws.
logging.
console.
log.
level=OFFcom.
ibm.
ws.
logging.
copy.
system.
streams=falseOpenLiberty2020OpenLibertyRuntimeGuide26binaryLogviewdefaultServer9.
3.
CONFIGURATIONSETTINGSBYSOURCEThetablebelowshowstheequivalentserver.
xml,bootstrap.
properties,andenvironmentvariableconfigurationsalongwithbriefdescriptions.
Fullconfigurationdocumentationisavailableintheconfigreferencefortheloggingelement.
ServerXMLAttributebootstrappropertyEnvvarDescriptionhideMessagecom.
ibm.
ws.
logging.
hideMessageYoucanusethisattributetoconfigurethemessageskeysthatyouwanttohidefromtheconsole.
logandmessages.
logfiles.
Ifthemessagesareconfiguredtobehidden,thentheyareredirectedtothetrace.
logfile.
logDirectorycom.
ibm.
ws.
logging.
log.
directoryLOG_DIRYoucanusethisattributetosetadirectoryforalllogfiles,excludingtheconsole.
logfile,butincludingFFDC.
ThedefaultisWLP_OUTPUT_DIR/serverName/logs.
ItisnotrecommendedtosetthelogDirectoryinserver.
xmlsinceitcanresultinsomelogdatabeingwrittentothedefaultlocationpriortoserver.
xmlbeingread.
ConsoleLogConfigconsoleFormatcom.
ibm.
ws.
logging.
console.
formatWLP_LOGGING_CONSOLE_FORMATTherequiredformatfortheconsole.
Validvaluesarebasicorjsonformat.
Bydefault,consoleFormatissettobasic.
CHAPTER9.
LOGGINGANDTRACING27consoleLogLevelcom.
ibm.
ws.
logging.
console.
log.
levelWLP_LOGGING_CONSOLE_LOGLEVELThisfiltercontrolsthegranularityofmessagesthatgototheconsole.
ThevalidvaluesareINFO,AUDIT,WARNING,ERROR,andOFF.
ThedefaultisAUDIT.
IfusingwiththeEclipsedevelopertoolsthismustbesettothedefault.
consoleSourcecom.
ibm.
ws.
logging.
console.
sourceWLP_LOGGING_CONSOLE_SOURCEThelistofcomma-separatedsourcesthatroutetotheconsole.
ThispropertyappliesonlywhenconsoleFormat="json".
Validvaluesaremessage,trace,accessLog,ffdc,andaudit.
Bydefault,consoleSourceissettomessage.
Tousetheauditsource,enabletheLibertyaudit-1.
0feature.
TousetheaccessLogsourceyouneedtohaveconfiguredhttpAccessLogging.
copySystemStreamscom.
ibm.
ws.
logging.
copy.
system.
streamsIftrue,messagesthatarewrittentotheSystem.
outandSystem.
errstreamsarecopiedtoprocessstdoutandstderrandsoappearinconsole.
log.
Iffalse,thosemessagesarewrittentoconfiguredlogssuchasmessages.
logortrace.
log,buttheyarenotcopiedtostdoutandstderranddonotappearinconsole.
log.
Thedefaultvalueistrue.
MessageLogConfigServerXMLAttributebootstrappropertyEnvvarDescriptionOpenLiberty2020OpenLibertyRuntimeGuide28com.
ibm.
ws.
logging.
newLogsOnStartIfsettotruewhenLibertystarts,anyexistingmessages.
logortrace.
logfilesarerolledoverandloggingwritestoanewmessages.
logortrace.
logfile.
Ifsettofalsemessages.
logortrace.
logfilesonlyrefreshwhentheyhitthemaxFileSize.
Thedefaultistrue.
Thissettingcannotbeprovidedusingtheloggingelementinserver.
xmlbecauseitisonlyprocessedduringserverbootstrap.
isoDateFormatcom.
ibm.
ws.
logging.
isoDateFormatSpecifieswhethertouseISO-8601formatteddatesinlogfiles.
Thedefaultvalueisfalse.
Ifsettotrue,theISO-8601formatisusedinthemessages.
logfile,thetrace.
logfile,andtheFFDClogs.
Theformatisyyyy-MM-dd'T'HH:mm:ss.
SSSZ.
Ifyouspecifyavalueoffalse,thedateandtimeareformattedaccordingtothedefaultlocalesetinthesystem.
Ifthedefaultlocaleisnotfound,theformatisdd/MMM/yyyyHH:mm:ss:SSSz.
ServerXMLAttributebootstrappropertyEnvvarDescriptionCHAPTER9.
LOGGINGANDTRACING29maxFilescom.
ibm.
ws.
logging.
max.
filesHowmanyofeachofthelogsfilesarekept.
ThissettingalsoappliestothenumberofexceptionsummarylogsforFFDC.
Soifthisnumberis10,youmighthave10messagelogs,10tracelogs,and10exceptionsummariesintheffdc/directory.
Bydefault,thevalueis2.
Theconsole.
logdoesnotrollsothissettingdoesnotapply.
maxFileSizecom.
ibm.
ws.
logging.
max.
file.
sizeThemaximumsize(inMB)thatalogfilecanreachbeforeitisrolled.
Settingthevalueto0disableslogrolling.
Thedefaultvalueis20.
Theconsole.
logdoesnotrollsothissettingdoesnotapply.
messageFileNamecom.
ibm.
ws.
logging.
message.
file.
nameThemessageloghasadefaultnameofmessages.
log.
Thisfilealwaysexists,andcontainsINFOandother(AUDIT,WARNING,ERROR,FAILURE)messagesinadditiontoSystem.
outandSystem.
err.
ThislogalsocontainstimestampsandtheissuingthreadID.
Ifthelogfileisrolledover,thenamesofearlierlogfileshavetheformatmessages_timestamp.
logServerXMLAttributebootstrappropertyEnvvarDescriptionOpenLiberty2020OpenLibertyRuntimeGuide30messageFormatcom.
ibm.
ws.
logging.
message.
formatWLP_LOGGING_MESSAGE_FORMATTherequiredformatforthemessages.
logfile.
Validvaluesarebasicorjsonformat.
Bydefault,messageFormatissettobasic.
messageSourcecom.
ibm.
ws.
logging.
message.
sourceWLP_LOGGING_MESSAGE_SOURCEThelistofcomma-separatedsourcesthatroutetothemessages.
logfile.
ThispropertyappliesonlywhenmessageFormat="json".
Validvaluesaremessage,trace,accessLog,ffdc,andaudit.
Bydefault,messageSourceissettomessage.
Tousetheauditsource,enabletheLibertyaudit-1.
0feature.
TousetheaccessLogsourceyouneedtohaveconfiguredhttpAccessLogging.
TraceConfigsuppressSensitiveTraceTheservertracecanexposesensitivedatawhenittracesuntypeddata,suchasbytesreceivedoveranetworkconnection.
Thisattribute,whensettotrue,preventspotentiallysensitiveinformationfrombeingexposedinlogandtracefiles.
Thedefaultvalueisfalse.
ServerXMLAttributebootstrappropertyEnvvarDescriptionCHAPTER9.
LOGGINGANDTRACING31traceFileNamecom.
ibm.
ws.
logging.
trace.
file.
nameThetrace.
logfileisonlycreatedifadditionalordetailedtraceisenabled.
stdoutisrecognizedasaspecialvalue,andcausestracetobedirectedtotheoriginalstandardoutstream.
traceFormatcom.
ibm.
ws.
logging.
trace.
formatThisattributecontrolstheformatofthetracelog.
ThedefaultformatforLibertyisENHANCED.
YoucanalsouseBASICandADVANCEDformats.
traceSpecificationcom.
ibm.
ws.
logging.
trace.
specificationThetracestringisusedtoselectivelyenabletrace.
Theformatofthelogdetaillevelspecification:component=levelwherecomponentspecifieswhatlogsourcesthelevelshouldbesetto,andlevelspecifieshowmuchtraceshouldbeoutputusingoneof:off,fatal,severe,warning,audit,info,config,detail,fine,finer,finest,all.
Multiplelogdetaillevelspecificationscanbeprovidedbyseparatingthemwithcolons.
Acomponentcanbealoggername,tracegrouporclassname.
Anasterisk*actsasawildcardtomatchmultiplecomponentsbasedonaprefix.
Forexample:*SpecifiesalltraceablecodeServerXMLAttributebootstrappropertyEnvvarDescriptionOpenLiberty2020OpenLibertyRuntimeGuide32thatisrunningintheapplicationserver,includingtheproductsystemcodeandcustomercode.
com.
ibm.
ws.
*Specifiesallclasseswiththepackagenamebeginningwithcom.
ibm.
ws.
com.
ibm.
ws.
classloading.
AppClassLoaderSpecifiestheAppClassLoaderclassonly.
ServerXMLAttributebootstrappropertyEnvvarDescriptionCHAPTER9.
LOGGINGANDTRACING33CHAPTER10.
TRUE-TO-PRODUCTIONINTEGRATIONTESTINGMicroShedTestingisaJavalibrarythathelpsyouwritetrue-to-productionintegrationtestsforyourapplicationinanenvironmentsimilartoproduction.
Tominimizetheparityissuesbetweendevelopmentandproduction,youcantestyourapplicationinthesameDockercontainerthatyouuseinproduction.
MicroShedTestingusestheTestcontainersframeworktoanalyzeyourapplicationfromoutsidetheDockercontainerwithoutaccessingtheapplicationinternals.
YoucanuseMicroShedTestingtodevelopintegrationtestsforyourOpenLibertyapplication.
Youneedtomakesurethatyourapplicationworksaccuratelyinproduction,similartothedevelopmentenvironment.
Integrationtestsassessmultipletestclassesandcomponents,butintegrationteststakelongertosetupandconfigurethanunittests.
Alternatively,unittestsareshorterandinvolvetestingindividualmodulesofanapplication.
Withshorterdevelopmentcyclesandlimitedtimeavailable,developersoftenrununittests.
MicroShedTestinghelpsyouwriteandruntrue-to-productionintegrationtestsforyourapplications,andstreamlinesyourintegrationtestswiththeTestcontainersframeworkforanefficientworkflow.
10.
1.
DEVELOPMENTANDPRODUCTIONPARITYDevelopmentandproductionparityisoneofthefactorsinthetwelve-factorapp,whichisamethodologytobuildmodernapplications.
Theideabehinddevelopmentandproductionparityistokeepthedevelopment,staging,andproductionenvironmentssimilar,regardingtime,personnel,andtools.
Tosimplifythedevelopmentprocess,developersoftenusetoolsindevelopmentthataredifferentfromproduction.
Forexample,youmightusealocalMavenbuildtobuildaprojectforyourapplicationindevelopment,buttheapplicationmightbedeployedtoaDockercontainerinproduction.
Differencesbetweentheenvironmentscancauseatesttofailinproduction,thoughthetestpassesinthedevelopmentenvironment.
MicroShedTestinghelpsachievedevelopmentandproductionparitybytestingtheapplicationinanenvironmentsimilartoproduction.
10.
2.
WRITINGINTEGRATIONTESTSWITHTHEMICROSHEDTESTINGLIBRARYYoucandeployyourapplicationsindifferentenvironmentswithcontainers.
WiththeTestcontainersframework,youcanusecontainersinatestenvironment.
MicroshedTestingisaJavalibraryforMicroProfileandJakartaEEdeveloperstotesttheirapplicationsinanenvironmentsimilartoproduction.
MicroshedTestingimplementstheTestcontainersframeworktosupportdevelopmentandproductionparityintesting.
WithMicroShedTesting,youcanwriteanintegrationtestthatlookslikethefollowingexample:@MicroShedTestpublicclassBasicJAXRSServiceTest{@ContainerpublicstaticApplicationContainerapp=newApplicationContainer().
withAppContextRoot("/myservice");@RESTClientpublicstaticPersonServicepersonSvc;@TestpublicvoidtestGetPerson(){OpenLiberty2020OpenLibertyRuntimeGuide34The@MicroShedTestannotationsearchesforaDockerfiledocumentintherepository,startsuptheapplicationinaDockercontainer,andwaitsfortheapplicationtobereadybeforetheteststarts.
The@ContainerannotationinjectsaRESTClientproxyofthePersonServiceclass,whichhelpsyousendHTTPrequestsontherunningapplicationcontainer.
The@RESTClientannotationsendsanHTTPPOSTrequesttotherunningcontainer,whichtriggersthePersonService#createPersonendpointandreturnsthegeneratedID.
ByusingthegeneratedID,youcansendanHTTPGETrequesttoreadtherecordthatwascreated.
TheJSONresponseautomaticallyconvertstoaPersonobjectbyusingaJSON-Btoken.
The@TestannotationsendsanHTTPGETrequesttofindaPersonobjectwiththe-1ID,whichdoesnotexist.
TheannotationassertsthattheapplicationcontainerreturnsanHTTP404exception.
10.
3.
SEEALSOGuide:TestingaMicroProfileorJakartaEEapplicationLongbobId=personSvc.
createPerson("Bob",24);Personbob=personSvc.
getPerson(bobId);assertEquals("Bob",bob.
name);assertEquals(24,bob.
age);assertNotNull(bob.
id);}@TestpublicvoidtestGetUnknownPerson(){assertThrows(NotFoundException.
class,()->personSvc.
getPerson(-1L));}}CHAPTER10.
TRUE-TO-PRODUCTIONINTEGRATIONTESTING35CHAPTER11.
DEBUGGING11.
1.
MANAGINGBUILDPROCESSESWITHTHEOPENLIBERTYMAVENPLUG-INYoucanbuildandtestyourapplications,whethertheyaresimpleapplicationswithasinglemoduleormorecomplexapplicationsthatconsistofmultiplemodules.
Afteryoudefinethedetailsanddependenciesofaproject,Mavenautomaticallydownloadsandinstallsallofthedependencies.
Italsorunsautomatedtestsonanapplicationafteritisbuilt.
Ifthetestsdon'tpassafteryouupdateanapplication,thebuildfails.
Youmustfixyourcode.
ThefollowingcoordinatesfortheMavenplug-inarerequired:TolearnhowtoconfigureasimplewebservletapplicationbyusingMavenandtheLibertyMavenplug-in,seeBuildingawebapplicationwithMaven.
JakartaEEapplicationsconsistofmultiplemodulesthatworktogetherasoneentity.
TolearnhowtobuildanapplicationwithmultiplemodulesbyusingMavenandOpenLiberty,seeCreatingamulti-moduleapplication.
11.
2.
TRACINGREQUESTSDistributedtracinghelpsyoutroubleshootmicroservicesbyexaminingandloggingrequestsastheypropagatethroughadistributedsystem,allowingdeveloperstotackletheotherwisedifficulttaskofdebuggingtheserequests.
Withoutadistributedtracingsysteminplace,it'sdifficulttoanalyzeworkflowsandpinpointwhenandbywhomarequestisreceivedorwhenaresponseisreturned.
Tolearnhowtomonitorandtraceloggingrequestsacrossmicroservicesinanapplication,seeEnablingdistributedtracinginmicroservices.
io.
openliberty.
toolsliberty-maven-plugin3.
1.
0OpenLiberty2020OpenLibertyRuntimeGuide36CHAPTER12.
MONITORINGOPENLIBERTYYoucanuseMicroProfileMetricsandMicroProfileHealthtomonitormicroservicesandapplicationsthatrunonOpenLiberty.
Enablingandreportingmetricandhealthcheckdataforyourmicroserviceshelpsyoupinpointissues,collectdataforcapacityplanning,anddecidewhentoscaleaserviceupordown.
12.
1.
MONITORINGWITHMETRICSWithOpenLiberty,twotypesofmetricsareavailabletomonitoryourapplications,RESTendpoint-stylemetricsthatareprovidedbyMicroProfileMetrics,andJavaManagementExtensions(JMX)metrics.
MicroProfileMetricscanbeaccessedbymonitoringtools,suchasPrometheus,andbyanyclientthat'scapableofmakingRESTrequests.
JMXmetricsaresuitableforusebyJava-basedmonitoringtoolsthatcancommunicatewithJMXservers,orbycustomJMXclients.
12.
1.
1.
MicroProfileMetricsandthe/metricsendpointTheMicroProfileMetricsfeatureprovidesa/metricsRESTinterfacethatconformstotheMicroProfileMetricsspecification.
OpenLibertyusesMicroProfileMetricstoexposemetricsthatdescribetheinternalstateofmanyOpenLibertycomponents.
DeveloperscanalsousetheMicroProfileMetricsAPItoexposemetricsfromtheirapplications.
Metricscomeinvariousformsthatincludecounters,gauges,timers,histograms,andmeters.
YoucanaccessMicroProfileMetricsbyenablingtheMicroProfileMetricsfeature.
Real-timevaluesofallmetricsareavailablebycallingthe/metricsendpoint.
Formoreinformationaboutaddingthesemetricstoyourapplications,seeMicroserviceobservabilitywithmetrics.
ForalistofallRESTendpoint-stylemetricsthatareavailableforOpenLiberty,seethemetricsreferencelist.
The/metricsendpointprovidestwooutputformats.
TheformatthateachresponseusesdependsontheHTTPacceptheaderofthecorrespondingrequest.
PrometheusformatisarepresentationofthemetricsthatiscompatiblewiththePrometheusmonitoringtool,whichisanopensourcemetricsscraper,datastore,andbasicvisualizationtool.
Thisformatisreturnedforrequestswithatext/plainacceptheader.
JSONformatisaJSONrepresentationofthemetrics.
Thisformatisreturnedforrequestswithanapplication/jsonacceptheader.
ThefollowingtabledisplaysthedifferentendpointsthatcanbeaccessedtoprovidemetricsinPrometheusorJSONformatwithaGETrequest:Table12.
1.
MetricsendpointsthatareaccessiblebyGETrequestEndpointRequesttypeSupportedformatsDescription/metricsGETPrometheus,JSONReturnsallregisteredmetrics.
/metrics/GETPrometheus,JSONReturnsmetricsthatareregisteredforthespecifiedscope.
CHAPTER12.
MONITORINGOPENLIBERTY37/metrics//GETPrometheus,JSONReturnsmetricsthatmatchthemetricnameforthespecifiedscope.
EndpointRequesttypeSupportedformatsDescription12.
1.
2.
JMXmetricsYoucanaccessJMXmetricsbyenablingthePerformanceMonitoringfeature.
Afteryouaddthisfeaturetoyourserverconfiguration,JMXmetricsareautomaticallymonitored.
ThePerformanceMonitoringfeatureprovidesMXBeansthatyoucanusewithmonitoringtoolsthatuseJMX,suchasJConsole.
JConsoleisagraphicalmonitoringtoolthatyoucanusetomonitorJVMandJavaapplications.
AfteryouenablemonitoringforOpenLiberty,youcanuseJConsoletoconnecttotheJVMandviewperformancedatabyclickingattributesoftheMXBeans.
YoucanalsouseotherproductsthatconsumeJMXmetricstoviewyourmetricsinformation.
ForalistofallJMXmetricsthatareavailableforOpenLiberty,seetheJMXmetricsreferencelist.
12.
1.
3.
BothtypesofmetricscombinedTheMicroProfileMetricsfeatureprovidesbasicmetricsabouttheJVMandaboutmetricsthatareaddedtoapplicationsbyusingtheMicroProfileMetricsAPI.
However,theMicroProfileMetricsfeaturedoesn'tprovidemetricsaboutOpenLibertyservercomponentsunlessit'susedalongwiththePerformanceMonitoringfeature.
IfyouenableboththeMicroProfileMetricsandPerformanceMonitoringfeatures,thentheMXBeansformonitoringandthe/metricsRESTendpointareactivated.
Inthiscase,metricsforOpenLibertyservercomponentsareexposedthroughbothinterfaces.
TheMicroProfileMetricsfeatureversion2.
3andlaterautomaticallyenablesthePerformanceMonitoringfeature.
12.
2.
HEALTHCHECKSFORMICROSERVICESAhealthcheckisaspecialRESTAPIimplementationthatyoucanusetovalidatethestatusofamicroserviceanditsdependencies.
MicroProfileHealthenablesmicroservicesinanapplicationtoself-checktheirhealthandthenpublishestheoverallhealthstatustoadefinedendpoint.
Ahealthcheckcanassessanythingthatamicroserviceneeds,includingdependencies,systemproperties,databaseconnections,endpointconnections,andresourceavailability.
ServicesreportastheiravailabilitybyimplementingtheAPIprovidedbyMicroProfileHealth.
Whenamicroserviceisavailable,itreportsanUPstatus.
Ifamicroserviceisunavailable,itreportsaDOWNstatus.
Aserviceorchestratorcanthenusethesestatusreportstodecidehowtomanageandscalethemicroserviceswithinanapplication.
HealthcheckscanalsointeractwithKuberneteslivenessandreadinessprobes.
Forexample,inamicroservices-basedbankingapplication,youmightimplementhealthchecksontheloginmicroservice,thebalancetransfermicroservice,andthebillpaymicroservice.
Ifahealthcheckonthebalancetransfermicroservicedetectsabugordeadlock,itreturnsaDOWNstatus.
Inthiscase,ifthe/health/liveendpointisconfiguredinaKuberneteslivenessprobe,theproberestartsthemicroserviceautomatically.
Restartingthemicroservicesavestheuserfromencounteringdowntimeoranerrorandpreservesthefunctionsoftheothermicroservicesintheapplication.
12.
2.
1.
MicroProfileHealthendpointsandannotationsOpenLiberty2020OpenLibertyRuntimeGuide38MicroProfileHealthprovidesthefollowingthreeendpoints:/health/ready:returnsthereadinessofamicroservice,orwhetheritisreadytoprocessrequests.
ThisendpointcorrespondstotheKubernetesreadinessprobe.
/health/live:returnsthelivenessofamicroservice,orwhetheritencounteredabugordeadlock.
Ifthischeckfails,themicroserviceisnotrunningandcanbestopped.
ThisendpointcorrespondstotheKuberneteslivenessprobe,whichautomaticallyrestartsthepodifthecheckfails.
/health:aggregatestheresponsesfromthe/health/liveand/health/readyendpoints.
Thisendpointcorrespondstothedeprecated@HealthannotationandisonlyavailabletoprovidecompatibilitywithMicroProfile1.
0.
IfyouareusingMicroProfile2.
0orhigher,usethe/health/readyor/health/liveendpointsinstead.
Toimplementreadinessorlivenesshealthchecks,addeitherthe@Livenessor@Readinessannotationtoyourcode.
TheseannotationslinktheprovidedendpointstoKuberneteslivenessandreadinessprobes.
Thefollowingexampledemonstratesthe@Livenessannotation,whichcheckstheheapmemoryusage.
Ifmemoryconsumptionislessthan90%,itreturnsanUPstatus.
Ifmemoryusageexceeds90%,itreturnsaDOWNstatus:ThefollowingexampleshowstheJSONresponsefromthe/health/liveendpointifheapmemoryusageislessthan90%.
Thefirststatusindicatestheoverallstatusofallhealthchecksthatarereturnedfromtheendpoint.
Thesecondstatusindicatesthestatusoftheparticularcheckthatisspecifiedbytheprecedingnamevalue,whichinthisexampleisheap-memory.
InorderfortheoverallstatustobeUP,allchecksthatarerunontheendpointmustpass:@Liveness@ApplicationScopedpublicclassMemoryCheckimplementsHealthCheck{@OverridepublicHealthCheckResponsecall(){//statusisupifusedmemoryis<90%ofmaxMemoryMXBeanmemoryBean=ManagementFactory.
getMemoryMXBean();longmemUsed=memoryBean.
getHeapMemoryUsage().
getUsed();longmemMax=memoryBean.
getHeapMemoryUsage().
getMax();HealthCheckResponseresponse=HealthCheckResponse.
named("heap-memory").
withData("used",memUsed).
withData("max",memMax).
state(memUsed9).
build();returnresponse;}}{"status":"UP","checks":[{"name":"heap-memory","status":"UP","data":{"used":"1475462",CHAPTER12.
MONITORINGOPENLIBERTY39Thenextexampleshowsthe@Readinessannotation,whichchecksforanavailabledatabaseconnection.
Iftheconnectionissuccessful,itreturnsanUPstatus.
Iftheconnectionisunavailable,itreturnsaDOWNstatus:ThefollowingexampleshowstheJSONresponsefromthe/health/readyendpointifthedatabaseconnectionisunavailable.
Thefirststatusindicatestheoverallstatusofallhealthchecksreturnedfromtheendpoint.
Thesecondstatusindicatesthestatusoftheparticularcheckthatisspecifiedbytheprecedingnamevalue,whichinthisexampleisdatabaseReady.
Ifanycheckthatrunsontheendpointfails,theoverallstatusisDOWN.
12.
2.
2.
Seealso:Guide:AddinghealthreportstomicroservicesGuide:CheckingthehealthofmicroservicesonKubernetes.
MicroProfileHealthfeatureMicroProfileHealthonGitHub"max":"51681681"}}]}@Readiness@ApplicationScopedpublicclassDatabaseReadyCheckimplementsHealthCheck{@OverridepublicHealthCheckResponsecall(){if(isDBConnected()){returnHealthCheckResponse.
up("databaseReady");}else{returnHealthCheckResponse.
down("databaseReady");}}}{"status":"DOWN","checks":[{"name":"databaseReady","status":"DOWN",}]}OpenLiberty2020OpenLibertyRuntimeGuide40APPENDIXA.
ADDITIONALOPENLIBERTYRESOURCESYoucanlearnmoreaboutOpenLibertyandtheAPIsitsupportsbyviewingresourcesontheOpenLibertywebsite.
OpenLibertyservercommandsOpenLibertyguidesJavaEEAPIMicroProfileAPIAPPENDIXA.
ADDITIONALOPENLIBERTYRESOURCES41