Mastering Spring Boot's Actuator

hello everyone good morning welcome thank you for joining us for this morning's talk about mastering spring boots actuator my name's andy wilkinson I work for pivotal where I'm a member of the spring bootie hi everyone my name is Maura Bobby and I also work for pivotal on Springville team with Andy thank you all for joining and I hope you're having a good conference so far all right so we thought we'd just start by Trani maybe fill in a blank for some of you about you know why is spring boots actuator called saturator I didn't know how many of you knew what an actuator was before you'd heard of spring boot actuator a few hands okay so an actuator is actually a physical device that's used so it's a mechanical device for moving or controlling something and we kind of see spring boots actuator as being a bit like that it's a device for basically controlling your spring boot applications so to start you on the the journey towards mastering spring boots actuator we thought the best way to get going was to show you some of the things that are new in the actuator in spring boot 2.0 and in spring boot 2.1 which we just released them for earlier this week and that will be going final next month okay and let's just jump straight into the code to see some of the new features in the actuator a tutorial so what we have here is a very simple spring boot application you can see you're familiar at spring boot application annotation and this is the main application class the application web properties file it's empty right now but we we are going to go ahead and show you some configuration options for your actuator end points just a quick look at the prom we are using spring boot 2.1 m4 so we just released the fourth milestone this week for the upcoming to one release the web starter will give you will start your application up on Tomcat by default and we have the starter actuator which will give you the actuator endpoints dev tools is just so that when we add the properties the application will restart will trigger a restart and automatically so let's go ahead and fire up this application if we take a quick look at the logs here you can see that that says it's exposing two endpoints beneath base path slash actuator so one of the changes that we made in a spring boot tool was the by default HTTP actuators are not enabled except for the health and the info actuators and we realized that a lot of times your actuators contain potentially sensitive information so we didn't want you to expose sensitive information accidentally to anybody over the Internet and health an info by default don't contain any additional details so we've exposed them out of the box it's a little bit different for the JMX actuators because JMX is inherently more secure than HTTP because by default you can only access their ambience if you're on the same machine you will see more actuators out of the box if you're using JMX so let's fire up j console and connect to our application so you'll see you'll see here within the JMS console you can see there are a bunch of endpoints listed many more as Medora explains than the two that you get exposed over HTTP by default because of jmx inherently being more secure a lot of the names that you're seeing here should be familiar to you from spring boot 1.5 so the beans endpoint for example but there are also some new endpoints in their schedule tasks endpoint is new in spring boot 2.0 gives you an insight into anything you set up with Spring Framework scheduling support you can see what's going on in there we have a bit more detail about that later on in the presentation there's also a caches endpoint which again is new in the spring boot to line and we've also reworked a few of the endpoints for example the HTTP trace endpoint has been renamed that was the trace endpoint in spring boot 1.5 renamed to HTTP trace to better reflect the fact that it is focused on tracing of HTTP requests rather than kind of broader tracing across the whole of your application there are a few more that you don't see in this list for example the sessions endpoint because our application doesn't have spring spring session on the class path which is just spring boot standard Auto configuration so if you drop spring session on there the actuator endpoint for that will be automatically enabled for you and we've also got you can so the kind of that list shown there in the in J console of the am beans available via JMX there's also kind of an HTTP equivalent for that where you can get a list of all of the information about the endpoints yeah and before that I just wanted to point out that in spring boot tool we've moved all the actuators under the actuator base path so we realize that in spring boot 1.5 we would place all the actuators at the root path by default you could configure it but when we started noticing that sometimes in your application you might want to use the info path for your own by snapping or maybe the end pad at the root of your application for your own request mappings so now we've grouped them under the actuator base path but we still give you a configuration option to configure the base path so you can put in whatever you want your actuators to be under using the management at endpoints or web base path property if you want to go back to the default 1.5 behavior you can just use slash and the actuators will be available at the root of the application but for now we're just going to leave them under actuator and going back to what Andy was saying we do have a we do have all the actuators available over HTTP as well and the way we can expose them over HTTP is using the management or endpoint store web exposure that include flag so you can specify a comma-separated list of endpoints or if you want to expose all of them over HTTP you can use the star and there's a there's a key difference here we've kind of there's two concepts to think about when you're you want to look at your configuration and know which endpoints will be available remotely so there's a concept of an endpoint being enabled and if an endpoint is enabled then that means that the beans will be created for it but you then also have to expose that endpoint to make it accessible externally so you can expose it over the web over HTTP or you can expose it over jmx so by default almost all of the endpoints are enabled but the exposure rules are different so for the JMX all of the endpoints that are enabled are exposed whereas for the web by default as majority explained we only expose the health an info endpoint but you can opt into exposing more customizing that as you need as is appropriate for the security of your environment there's also a management dot endpoints dot web dot exposure at exclude flags so let's say you want to enable you want to expose all the actuators over the web except for the beams actuator so you can do that with this kind of combination where you say star is include or expose all my actuators except for the beams actuator so these two properties together should give you a way to combine what you want to expose and not expose so go ahead and should we have a look at the the kind of the HTTP list of all the end points that are enabled so if you're if you've got a spring boot application and you want to know the your eyes that you can use to access a particular actuator or you want to see which have been exposed in spring book 2o with no other dependencies on the class pass we had something like this in one fight but you had to have spring hey to us on the classpath in spring boot - oh you don't need any additional dependencies and you'll automatically get this if so if you go to slash actuator the default base path whatever you've configured the base path to be for your actuator end points will give you this list of all of the end points in the your eyes that you can use to access them and this is used by some additional tooling that integrates with spring boots so for example cloud foundries integration for spring boot that we'll look at a little bit later uses this information to snow which endpoints you've got available which controls the extra information that appears in the cloud foundry apps manager dashboard and there's also how many of you've heard of spring boot admin a few so there's a third-party project called spring boot admin open source project that provides like an administrative dashboard for spring boot applications it will do some kind of service discovery and things as well so it will you know you can automatically set things up so that your applications will automatically register with the dashboard just by adding a small dependency to your app and again it uses this slash actuators endpoint to get a list for all the actuators that are enabled to control the information that it will display to you in its dashboard as well right so here's the list of all the available actuators from the actuator end point you can see one that's missing there is the shutdown end point yep and that's because the shutdown end point is disabled by default because it lets you shut your application down and that's something we think you should really opt into if you know you've secured your shutdown end point properly so let's go ahead and enable the shutdown end point as Andy mentioned previously each end point has an enabled and disabled flag so to enable the shutdown end point we can use management or end point out shutdown not enabled and let's set it to true if I rebuild dev tools should pick up that property change and we should be able to just hit the shutdown end point sorry and that's gonna be a post so I need to put that here so it gives you a message shutting down by not the kind of thing that you want someone to stumble across hence why it's disabled by default the other thing that's new in spring boot order over the actuators is the health endpoint has some more configuration options so by default if you take a look at the response from the health endpoint this is what happens when someone wants to shut down an endpoint oh right I need to restart the application yeah thank you Andy so it did shut the application down right so if I hit the health endpoint now I can see that I just get back a status which tells me that the application is up but if you want some additional details about your health indicators like if you have the datasource health indicator and you would want to know how that is doing you can do that using the management dot endpoint or helped out show details flag by default it's never again for security reasons we don't want to we want you to opt in to the details whenever you know you've secured the endpoints as you wish so the options are never which only shows you the status there's the when authorized which means that if there is an authenticated user and the user has the right roles then show the details for any other user or for an unauthenticated user to show status of up and then always means it will always show you the health details so which one should be big actually when was Roy's first let's do that so it's restarting the application and if we run that now with Wayne authorized it's still not giving us any details because we haven't authorized with the application so that leads us on now to some changes and that we've made to support the actuator that integrates with spring security so we've tried to make it easier for you to customize the security of the actuators so if we want to be able to authorize we need to set up spring security and we need to set up whether we're allowed you know permission to access particular endpoints whether you need to be authenticated what role you need to be in whether you know will permit all access so to do that we can add the spring boots security starter as you normally would for if you wanted to use spring security with spring boot and I'm manually restarting the app this time because it's a classified change dev tools won't be able to detect that and and then securing the actuators endpoints is really very similar hopefully those of you familiar with spring security it's very similar the fact that the actuator doesn't really make that much difference you add a configuration class you extend spring Security's web security configure a doctor and then you can override the HTTP security method which will give you a bunch of configuration options using the spring security DSL so HTTP dot authorize requests and because we've now changed our security model a little bit in spring boot to dot o we give you some convenience methods to secure your actuator actuator endpoints because your actuator endpoints could be under any base path you might have configured it to be under a different base path you don't need to know what the base path is here when you're creating the security request matter you can use this class called endpoint request and there's a small gotcha here so you can see there's two endpoint requests in this list so a lot of you will probably already knew in know in spring boo - oh and kind of in the whole release train that built on the top of Spring Framework five we introduced reactive support pretty much across the whole of Spring portfolio so that came up from framework into boo into spring security into various other projects and there are slightly different models for reactive security and for kind of the blocking servlet based security so there are two end point request classes in different packages one if you're building a reactive app and one if you're building a an app that's using that servlet based so if you're using endpoint requests just take care to make sure that you get the one from the package that's appropriate to which which web stack you're building on top of right so endpoint request has a few static methods the - you can specify the endpoints that you want the request matter for so I'm gonna say from for the health endpoint permit all requests so permit unauthenticated requests to the health endpoint we'll go back to that when authorized flag that we added for the details and show you how that works in combination with the permit all endpoint request to any endpoint so any endpoint other than the health endpoint because the health endpoint has its own request matcher we can say that it has some rules so let's say it has the actuator role and let's just use HTTP basic to secure that so if we run the application again now and try to hit our health endpoint let's try and hit it with username and password so because we have spring security on the classpath spring boot we'll give you a default user out of the box with a generated password and I use the name of user is this light aside that randomly generated passwords is basically our attempt to make things a bit more secure out of the box so that you don't get left with like you know admin admin or whatever and anyone can access your app so by default you'll get a random the username is constant but the password is randomly generated each time your app stars so hopefully that reduces the risk of you accidentally giving someone access to your app and also hopefully encourages you to set up some user details storage that's that's more robust and more ready for a proper deployment right so we just hit the health endpoint here with a user and password and as you can see that instead of just a status of up we now get more additional health details from the health endpoint because we have the when authorized flag if we were to hit the health endpoint with no user it would still allow access because our security matcher allows from says permit all requests to the health endpoint but we don't see the additional details so you can think of this to be useful if let's say your application you have a load balancer or some kind of monitoring system checking if your application is up so you just hit the health endpoint to get the 200 response and let's say you get healthy the application is down you can have a user actually log in to view additional details should we try an ad Webb flux now yeah so well if we clear remove the security from the picture just to simplify a little bit so we don't have to update the security configuration to the reactive model a change that we made in spring boo 2.0 so take a bet step back to 1.5 spring boots actuator was quite tightly coupled to spring MVC and we had requests from various people because in the spring boot one direct line we also support it Jersey for those of you preferred the jax-rs programming model and you could use Jersey rather than spring MVC if you chose to do so and there were a number of people who did and they quite reasonably said you know can I use the actuator on top of Jersey and we always had to say no if you can still use Jersey for your own end points but if you want to use the actuator then you need to have spring MVC in there as a dependency as well and it wasn't the end of the world but it did mean that you had some extra dependencies in your app made it a little bit bigger he used a bit more heap none of which was ideal so in spring brute 2.0 we knew that this problem is only going to get worse because web flocs was getting added into the picture and asking people to have an it spring MVC dependency when you're trying to use web phlox wouldn't have worked because web flops can run on top of Metis which doesn't have any servlet support so spring MVC we just wasn't an option in that environment so that's really what prompted a lot of the changes in the actuator in spring boot 2.0 and we wanted it to work to be a bit better detached from the web framework so that we could run it on top of web flux and on top of Jersey in addition to the existing spring MVC support so we can just switch the starter from start to web to start a web flux start the app back up and all of the code for all of the endpoints and we'll look a little bit later at writing your own end points none of that code has changed so you just write your endpoints once and they will run on top of Jersey or web flux or spring MVC without you having to make any changes and as you can see it started on nettie by default because that's the that spring boot starts up on if it's a web flux application and let's just make sure things work so let's go ahead and hit our health endpoint still up and running so all you had to do was change the dependency in your bomb and the actuator infrastructure as Andy said we'll just adapter the web framework okay so just two we're just kind of summarize now and what little question so the question was can you change the health endpoints path or any individual endpoints path so that only one of them is under the root and the answer is that you can't you can move you can change the path that each individual endpoint is mapped to so say you didn't like slash health and you wanted to change it to /foo you could do that but you can't just if the base path moves all of the endpoints or none of the endpoints so you could you can move them all to the root or leave them all under something but you can't just pluck one out and move it expose it under the root mapping you have to it's an all-or-nothing all right there's a question but maybe we can take questions later because we have a lot to cover okay so what's new endpoints are they're all under slash actuated by default and you can move them should you wish to do so using the management or EMM points web base path property you can set that to slash if you want to move everything to the root or you can set it to admin or management or whatever might be appropriate for your environment and when you where you expect to find that sort of information so as we discussed there's kind of a difference between endpoints being enabled and being exposed and if you want them to be accessible remotely then you need to use the exposure properties so there are two of those so there's exposure to include an exposure to exclude you can use a wild-card with include you can also use a wild-card with exclude other that's kind of pointless because it will exclude everything the exclude property takes precedence over the include as Medora show so you can use include with a wild card and then excludes just to switch a few of them back as a more concise way of configuring that sort of arrangement there are equivalent properties for GMX as we discuss they have different defaults because we consider jmx to be more secure at the box because it's you have to switch something on for JMX to be remotely accessible by default for someone to connect via jam X they need to be able to run a process on the local machine so you have bigger things to worry about them whether they can access your endpoints if someone's already managed to do that all of the endpoints have enabled properties and all of them are enabled by default other than the shutdown endpoint so you can set management endpoint shutdown got enabled that won't defaults to false you can set that to true if you wish to enable the shutdown endpoint and equally if you wish to disable any of the other endpoints then you can use management or endpoint ID of the endpoint enabled and set it to false to switch them off we looked at show details for the health endpoint so you can control you have some quite fine-grained control over who can and can't see the details of the health of your application three possible values there always which means anyone who has access to the endpoint will see all of the details of your applications health you can set it to never which means that no one will see any details and all they'll get is status up or down or you can set it to when authorized and then if your access the endpoint as an authenticated user and that user is in one of the required roles then they'll see the details otherwise they won't by default there there are no roles that that user is required to be in so by default if you set it to when authorized then any authenticated user is considered to be authorized so you may want to if you're using when authorized you may also want to narrow that down to users that are in specific roles we saw endpoint requests for configuring the security of your endpoints there's both servlet and reactive variants of endpoint requests and then lastly we saw that you can use the actuator on top of web flocks we damand maduro demo that you can also run out on top of jersey and it's just a case of changing the dependency so you'd swap out start a web for starter jersey or starter web for start a web flux and the actuators infrastructure will take care of everything else for you and that applies to the endpoints available out of the box and also any that you write yourselves which you'll be learning how to do shortly so we looked at some of the new endpoints we showed a few of them in j console and now we just like to kind of talk you through in a bit more detail some of the new endpoints and show you their capabilities so one of the new endpoints in spring butoh is the scheduled tasks endpoint and it was inspired from a proposal from one of the members of the spring community unfortunately i think they had submitted a pull request but by the time we got the pull request Andy and Stefan had already started changing the actuator infrastructure for to rato they were doing a complete rewrite so we couldn't use their pull request and but we did get inspired from their proposal and it triggered some changes within Spring Framework itself to give us more information about the schedule test running in your application so if you hit the schedule tasks activate our endpoint that the response looks somewhat like what you see on the screen the runnable is the method that's going to be scheduled and the expression is the time that it's going to run at or the cron for the cron jobs we have similar configuration for fixed delay here you can see there's an initial delay and an interval this kind of the scheduled task actuator is useful if let's say you have a bunch of scheduled tasks in your application and things are not running as expected you can go to this actuator and see if the configuration is right you're scheduled tasks the next one is the sessions endpoint and this is a contribution from another member of the community veteran Pavich the sessions endpoint will be available when you have spring session on the class path and as you can see the response looks somewhat like this so we can get the session for a particular user you will see when the session was created when it was last accessed if it's expired or not and you can also hit the delete delete method on the sessions endpoint to delete sessions for a particular user caches so the caches on point I believe is new in spring boot 2.1 and so it will be available once to dot it's available in the milestones that are already if you want to give it a shot or if you want to go with spring go to that one when it's released you'll be able to use that once 2.1 is generally available again a contribution from the community so I think we're seeing a sort of pattern here a lot of the new actuators are contributions from the community and maybe that has something to do with the fact that the actuator infrastructure was rewritten so that it's easier to add custom actuators now than it was in the one dot X line and if you have written a custom endpoint or have an idea for an endpoint that you think would be useful then you know we love getting pull requests or issues making suggestions so you know don't don't be shy about OSHA opening issues or pull requests in the spring boot tracker because all of these have come from the community and we'd love to get more if there's ones that you that you've written or that you think would be generally useful from your experience because you're you know better than I do about run you know the whole boot team you know you or you're running spring new applications in production probably on a daily basis so you have some insight that we don't so we love you know we'd love to hear your suggestions for any that any holes that we could plug in what the actuator offers and the caches endpoint as the name suggests it will give you a list of all the caches available in your application the structure is we have the cache managers at the top level which are keyed by ID and under that we have the caches keyed by name the target is the underlying native the fully qualified name for the underlying native cache you can also retrieve from retrieve caches using the cache name so for a single cache if you want to just get a single cache you can do that using the name of the cache so here you'll just be able to see the target the name and the cache manager for that particular cache the caches endpoint also lets you evict from caches so you can delete from all the caches or you can delete from a particular cache another new endpoint that we've added is the integration graph endpoint again another contribution for the from the community so this is actually something that's built in the integration graph thing is something that's bring integration has had for a number of releases now but we've now made it available via the actuator so again this is one like the session endpoint that appears automatically if you add spring integration to the class path and you're using the actuator will automatically configure the integration graph endpoint for you and it gives you information about all of the police bring integration components that you're using and how they're wired wired together so you can see here here's a node within the graph so in this case it's a it's a it's a channel is the null channel so you'll get kind of an entry like that for every component and then you also get information about the links in the graph and this would allow something to then visualize the graph so you get information about all the nodes in the graph and the links and you can take all of that information then basically plot the graph showing so here we can see that for example no 2 is connected to node 3 in the graph we've also made some changes to the health endpoint in spring boot 2.1 so as we've just seen and i imagine a lot of you were already familiar with you can hit slash actuator slash health and you'll get information about the status of your application and also in the details if you've configured things so that's exposed you'll also get information you're broken down by each individual health indicator that's contributed information about the applications overall health so here we can see we've got some information about the health of a database and also the health of a broker that the application is is talking to in spring boot 2.1 we allow you to drill down into the health so rather than just querying slash actuator slash health you can query slash actuator slash health slash components and you'll get this kind of more focused view on a particular part of your applications health so here we've just focused on the broker piece of the health response so we can see yet the brokers is up and we still get the details and the same rules apply in terms of whether or not those details are visible it's done with the same overall configuration and you can even drill down even further so in this case the broker there were multiple instances that we were talking to so you can focus right down onto the health of a particular aspects of your application should you wish to do so so now we just like to take a bit of time to show you some of the cloud foundry integration that the actuator offers and one of the cool things that's come out of the work that we've done to get the actuator working on top of Webb flux and Jersey and additional to spring MVC is that you can now also use the Cloud Foundry integration irrespective of which web stack you're using it will still integrate and you'll get the kind of the enriched dashboard showing you more information about a spring view apps that Medora is going to show us now so how many of you have heard of apps manager okay a few hands apps manager is sort of you can consider it the dashboard for your applications running on Cloud Foundry and what you can see here this is apps manager that's available on PWS or pivotal Web Services which is pivotal hosted version of Cloud Foundry and we added actuator integration for spring boot applications for apps manager as part of spring boot 1.5 itself but as Andy said it's now also automatically available for the web Fluxx applications and for Jerzy applications so let's see let's take a look at how the dashboard is enhanced with some information from the springboard actuators so first of all you can see that there's this tiny little spring boot logo next to the application name that tells you that this is a spring boot application and apps mallet weather apps manager get this information from so we looked a little bit before at the slash actuator endpoint which gives you a list of all the actuators that that were available in your application and we have the same thing available for when your application is running on Cloud Foundry we detect that the application is running on Cloud Foundry and we offer the same actuator list at the Cloud Foundry application path so if you see here apps manager hits your applications route slash Cloud Foundry application to get a list of all the actuators that are available in your in your application and the reason why apps manager is not using the regular slash actuator path and is using this different Cloud Foundry application path is because we wanted to secure the Cloud Foundry application path using OAuth tokens from the UAE the UAE is cloud foundries user authentication and authorization system so we already have and inbuilt authentication mechanism built into the platform and we just wanted to use the same for the actuators on Cloud Foundry it also means that your own application security you deploy your app to Claire foundry you don't need to worry about you know am I am I going to allow how do I allow apps manager to connect to the app it kind of takes advantage of the fact that there's already this ability to authenticate and authorize because of the UA a within Clio foundry so it's something that you can just kind of deploy and you don't need to worry about the there will be a secure connection established between the dashboard and your app without you having to perform any additional configuration right and apart from this spring boot logo here there are a few other things that apps manager gets from the actuate our endpoints the help for each instance of the application shows information from the health actuator so this is along with the health details that the health actuator exposes and the reason why we are showing the health details is because we have authorized that the user is authorized to view this application and it's details on Cloud Foundry this hello health indicator I've just added a dummy health indicator which returns the status of up every time you can add any custom health indicator that you want and map it to how you want to return the health of your application in addition to that let's look at the loggers endpoint so this is an interesting one because you can actually change the runtime configuration of the loggers in your application through Apps manager and in the backend this uses the loggers actuator so if I let's start tailing the logs and if I filter by my applications loggers I'm gonna change the scheduled logger to be debug it was at info and we should see some debug logging output from the sketch schedule logger class so this we couldn't see this before because this was only logging at the info level but we just dynamically changed this and you automatically start seeing the debug logging so this is using the loggers actuator you can use this actuator even outside of CF it's just making a a post request basically saying set the name they said we're in fact this recover the lockers endpoint a bit more detail but it's basically a post request basically saying this logger set its level to you know debug or info or whatever so you can do it yourself using curl or you can build your own dashboard on top it's just an HTTP POST [Music] so the question was are these logs automatically available what you have so this is I don't know what the retention policy yeah in cloud foundry we are just I mean apps mine just pulling the console logs just real quick another interesting feature that apps manager integrates with is information get information from the info endpoint so let's say you deployed your application with some latest change that you made and it broke and you want to see which commits broke your application apps manager will link to the commits that was used to deploy the application so you can go ahead and figure out what's going wrong and this information comes from the info actuator endpoint I'm not sure about other version control systems does the actual it's trip well it will give so the the question is is it just for github the info endpoint captures information it's basically captured at Build time it's metadata that's baked into your app and it's just information about this is the git repository this is the URL of the get repository this is the hash of the commit and then apps manager is just surfacing that information in the dashboard so as long as you provide a URL that's accessible then it doesn't matter it's on github or or any way it's just the URL plus the hash of the commitment so the question was do you need to do anything to enable this integration or is it just enabled by default the apps manager integration so for the get information that was available you have to add the get plug-in to your palm file and whenever there's a gift or properties file available at the root of your class path that is exposed via the info end point and then apps manager will be able to get it you have to set an additional flag to say that the get information mode is full so that apps manager gets all the information but apart from the get in get information the other actuators are integrated by default into apps manager if you have the actuator dependency on your class that's okay I think that's pretty much what I wanted to show for the absent so just a quick summary of what we saw there so the end points they were all available under slash cow foundry application slash actuator as we already explained that's done for security reasons that's a separate endpoint that's secured via the UA a so that from your applications perspective you don't need to worry about how Apps manager is going to access the app is it going to be done securely and that's something that switched on automatically when spring boot starts up it can detect that it's running in Cloud Foundry and it can auto configure that stuff for you and then the UA a takes care of making sure that the apps manager is has authenticated and as authorized to be able to access the the endpoints without you having to configure anything so yeah Balaji ray a token you can switch this off if you want if you're not comfortable with this happening you can set management co-founders are unable to false and then you'll lose some of the while all of the spring boots specific stuff in the apps manager dashboard so it's yeah it's a trade off are you happy with this stuff happening or not if you're not you can switch it off and again this works on top of Jersey Webb flux or spring MVC because of the fact that the actuator infrastructure is now web container agnostic all right well one another thing that we've worked on in spring group 2.0 is to provide better API documentation for accessing the actuators endpoints we actually had in spring boot 1.5 we had a spring boot actuator Docs module how many of you were aware of the spring boot actuated docks module three people that's pretty much as many downloads as it goes well it unfortunately wasn't very discoverable the idea was that you had this module you added it to your app and then your app would self host API documentation for the actuator but unfortunately no one really knew about it partly because if it's self hosted Google can't find it so if you're searching on web you know how do I do this with the actuator it wasn't going to be indexed by any search engines so we rethought that approach in spring boot 2.0 and so we now have sitting alongside the reference documentation and the Java doc we now have this separate set of documentation produced using spring rest Doc's that describes all of the actuator endpoints for you so there's detailed API information for accessing the actuators endpoints over HTTP and you can see here on the left-hand side in the table of contents we have entries for all of the different endpoints so there's every single endpoint that's available out of the box there is detail detailed information about it will give you information about example requests and response detailed information about the structure of the requests you know we have kind of Jason pass things that says you know at this point in the JSON document you can expect to find this thing so hopefully that should give you all of the information that you need to you know make full use of all the actuator end points and it will tell you you know we talked a little bit for example about being able to send a delete request to the cache at endpoint so it'll give you information about all the different HTTP verbs that all the endpoint support to do sniffing things with them so posting to the loggers endpoint or a delete to the caches endpoint tells you about all the path variables and everything that they support so hopefully that will be more useful and as I said it just sits online alongside it's a sibling of the reference documentation and the Javadoc and things so in you know you go Doc's spring to io / Bing boot slash the version and then you'll find it sitting alongside the documentation for all the other all the other components right and the last thing that we wanted to talk about what's new in the actuators in spring Butera or is metrics I'm not going to spend a lot of time talking about metrics because I am not knowledgeable to do so but I just wanted to mention that in spring butoh we've added support for a metrics instrumentation library called micrometer you've probably heard of it or seen talks related to micrometer it is a facade over multiple monitoring systems so you can export your metrics to a multiple back-end system such as data dog New Relic Atlas and there's a whole bunch of others which you can find in the documentation so the one of the key differences between the Springwood 1.5 actuators and the support that we've got with micrometer in string boot - is that micrometer gives you metrics so you can actually tag your metric with multiple tags and then use those tags to drill down to see what's going on in your application so let's say you have tags such as the method for HTTP requests or the status code you can go in and see how many post requests with status code of 200 or something like that if you are interested in learning more about micrometer and how it integrates with Springwood too you can you can view a recording of John's talk because unfortunately John stock was yesterday so but once the recording is available John Schneider's talk on observe observability should cover micrometer in much more detail all right so now we'd like to shift kind of into the second half or not quite half because we've got about 20 minutes left of the presentation to take you through how you can write your own endpoint so we've talked about the infrastructure and the changes and the fact that it you can now write the endpoints and they'll run on top of spring MVC and web flocks and Jersey and we're now like to kind of by example take you through some of the existing endpoints and show you the new endpoint programming model so that hopefully you'll leave here armed with the information you need to to write your own endpoint so the first one we'd like to look at here is the sessions endpoint so against contribution from FedRAMP povitch and so the first thing to notice here is the endpoint annotation so we've we've referred to various endpoints throughout the presentation so far by their IDs and when we were configuring them enabling them exposing them excluding them we were using those IDs so when you want to write an endpoint the first thing to do is to create a class annotate it with endpoint and give it an ID and that ID has to be unique within your application and you'll get a starter failure at runtime if you have multiple endpoints with the same ID and the ID is used to map by default is how the matter the your I for the endpoint created so we have the sessions ID here and that goes down straight down map straight down into the URL so slash actuator is the default bathed path and then the ID is the part that's used to identify a particular end point within your application so once you've got your kind of your basic your basic endpoint set up you need to be able to make it do things and we call those operations on an endpoint and there are different types of operations that you can perform so this is a read operation taken from the sessions endpoint so this is an operation that you're going to make a request to it and the actuator is going to give you some information back you're reading some information from the system so you use the read operation annotation on a method on your endpoint class and in this case we're taking some input so there's a user name so we're wanting to say this is how the sessions endpoint provides an operation for getting a particular users sessions and it's going to return a sessions report for you and the infrastructure will handle taking that response that session support object marshaling it to Jason and returning it to you as a JSON based response very you know if you're familiar with spring MVC controller or a web fox controller is very similar you just return something and we worry about mapping it to Jason for you so you can see here because it's a read operation it's mapped to HTTP GET and then you know slash actuator slash sessions and then the user name comes into play and that's automatically mapped to a query parameter so you have because you've your parameter to the method is called user name you automatically get a user name query parameter on the URI so here we're asking for all of Alice's sessions an important part to note we rely on the Java rate in Java rate you can compile your code with - parameters and that automatically means that all of the parameter names are baked into the bytecode and then they're available to us at runtime and that's how we know that your user name parameter here was called user name and so that controls the name of the query parameter and will automatically if you're using us bring boost data with maven or your using the Gradle plugin will automatically configure the Java compiler for your own app to enable - parameters but if you're not that's something to be aware of you'll want to compile if you're writing your actuator endpoints you'll want to compile them with the - parameters option so that we can get that information out at runtime so here's another read example this one's slightly different so the the previous one was kind of using the username as kind of a search to say well I want everything that map's these criteria so again here we got a read operation a session descriptor so here we're returning this time an individual session so other report about lots of sessions and we're returning some information about a single session so here we're using so the difference here is that the method parameter is annotated with selector and that tells the actuator infrastructure this parameter should be used to select a specific thing and here we want to select a session with a particular ID so this gets mapped again to a get request because it's a read operation and this time the session ID gets mapped because it was annotated with selector rather than getting mapped into a query parameter it's mapped into a path parameter in the array in the URL so this we're now creating the URL for a specific resource rather than kind of something that's more like a more like a search actually if I go another thing you can see here is that we're returning null in some cases so there might not be any sessions with that particular ID the endpoint infrastructure will automatically handle if you return null it will automatically map that to an HTTP 404 and whereas if you return an actual object that we're going to marshal to Jason then that'll automatically be an HTTP 200 okay response all right as Medora also mentioned you can use the session input to delete figs so you can make a query to say what I want to get rid of this session so for example if you know someone wants to log out on all their devices and you know you have some kind of support infrastructure to set up to do that you can use the session endpoint to help you so you can delete an individual session using the delete operation so again it's very similar to a read operation you just stick the delete operation annotation on your method this one returns void there's nothing really to return it's just the delete happens there's no information to come back that will get automatically mapped to an HTTP 204 response so that's kind of basically saying successful but there's no content so it's an indication in the status code that the response won't have any body and again we're using a selector here to identify a specific session that we want to delete and this time the delete operation as you might imagine hopefully it's it's intuitive at this point the delete operation gets mapped to the HTTP delete verb and the session ID again in the same way as it did for the get request because it's annotated with selector it comes down into a path parameter within the URL switching now to the loggers endpoint the loggers endpoint has a write operation so this is the endpoint that was used when Medora changed the log level in the apps manager demo so again very similar endpoint annotation ID this time it's the loggers endpoint we have a write operation this time so this is how you pass information into the actuator and ask it to make a change for you we're returning void again so that will get mapped to an HTTP 204 assuming the request is successful here we're using the selector again so we're saying we want to select a specific logger and that's the log of the level of which we want to configure and we're also passing in the log level so this is basically saying for a particular logger set it's log level to whatever is passed in and the nullable annotation here is saying to the actuator and point infrastructure that this argument is optional you don't have to pass it in if you're familiar with how loggers generally work they're kind of they're hierarchical and they inherit their level from their parent logger so if you set like a level on Condor example and then you have Condor example dot alpha that hasn't got a level configured on it it will automatically inherit that from its parent from the Condor example logger so there may be a case where you've set a very specific logging level for kind of a lowdown logger and you want to clear that and just ask it to inherit the level that's been configured on one of its ancestors in that case you just wouldn't pass in a level so and that would just clear it out and allow it to inherit from one of its ancestors again and that's what the use of the nullable annotation lets you do so we can see this the right operation gets mapped to an HTTP POST request and the name of the logger comes down into the into the URI and then we also need to be also also how do we pass the information about the level and this is automatically mapped into the JSON body so you send a post request with the body with configured level and in this case we're setting it to debug and again that configured level that's the key in the JSON payload is named configured level because that's what the method parameter was work all the calls and again that's relying on the - parameters switch and that information being available in the byte code so that's kind of the the basics of the programming model but there are also some things that we've added to let you go beyond that when that doesn't quite give you what you need if you have more advanced needs then you can do so amador take us through that now so in addition to the endpoint annotation that's been added in swing boot tool we've also added some technology specific annotations because you might want to change the behavior of your actuator endpoints for a particular technology so you might want the actuate to do something over HTTP whereas it might do something else over jmx let's take the health endpoint for examples so we have the health endpoint web extension and that's using the add endpoint web extension annotation and the endpoint attribute there is the target endpoint that you want to extend and the reason we are using this extension for the health endpoint is because when you get the overall health of your application so let's say you get status up from the health endpoint we want to map that up to an HTTP status code so up will map to HTTP 200 by default down Maps - I think 503 service unavailable by default and that's the kind of behavior that we've put in into the web extension for the health endpoint one thing that you see here is that the return type is a web endpoint response and if you're familiar with spring MVC it's this is similar to the response entity class but the reason why we are not using response entity is because this is web infrastructure agnostic we didn't want to tie ourselves to a particular web framework and which is why we added this custom return type another thing you notice is security context so a little bit before in the talk we saw how the health endpoint was returning details based on whether the user was authenticated or authorized and we can do that using the security context interface which can give you the principle that's present in the authentication and whether that user is in the role that you want the that you wanted to specify for the health details again we are using the security context we are not tying ourselves to httpservletrequest because in in the MVC were in the sublet world you can get weather users in a row or the principal from the HTTP server requests but we want abyss to work for web slugs too so we've added this web infrastructure agnostic interface the last thing that we wanted to mention in this talk is something that is a little bit of an edge case and in most cases the endpoint infrastructure that is available to you should work but let's say you were using spring boot 1.5 actuator customization to write your own custom actuators and because the spring boot 1.5 actuators were tied to spring MVC then there were a few things that you could do in spring boot 1.5 which we wanted to continue you continue allowing in spring boot 2 and one such use is is the servlet endpoint annotation so let's say you have a third-party servlet that you wanted to expose as an actuator endpoint you can do that now using the add servlet endpoint annotation and the advantage of using the add servlet endpoint annotation is that when you change the base path of your actuators this endpoint will also move under that base path the security model that we saw initially with endpoint requests will also apply to the servlet endpoints that you expose using at servlet endpoint you just need to use this annotation and a little helper method which tells the actuator infrastructure which servlet you want to expose as an endpoint you also get properties for enabling the endpoint so the and they include the exposure include an excludes2 it basically makes a servlet appear as if it was just a normal endpoint so you get all of the configuration options that we've them that we've seen and in addition to that we have the controller endpoint and the rest controller endpoint these two annotations are tied to spring MVC two spring MVC and spring web flux so you won't be able to use these if you have Jersey or over jmx and in spring boot 1.5 you could write MVC actuator endpoint adapters to sort of get the full capabilities of spring MVC in your actuator end points so you could do things like content negotiation within your actuator endpoints and to allow you to do that in Springwood - we've provided controller endpoint and rest controller endpoint but this is still at the expense of portability so once you start using these annotations for your custom actuators you will be tied to that particular web framework and other applications let's say over Jersey will not be able to use those endpoints so our hope is that the endpoint infrastructure that we've provided using the at endpoint annotation and the technology specific extensions that should work in most cases and you should only use this for if you want a way out or you want to do something special in your actuator or endpoints and I think with that that's all we've got for today yep thank you very much everyone thank you you

Channel: SpringDeveloper

Views: 32,130

Keywords: Web Development (Interest), spring, pivotal, Web Application (Industry) Web Application Framework (Software Genre), Java (Programming Language), Spring Framework, Software Developer (Project Role), Java (Software), Weblogic, IBM WebSphere Application Server (Software), IBM WebSphere (Software), WildFly (Software), JBoss (Venture Funded Company), cloud foundry, spring boot, spring cloud

Id: otcYECeFS6Y

Length: 65min 48sec (3948 seconds)

Published: Thu Oct 04 2018