How to Manage Memory Allocations for a Niagara 4 Web Supervisor

Check Heap Max in the station's Resource Manager, then raise the -Xmx value in station.java.options in nre.properties and restart the station.

A Niagara station runs inside a Java virtual machine with a fixed maximum amount of memory, its heap. The default suits most stations, but a large Web Supervisor importing histories from dozens of controllers, serving graphics to many users and running analytics can outgrow it. When that happens the station slows down, stops responding or restarts. Workbench has the same limit and can crash when you work on several large stations. This guide explains how to check memory use, how to increase the allocation for a station and for Workbench, and how to size it safely.

Signs a station needs more memory

• the station becomes slow or unresponsive under load, then recovers
• the station restarts unexpectedly, with out-of-memory errors in the application director output
• the Resource Manager shows heap use close to Heap Max most of the time
• performance degrades as more controllers, histories or users are added
• Workbench closes unexpectedly when several large stations are open

How to check memory use

1. Connect to the station in Workbench.
2. Right-click the station and choose Views > Resource Manager.
3. Look at Heap Max (the maximum the station may use) and the heap used figures.

A station whose used heap regularly sits near Heap Max needs attention. Some fluctuation is normal: Java frees memory in cycles (garbage collection), so heap use rises and falls. Look at the peaks and the baseline after collection, not a single reading.

Note that Heap Max is shown slightly below the configured value. A station configured for 1,024 MB typically reports around 910 MB as Heap Max. That is normal.

How to increase a station's memory (Windows supervisor)

The station's Java options are set in the nre.properties file for the Niagara installation.

Step 1: Find nre.properties

1. On the supervisor PC, open the ProgramData folder (for example C:\ProgramData). It is hidden by default; enable Show hidden items in File Explorer.
2. Open the folder for your Niagara version, for example Niagara4.13, then the brand folder (for example tridium, vykon or another OEM brand).
3. Open the etc folder and find nre.properties.

If several Niagara versions are installed, make sure you edit the file for the version the station runs on.

Step 2: Edit station.java.options

1. Open nre.properties in a text editor such as Notepad++. You need administrator rights to save it.
2. Find the station.java.options entry. It contains Java options including -Xmx, the maximum heap size, for example -Xmx1024M or -Xmx1g.
3. Increase the value, for example to -Xmx2048M (2 GB) or -Xmx4g (4 GB), according to the station's needs and the server's memory.
4. Save the file. If administrator rights are required, Notepad++ offers to relaunch with elevated permissions.

Newer Niagara versions include comments in nre.properties explaining each setting. Change only the -Xmx value unless you know exactly why another option needs changing.

Step 3: Restart and verify

1. Restart the station from the Application Director (platform connection) or restart the Niagara service.
2. Open the Resource Manager again and confirm Heap Max reflects the new allocation.

How to increase Workbench memory

Workbench uses the wb.java.options entry in the same nre.properties file. If Workbench crashes or becomes sluggish when you work across multiple complex stations, raise its -Xmx value in the same way, then restart Workbench.

How much memory should you allocate?

These are starting points. Increase in steps, monitor the Resource Manager under real load, and stop when there is comfortable headroom.

Leave memory for everything else

The heap is not the only memory a station uses. Java needs memory outside the heap, Windows needs memory, and other services (SQL databases, antivirus, backups) run on the same server. As a rule of thumb:

• do not allocate more heap than the host can safely support
• keep at least several gigabytes free for the operating system and other processes
• if you run several stations on one server, the total of all their heaps must fit

Allocating too much heap can make performance worse: the server starts paging to disk, and long garbage collection pauses make the station stutter.

Controllers: JACE and IONA

Embedded controllers have fixed physical memory, and their station memory is managed by the platform. You cannot simply raise -Xmx on a JACE the way you can on a server. If a controller's station is running short of memory:

• remove unused points, histories and alarm extensions
• archive histories to a supervisor instead of storing them locally
• simplify large graphics or serve them from the supervisor
• split the integration across more controllers
• consider more powerful hardware, such as a JACE 9000 (2 GB RAM) in place of a JACE 8000

Worked example: a growing supervisor

A Web Supervisor started with 8 JACEs and the default 1 GB heap. Two years later it supervises 35 controllers, imports histories from all of them every 15 minutes, runs analytics and serves graphics to 20 regular users. Operators report the supervisor freezing for several seconds at a time, and the Resource Manager shows heap use hitting Heap Max every few minutes.

The server has 16 GB of RAM and runs nothing else except Windows and antivirus.

Actions:

1. heap raised from 1 GB to 4 GB in station.java.options
2. history capacities reviewed and long-term archive moved to a SQL database
3. three Px pages with hundreds of bindings split into smaller pages
4. station restarted out of hours and the Resource Manager monitored for a week

Result: heap use settles around 2–2.5 GB with peaks well below the new Heap Max, freezes stop, and graphics load faster. The server still has ample free memory for Windows.

Garbage collection in plain English

