Introduction
This document is intended to assist integrators with history collection in a Niagara station running on a JACE 8000. The mechanics of history collection, memory pools, history record size and history archiving will be discussed. Also covered are some good and bad practices relating to collecting histories.Managing Platform Resources
Memory Pools
The NRE memory allocations in a Niagara JACE 8000 can be manually adjusted by the user and these values greatly affect the operation of the system. Tridium has published a knowledge article that goes into detail about adjusting the different memory pools “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment”. Note that the RAM Disk is where the alarms and histories are stored while the operating system is running.
CPU
The cpu usage should be maintained below 80% on a JACE 8000. Periodic spikes above 80% are permissible but should not remain above 80% for an extended period. The current cpu usage can be viewed in the Resource Manager of the station.
Heap
The Java Runtime Environment uses a memory pool called heap for object allocation. The JRE automatically invokes garbage collection to clean up the heap of unreferenced objects. Heap should be maintained below 75% of heap.max. Heap.used and heap.max can be viewed in the Resource Manager.
File Descriptors
The JACE 8000 has a hard limit of 8000 file descriptors. The descriptors are consumed by any open file, device or network port on the platform. To reserve descriptors for the operating system and users logging into the station we recommend the number of histories not exceed 5000. The number of open file descriptors (fd.open) can be viewed in the Resource Manager. The file descriptor allocation can be viewed in spy:/platform diagnostics/pidin fds
Ram disk is a virtual disk drive where the history files are stored. On the JACE 8000 the RAM Disk is named ‘/mnt/aram0’. The total and free amount of file space can be viewed from the PlatformServices Filesystem property. Default RAM Disk size is 384MB. Note that increasing RAM Disk means reducing other memory pools. As noted earlier in this document, refer to “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment” for guidance on adjusting the memory pools.
When a history is first enabled, the station creates the history file on /mnt/aram0. The initial file includes a 1600-byte header (which defines the configuration parameters) and a single page file of 4096-byte size. When triggered by either the collection interval or change of value, a record is added to the page file. When the page file becomes full, additional page files are created based on the capacity configuration of the history.
Below is a table showing the history record size by the extension type:
The NRE memory allocations in a Niagara JACE 8000 can be manually adjusted by the user and these values greatly affect the operation of the system. Tridium has published a knowledge article that goes into detail about adjusting the different memory pools “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment”. Note that the RAM Disk is where the alarms and histories are stored while the operating system is running.
CPU
The cpu usage should be maintained below 80% on a JACE 8000. Periodic spikes above 80% are permissible but should not remain above 80% for an extended period. The current cpu usage can be viewed in the Resource Manager of the station.
Heap
The Java Runtime Environment uses a memory pool called heap for object allocation. The JRE automatically invokes garbage collection to clean up the heap of unreferenced objects. Heap should be maintained below 75% of heap.max. Heap.used and heap.max can be viewed in the Resource Manager.
File Descriptors
The JACE 8000 has a hard limit of 8000 file descriptors. The descriptors are consumed by any open file, device or network port on the platform. To reserve descriptors for the operating system and users logging into the station we recommend the number of histories not exceed 5000. The number of open file descriptors (fd.open) can be viewed in the Resource Manager. The file descriptor allocation can be viewed in spy:/platform diagnostics/pidin fds
History Size Calculation
Size on RAM DiskRam disk is a virtual disk drive where the history files are stored. On the JACE 8000 the RAM Disk is named ‘/mnt/aram0’. The total and free amount of file space can be viewed from the PlatformServices Filesystem property. Default RAM Disk size is 384MB. Note that increasing RAM Disk means reducing other memory pools. As noted earlier in this document, refer to “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment” for guidance on adjusting the memory pools.
When a history is first enabled, the station creates the history file on /mnt/aram0. The initial file includes a 1600-byte header (which defines the configuration parameters) and a single page file of 4096-byte size. When triggered by either the collection interval or change of value, a record is added to the page file. When the page file becomes full, additional page files are created based on the capacity configuration of the history.
Below is a table showing the history record size by the extension type:
| Point Type | bytes/record |
| boolean | 9 |
| enum and single precision numeric | 12 |
| double precision numeric | 16 |
| string | variable length between 64 and 192 |
|
Example calculations: Boolean: 15-minute intervals = 4 per hour x 24 hours = 96 per day x 365 days = 35,040 records per year x 9 = .3 MB per history extension Enum and single precision numeric: 15-minute intervals = 4 per hour x 24 hours = 96 per day x 365 days = 35,040 records per year x 12 = .42 MB per history extension Double precision numeric: 15-minute intervals = 4 per hour x 24 hours = 96 per day x 365 days = 35,040 records per year x 16 = .56 MB per history extension. (All numeric history extensions are set to single precision by default and can be set to double precision in the history extension configuration) |
Size on Flash
The history.zip file is on the flash and only accessed at startup and history save. The JACE 8000 also keeps a backup of the history.zip file. The size on flash will vary depending on the compression ratio of the history files.
The history.zip file is on the flash and only accessed at startup and history save. The JACE 8000 also keeps a backup of the history.zip file. The size on flash will vary depending on the compression ratio of the history files.
Best Practices
Archiving HistoriesDistributed control systems typically consist of small application specific controllers which communicate with area controllers. Area controllers typically have advanced functions like trending, alarming scheduling, etc. The JACE 8000 would be considered an area controller in the Niagara architecture.
Typically, multiple JACE 8000s communicate to the Niagara Web Supervisor product to aggregate collected histories and alarms. The supervisory control usually consists of scheduling, alarm and history archiving and graphics. History records should be recorded as close to the source as possible. Let’s discuss a system with a Supervisor and multiple JACE 8000s. Histories should be recorded at the JACE 8000 and archived to the Supervisor.
Good practice would be to keep several days of history records on the JACE 8000 and archive daily to the Supervisor. Implementing this type of architecture, the system is protected against data loss due to short term network outages.
The number of records to keep in the JACE 8000 for each history for several days can be calculated.
For example, if you are logging data in 15-minute intervals:
15 minutes = 4 history records per hour x 24 hours = 96 per day. 3 days of records would
require a capacity record count of 288 records.
Note that the "Capacity" property "Record Count" should not be set to "Unlimited" on a JACE 8000 due to limited storage space available.
The combination of the number of histories and their respective record count determine the size of the history database that is stored in the ram disk. There is a possibility that the RAM disk may become full. See the error below:
Things to Avoid
Ram Disk FullThe combination of the number of histories and their respective record count determine the size of the history database that is stored in the ram disk. There is a possibility that the RAM disk may become full. See the error below:
javax.baja.history.HistoryException at com.tridium.history.file.BFileHistoryTable.doFlush(BFileHistoryTable.java) at com.tridium.history.db.BHistoryDbTable.flush(BHistoryDbTable.java) at com.tridium.history.db.BHistoryDbTable.close(BHistoryDbTable.java) at com.tridium.history.db.BLocalHistoryDatabase.closeUnusedTables(BLocalHistoryDatabase.java) at javax.baja.history.BHistoryService.doCloseUnusedHistories(BHistoryService.java) at auto.javax_baja_history_BHistoryService.invoke(AutoGenerated) at com.tridium.sys.schema.ComponentSlotMap.invoke(ComponentSlotMap.java) at com.tridium.sys.engine.EngineUtil.doInvoke(EngineUtil.java) at javax.baja.sys.BComponent.doInvoke(BComponent.java) at javax.baja.util.Invocation.run(Invocation.java) at javax.baja.util.Worker.process(Worker.java) at javax.baja.history.BHistoryService$CloseUnusedHistoriesWorker.process(BHistoryService.java) at javax.baja.util.Worker$Processor.run(Worker.java) at java.lang.Thread.run(Unknown Source) Caused by: java.io.IOException: No space left on device at java.io.RandomAccessFile.writeBytes(Native Method) at java.io.RandomAccessFile.write(Unknown Source) at com.tridium.history.file.HistoryFileOutput.write(HistoryFileOutput.java) at com.tridium.history.file.fixed.Page.write(Page.java) at com.tridium.history.file.fixed.PageManager.writePage(PageManager.java) at com.tridium.history.file.fixed.PageManager.flush(PageManager.java) at com.tridium.history.file.fixed.BFixedLengthHistoryTable.flushData(BFixedLengthHistoryTable.java)
Note the message: "java.io.IOException: No space left on device"
You can increase the size of the Ram Disk as described in the knowledge article “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment". You can also decrease the number of records being recorded by changing the capacity record count or reduce the number of histories being colllected. The database maintenance tool must be run to remove the old records in order to clear up disk space.
Numeric Cov
The frequency of history record collection for a NumericCov history extension can be limited by setting the “Change Tolerance” property. Note that leaving this at the default of “0.00” can cause nuisance records to be recorded with very minute changes in the output of the numeric point.
You can increase the size of the Ram Disk as described in the knowledge article “Adjusting NRE memory pools on N4 Jace Niagara Runtime Environment". You can also decrease the number of records being recorded by changing the capacity record count or reduce the number of histories being colllected. The database maintenance tool must be run to remove the old records in order to clear up disk space.
Numeric Cov
The frequency of history record collection for a NumericCov history extension can be limited by setting the “Change Tolerance” property. Note that leaving this at the default of “0.00” can cause nuisance records to be recorded with very minute changes in the output of the numeric point.
Potential Problems and Mitigation
File IOFile IO is the operation of accessing files. The station uses File IO to open a history in the running station. If all the history collections get queued up on a single engine cycle it can contribute significantly to the engine cycle time. There are a couple of ways to ease the effects of collecting history records on the engine.
Engine Watchdog Timeout
An engine watchdog timeout will occur if the engine cycle is longer than the Engine Watchdog Timeout setting in the Platform Services Container Plugin property sheet. The default setting is 3 minutes. Increasing the Engine Watchdog timeout needs to be done with caution. The engine watchdog is a platform daemon process, to which the station periodically reports its updated engine cycle count. The watchdog purpose is to detect and deal with a “hung” or “stalled” station, and is automatically enabled when the station starts. Setting the timeout too high can result in undesirable performance.
Staggering Collections
Staggering history collections can ease the effects on the engine cycle times by spreading the collections so they don’t all execute on the same engine cycle. Collections can be staggered by adjusting the “Active Period Time Range” start and end times. Set the start and end times of your histories a minute or more apart. The default Time Range is 12:00:00 AM to 12:00:00 AM.
Staggering history collections can ease the effects on the engine cycle times by spreading the collections so they don’t all execute on the same engine cycle. Collections can be staggered by adjusting the “Active Period Time Range” start and end times. Set the start and end times of your histories a minute or more apart. The default Time Range is 12:00:00 AM to 12:00:00 AM.
History Linger Time
There is a line that can be added to the system.properties file that will increase the time that a history file will remain open after it has been read or written. This will ease the effect of file IO on the engine cycle. The File Transfer Client that is available in the platform of the JACE must be used to copy the file to your local pc running Workbench. Open the file in Workbench using the text editor view. Add a new line at the end of the file: niagara.history.localDb.lingerTime=xxxxx (where xxxxx is the time in milliseconds, the default is 300000 which is 5 minutes). Save the file. The file must be copied back to the JACE using the File Transfer Client. The station must be restarted, the system.properties file is read on station startup.
Summary
Hopefully this document has helped improve the integrator’s understanding of history collection and archiving in the Niagara architecture. Managing platform resources such as heap and cpu usage will improve the JACE-8000 performance and stability. Calculating the appropriate amount of histories needed to be maintained on the JACE-8000 while archiving to the Niagara Web Supervisor will help maintain history collection without data loss due to intermittent network outages.
There is a line that can be added to the system.properties file that will increase the time that a history file will remain open after it has been read or written. This will ease the effect of file IO on the engine cycle. The File Transfer Client that is available in the platform of the JACE must be used to copy the file to your local pc running Workbench. Open the file in Workbench using the text editor view. Add a new line at the end of the file: niagara.history.localDb.lingerTime=xxxxx (where xxxxx is the time in milliseconds, the default is 300000 which is 5 minutes). Save the file. The file must be copied back to the JACE using the File Transfer Client. The station must be restarted, the system.properties file is read on station startup.
Summary
Hopefully this document has helped improve the integrator’s understanding of history collection and archiving in the Niagara architecture. Managing platform resources such as heap and cpu usage will improve the JACE-8000 performance and stability. Calculating the appropriate amount of histories needed to be maintained on the JACE-8000 while archiving to the Niagara Web Supervisor will help maintain history collection without data loss due to intermittent network outages.