boot.properties – 5 hints for Logscape Environments

A Logscape Agents is incredibly powerful: it might be a Forwarder shipping data or an IndexStore receiving it. It might even be a Management Agent providing the web front end. Regardless of what it may become, they all start from the boot.properties file. This small, innocuous looking file sitting in the Logscape folder is what makes the difference between a powerful, resource consuming Manager and a small, lightweight forwarder. Here are 5 useful tips for dealing with this file.

1. Consider Zones and Application Deployments in your role

When you install a Logscape agent, you are asked to give it a role: examples provided are dev.Management or dev.Forwarder. When you’re starting out the first time, you’ll probably just accept these to get going – that’s fine! However, when you start to scale up your deployment, you’ll need to pay more attention because the role controls the Zones the agent is a part of.

XKCD Comic - A man spends hours picking a server name but seconds choosing his daughter's name. Names are important! And your boot.properties controls the name

Naming conventions are important!

Zones allow you to determine the data segregation: for example you might want data from Europe to remain in the Europe zone. Therefore you might wish to change it’s role to: dev.europe.Forwarder.

How do you do that? Simply open the boot.properties file, search for -Dagent.role= and amend the role. Save the file, restart the process and like magic, your Agent has changed it’s zone.

In our previous example, we selected dev.europe.Forwarder. If we wanted to deploy an App to all European machines, we now could do so. However, what if I only want to deploy a certain App to a group of servers? Well, when creating Resource Groups as described here, I could use hostnames… but it’s much easier if I set my role to something more descriptive. For example: dev.europe.london.applicationserver.Forwarder

If I use this naming convention for all my agents, I can easily deploy by continent, city or server type – providing a much more flexible deployment. Again, just edit the boot.properties to change the role.

2. Centrally Deploy your boot.properties

So far, you’ve been editing the local copy of the boot.properties file. This means that if you want to make a change, you simply log on to the server, amend the boot.properties and then restart. In an enterprise Logscape deployment, the Logscape Administrator may not have permissions to access every machine, especially if those servers cross departments or countries. So what do you do when you need to amend those properties?

Simply put, you centrally deploy them. Let’s go with our earlier example of dev.europe.Forwarder. Every time the agent starts, it looks in the downloads folder for a file named dev.europe.Forwarder.boot.properties – and if that file exists then it uses it. Therefore, if you ensure you have a boot.properties file for each role deployed in your environment, you can control them centrally. That makes it much easier to retain control of your environment.

You may of course have realised, that the more roles you have, the more boot.properties files you’ll need to deploy and maintain. I’m afraid that is just a balance you need to maintain as an Administrator. Do you have more roles to increase flexibility or fewer to ease maintainability? The deciding factor will probably be your environment size. However, I have created a nifty tool that will allow you to make quick copies for each role, meaning you can generate them from a standard template.

Advanced Use: The agent will first check the local boot.properties to find the role – then check to see if a corresponding copy exists in the downloads folder. However, once the name of the replacement file matches the original role, the agent will then use the replacement file… even if that has a different role!

Remember – If a new version of Logscape comes out, you may need to upgrade the boot.properties file!

3. JVM Arguments

The first few lines of the boot.properties file are dedicated to the Java Virtual Machine arguments. You can tell because they start with vmargs=  and there are a couple of things you need to be aware of here.

  • -Xms / -Xmx :These control the initial and max sizes of your JVM memory heap. If this is agent is meant to be a Forwarder, you’ll want these to be quite small – which is the default. If you plan to use this machine as a Manager or IndexStore, they’ll need far more resources. Check the sizing guide for more information.
  • -XX:+HeapDumpOnOutOfMemoryError : If this is present, then when the Agent runs out of memory, it will dump a HPROF file. These can be rather large in size, especially in a larger machine. If you want to leave the ability to capture the memory state (for debug purposes for example) then leave this line. If you cannot afford to risk the disk space being taken up by this (for example, on a Production Critical server), remove this from the line.

4. Sysprops Arguments

Below the JVM arguments comes the sysprops= line, which is documented here. I just want to highlight a few that affect enterprise deployments – some of these are new for the 3.11 release!

  • -Dnet.iface=ethX This isn’t in position by default, but can be important if you add a server with multiple network cards. If Logscape has selected the incorrect NIC, then you can use this to force Logscape to use a different adaptor. To find out which ethX you need – use the NetworkList.bat in the scripts directory.
  • -Duser.timezone=EST Commented out by default, this allows you to force a machine to appear from a certain timezone. You may find that your infrastructure team have set time zones to suit the application rather than reflect the true time.
  • -Ddashboard.heap=512M  -Dlogspace.heap=512M -Daggspace.heap=512M Only required on a Manager, this allocates memory for the subsidiary processes the Manager runs. If you don’t allocate this memory, your performance will grind to a halt.
  • -Djava.io.tempdir=work/tmp The location of Logscape temporary files. This is a new feature, allowing you to control where your searches are cached for performance. This folder is now cleaned out every time Logscape restarts, ensuring your disk footprint remains small.

5. Set your Priority

The final setting in the boot.properties file is #priority=LOW. Since this is commented out, it will not affect the Agent and the process will run as normal priority. However, if you are running an Enterprise environment, it’s highly likely that your applications are more important to the business than the monitoring solution. Therefore, remove the # if the boot.properties applies to a Forwarder and it will be given a lower priority by the machine. Your monitoring may suffer slightly at peak times, but at least you won’t interfere with business processes.

As always, there is always more to talk about, but hopefully that has given you some useful information for dealing with boot.properties files. Let us know how you found it!