Java programs, including Niagara stations, create objects in the heap as they work and periodically clean up the ones no longer needed. This clean-up is garbage collection. It explains several things you see in the Resource Manager:

• heap use rises steadily, then drops sharply: that is a collection freeing memory
• a station with too little heap collects very often, using CPU and causing brief pauses
• a station near its limit may spend so much time collecting that it becomes unresponsive, and may finally fail with an out-of-memory error
• a healthy station's heap after collection stays well below Heap Max

So when judging whether a station needs more memory, look at the low points after collections over a day, not the momentary peaks. A rising baseline over days suggests growth in the station or a memory leak.

Linux supervisors and virtual machines

Supervisors increasingly run on Linux or on virtual machines. The principles are the same:

• the station's maximum heap is still set through the Java options for the station in the Niagara installation's configuration (nre.properties for your version and brand)
• on a virtual machine, the guest's memory allocation is the ceiling: increasing the station heap without increasing the VM's memory just moves the problem to the operating system
• avoid memory overcommitment on the hypervisor for supervisor VMs; if the host reclaims memory from the guest under pressure, the station suffers long pauses
• give the VM enough CPU as well: garbage collection on a large heap needs processing time, and a starved VM will pause more

Agree memory and CPU reservations with the IT team that runs the virtual infrastructure, and document them alongside the station's heap setting.

Before and after any change

A simple routine keeps memory changes safe:

1. Record the current -Xmx value, Heap Max and typical heap used.
2. Back up nre.properties (copy it with a date in the name) and the station.
3. Change one thing at a time.
4. Restart in a quiet period and confirm the station starts and drivers come up.
5. Monitor for a few days under normal load.
6. Document the change and the reason in the site log.

If the station fails to start after a change, restore the backed-up nre.properties and restart. The most common cause is a typing error in the Java options line.

Monitoring memory over time

Memory problems tend to creep up as systems grow, so monitor rather than react:

• record heap used as a station point and trend it, if your version exposes it, or check the Resource Manager at each maintenance visit
• note station restarts in the application director log; unexpected restarts are a warning sign
• review memory whenever you add controllers, large history imports, analytics or many new users
• keep the server's own memory and disk usage under review with standard IT monitoring

Reducing memory use instead

Before adding memory, check whether the station is using more than it should:

• histories: very large numbers of histories, or histories with excessive capacity, consume memory; archive to a database or reduce capacities
• alarm database: thousands of unacknowledged alarms grow the database; clean up nuisance alarms
• graphics: huge Px pages with hundreds of bindings use memory per user; split them
• unused modules and services: remove what the station does not use
• memory leaks: a station whose memory use climbs steadily until restart may have a faulty third-party module; check with the vendor and update

Frequently asked questions

How do I increase memory for a Niagara 4 station?

Edit station.java.options in the nre.properties file under ProgramData for your Niagara version and brand, raise the -Xmx value, save, and restart the station.

Where do I see how much memory a Niagara station uses?

In the station's Resource Manager view (right-click the station, Views, Resource Manager), which shows Heap Max and heap used.

Why does Heap Max show less than the -Xmx value?

Java reports usable heap slightly below the configured maximum. About 910 MB for a 1,024 MB setting is normal.

How do I stop Workbench running out of memory?

Raise the -Xmx value in wb.java.options in nre.properties and restart Workbench.

Can I give a station all the server's memory?

No. Leave memory for the operating system, Java's non-heap memory and other services, or performance will suffer.

Where is nre.properties?

On Windows, under the hidden ProgramData folder, in the folder for your Niagara version and brand, inside etc. For example C:\ProgramData\Niagara4.13<brand>\etc\nre.properties.

Does each Niagara version have its own nre.properties?

Yes. If several versions are installed, edit the file belonging to the version the station runs on.

Do I need to restart after changing -Xmx?

Yes. The new heap size applies when the station (or Workbench) next starts.

What does -Xmx mean?

It is the Java option that sets the maximum heap memory, for example -Xmx2048M or -Xmx2g for 2 GB.

Can I increase memory on a JACE?

Not in the same way. Reduce the station's memory use, archive histories to a supervisor, or move to more powerful hardware such as the JACE 9000.

How much RAM should a Niagara supervisor server have?

Enough for the station heap, Java's non-heap memory, the operating system and any other services on the server, plus headroom. A server running a 4 GB station heap typically needs considerably more than 4 GB of RAM in total.

Can too much heap be harmful?

Yes. If the heap is too large for the host, the server pages to disk and garbage collection pauses get longer. Allocate what the station needs plus headroom.

Need help from a Niagara engineer?

If this guide has not solved the problem, contact the Tyrrell Products technical team on 01942 732819 or [email protected]. Tell us the controller or host type, its Niagara version and what you have already tried, and we will help you get the system running.

Related guides

• Global Capacity points and the Resource Manager
• Niagara Workbench versions
• How to find a PC's Host ID
• Advanced engineering video guides