From Alteeve Wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

 AN!Wiki :: How To :: ScanCore

Warning: This is little more that raw notes, do not consider anything here to be valid or accurate at this time.

ScanCore - The Decision Engine

ScanCore is, at its core, a "decision engine".

It was created as a way for Anvil! systems to make intelligent decisions based on data coming in from any number of places. It generates alerts for admins, so in this regard it is an alert and monitoring solution, but that is almost a secondary benefit.

The core of ScanCore has no way of gathering data and it doesn't care how data is collected. It walks through a special agents directory and any agent it finds in there, it runs. Each agent connects to any number of ScanCore databases, checks whatever it knows how to scan, compares the current data with static limits and compares against historic values (as it deems fit) and records data (new or changed values) into the database.

An agent may decide to take independent action, like sending an alert or attempting a recovery of the devices or software it monitors, and then exits. If an agent doesn't find any hardware or software it knows about, it immediately exits without doing anything further.

After all agents run, ScanCore runs through post-scan tasks, depending on whether the machine it is running on is an Anvil! node or a ScanCore database. This is where the "decision engine" comes into play.

Lets look at a couple of examples;

Example 1; Overheating

ScanCore can tell the difference between a local node overheating and the room it is in overheating.

If the node itself has overheated, it will migrate servers over to the healthy peer. If the enough temperature sensors go critical, the node will power off.

If, however, both nodes are overheating then ScanCore can deduce that the room is overheating. In this case, it can automatically shed load to reduce the amount of heat being pumped into the room and slow down the rate of heating. Later, when the room cools, it will automatically reboot the shedded node and reform the Anvil! pair, restoring redundancy without ever requiring a human's input.

How does it do this?

Multiple scan agents record thermal data. The scan-ipmitool tool checks the host's IPMI sensor data which includes many thermal sensors and their upper and lower warning and critical thresholds. The scan-storcli agent scan AVAGO-based RAID controllers and the attached hard drives and solid state drives. These also have thermal data. This is true also for many UPSes, ethernet switches and so forth.

As each agent checks its thermal sensors, any within nominal ranges are recorded by the agent in its database tables. Any that are in a warning state though, that is, overly warm or cool but not yet a problem, get pushed into a special 'temperature' database table. Alone, ScanCore does nothing more than mark the node's health as 'warning' and no further action is taken.

If a given agent finds a given sensor reaching a 'critical' state, that is hot enough or cold enough to be a real concern, it it also pushed into the 'temperature' table. At the end of the scan, ScanCore will "add up" the number of sensors that are critical.

If the sum of the sensors exceed a limit, and if the host is a node, ScanCore will take action by shutting down. Each sensor has a default weight of '1' and by default, the shutdown threshold is "greater than five". So by default, a node will shut down when 6 or more sensors go critical. This is entirely configurable on a per-sensor basis as well as the shutdown threshold.

Later, when the still-accessible temperature sensors return to an acceptable level, ScanCore running on any one of the dashboards will power the node back up. Note that ScanCore will check how many times a node has overheated recently and extend a "cool-down" period before rebooting a node. This way, a node with a chronic overheating condition will be rebooted less often. Once repaired though, the reboots will eventually be "forgotten" and the cool-down delay will reset.

What about thermal load shedding?

The example above spoke to a single node overheating. If you recall, ScanCore does "post-scan calculations". When on a node, this includes a check to see if the peer's temperature has entered a "warning" state when it has as well. Using a similar heuristic, when both nodes have enough temperature sensors in 'warning' or 'critical' state for more than a set period of time, one of the nodes will be withdrawn and shut down.

Unlike the example above, which shutdown the host node after a critical heuristic is passed, the load-shedding kicks in only when both nodes are registering a thermal event at the same time for more than a set (and configurable) period of time.

Example 2; Loss of input power

In all Anvil! systems, at least two network-monitored UPSes are powering the nodes' redundant power supplies. Thus, the loss of one UPS does not pose a risk to the system and can be ignored. Traditionally, most UPS monitoring software would assume it was the sole power provider for a machine and would initiate a shutdown if it reached critically low power levels.

With ScanCore, it understands that each node has two (or more) power sources. If one UPS loses mains power, an alert will be registered but nothing more will be done. Should the one UPS deplete entirely, the power will be lost and additional alerts will be registered when input power is lost to one of the redundant power supplies, but otherwise nothing more will happen.

Thus, ScanCore is redundancy-aware.

Consider another power scenario; Power is lost the both UPSes feeding a node. In this case, ScanCore does two things;

  1. It begins monitoring the estimated hold-up time of the strongest UPS. If the strongest UPS drops below a minimum hold-up time, a graceful shutdown of hosted servers is initiated followed by the node(s) withdrawing and powering off. Note that if different UPSes power the nodes, ScanCore will know that the peer is healthy and will migrate servers to the node with power long before the node needs to shutdown.

In a typical install, the same pair of UPSes power both nodes in the Anvil!. In the case where power is lost to both UPSes, a timer is checked. Once both nodes have been running on UPS batteries for more than two minutes, load shedding will occur. If needed, servers will migrate to consolidate on one node, then the sacrificial node will withdraw and power off to extend the runtime of the remaining node.

If, after load shedding, power stays out for too long and minimum hold-up times are crossed, the remaining node will gracefully shut down the servers and then power itself off.

Later, power is restored.

At this point, the Striker dashboards will boot (if all power was lost). Once up, they will note that both nodes are off and check the UPSes. If both UPSes are depleted (or minimally charged), they will take no action. Instead, they will monitor the charge rate of the UPSes. Once one of the UPSes hits a minimum charge percentage, it will boot the nodes and restore full Anvil! services, including booting all servers.

The logic behind the delay is to ensure that, if mains power is lost immediately after powering the nodes back on, there is sufficient charge for the nodes to power back up, detect the loss and shut back down safely.

Example 3; Node Health

The final example will show how ScanCore can react to a localized node issue.

Consider the scenario where Node 1 is the active host. The RAID controller on the host reports that a hard drive is potentially failing. An alert is generated but no further action is taken.

Later, a drive fails entirely and the node enters a degraded state.

At this point, ScanCore would note that Node 1 is now in a 'warning' state and the peer node is 'ok' and a timer is started. Recall that ScanCore can't determine the nature of a warning, so it pauses a little bit to avoid taking action on a transient issue. Two minutes after the failure, with the 'warning' state still present, ScanCore will migrate all hosted servers over to Node 2.

It will remain in the Anvil! and no further action will be taken. However, now, if a second drive were to fail (assuming RAID level 5), Node 1 would be lost and fenced, but no interruption would occur because the servers were already moved as a precaution.

If the drive is replaced before any further issues arise, Node 1 would return to an 'ok' state but nothing else would happen. Servers would be left on Node 2 because there is no benefit or concern around which node is hosting the servers at any given time.

Scan Agents

When an agent runs and connects to the database layer, a timestamp is created and that time stamp is then used for all databases changes made in that given pass. This means that the modification timestamps will be the same for a given pass, regardless of the actual time when the record was changed. This makes resynchronization far more sane, at the cost of some resolution.

If your agent needs accurate record change timestamps, please make a note to record that current time as a separate database column.

DB Resync

Part of the difference between ScanCore and various other tools is that ScanCore is designed from its core as a resilient project. The data collected by agents needs to, from the user's perspective, sync N-way between ScanCore databases without the user needing to worry about backups, recoveries and whatnot.

How does this work?

In essence, the data Agents collects can be categorized in one of two ways;

  • Data that is global (like data on servers on the Anvil! platform)
  • Data that is target-bound (like a host's sensor data from IPMI interfaces or a given machines view of UPSes it cares about)

As an agent author, you need to consider that data may exist in some databases and not others.


A site has two Striker dashboards acting as ScanCore databases. This is a satellite office so you data replicates to a third Striker at head office. Meanwhile, head-office is collecting data from many different sites and the two dashboards on your site doesn't care about the data on the head-office site from those other locations.

Warning: Isolating data onto a limited number of databases is an efficiency effort, not a security effort! If you don't trust a ScanCore database machine, don't connect to it, period. Similarly, if you don't trust trust a machine with access to your database, don't give the owner access.

You also need to plan for N-directional resynchronization.

Also consider;

Power is lost to both/all UPSes and load-shedding takes "Striker 2" offline. Now data is being recorded to "Striker 1" that will need to be copied to Striker 2 later. Time passes and all power is lost. Power is restored, but for some reason Striker 2 boots up first and starts collecting data. Eventually, Striker 1 comes back online.

Now, Striker 1 has data that 2 doesn't, and Striker 2 has data that 1 doesn't.

ScanCore has already solved this problem using the following schemes, depending on which type of data your agent collects.

Note: Yes, this is expensive in terms of memory and processing power, relatively speaking. However, a lot of effort is made to never UPDATE the database unless something actually changes, keeping the history schema as small and efficient as possible. For this reason, even data collected from many nodes over a long period of time should not add up to too much. If you are concerned, be sure to run periodic archiving of the data.
Warning: As this is written, automatic archiving has not been implemented, though it is planned to be implemented shortly.

Resync Global Data

This is the simplest data to resync because it will go to all databases, no matter what. This is rare in practice but provides a good starting point.

The process;

The agent starts and connects to the databases. As part of the connection process, a check is made to see if any databases are behind (see>find_behind_databases()). If so, the agent will act on this by initiating a resync.

The resync process is fundamentally simple; All records are read in from it's history schema of all connected databases into a common hash based on the time a given record was recorded and the unique ID of the record. The same data is loaded into database-specific hash for later comparison. We also note for each unique record that we've seen at least one copy of the record for a later step. An example "record" would be a server's UUID, which uniquely identifies it regardless of the host node or Anvil!.

Here is an example of how the data is read in:

		my $query = "

Without constraints, all data in the table will be read in. This data is recorded in the 'unified' hash using the modification time and the unique identifier as keys.

			# Record this in the unified and local hashes.
			$an->data->{db_data}{unified}{servers}{modified_date}{$modified_date}{server_uuid}{$server_uuid} = {
				server_name			=>	$server_name, 
				server_stop_reason		=>	$server_stop_reason, 
				server_start_after		=>	$server_start_after, 
				server_start_delay		=>	$server_start_delay, 
				server_note			=>	$server_note, 
				server_definition		=>	$server_definition, 
				server_host			=>	$server_host, 
				server_state			=>	$server_state, 
				server_migration_type		=>	$server_migration_type,
				server_pre_migration_script	=>	$server_pre_migration_script,
				server_pre_migration_arguments	=>	$server_pre_migration_arguments,
				server_post_migration_script	=>	$server_post_migration_script,
				server_post_migration_arguments	=>	$server_post_migration_arguments,

Next, for the current Database ID that we're reading from, note that the server with the given ID exists in the public database schema. We'll also set this 'seen' as '0' for now. We'll see why in a moment.

			$an->data->{db_data}{$id}{servers}{server_uuid}{$server_uuid}{'exists'} = 1;
			$an->data->{db_data}{$id}{servers}{server_uuid}{$server_uuid}{seen}     = 0;

Finally, record the same data in another hash, identified by the currently active database ID in another hash.

			$an->data->{db_data}{$id}{servers}{modified_date}{$modified_date}{server_uuid}{$server_uuid} = {
				server_name			=>	$server_name, 
				server_stop_reason		=>	$server_stop_reason, 
				server_start_after		=>	$server_start_after, 
				server_start_delay		=>	$server_start_delay, 
				server_note			=>	$server_note, 
				server_definition		=>	$server_definition, 
				server_host			=>	$server_host, 
				server_state			=>	$server_state, 
				server_migration_type		=>	$server_migration_type,
				server_pre_migration_script	=>	$server_pre_migration_script,
				server_pre_migration_arguments	=>	$server_pre_migration_arguments,
				server_post_migration_script	=>	$server_post_migration_script,
				server_post_migration_arguments	=>	$server_post_migration_arguments,

So, once the read is done from all accessible databases, we'll have a set of hashes; One being the unified collection of all data from both/all sources, plus a hash for each database.

Note: This looks a little complicated, but it is worth the mental effort. With this in place, users will never need to worry about data recovery or synchronization so long as even one copy of the database exists somewhere. ScanCore database servers can come and go or be destroyed and replaced trivially. So please bear with it... The logic seems complex, but it is fundamentally quite simple.

With this, here is the sync process:

  1. Walk through the unified records for each given modification timestamp, newest records first, oldest records last.
    1. Walk through each unique record for the given timestamp (continuing the example, this would be each server's UUID).
      1. Loop through each connected database ID.
        1. Check to see if the unique record ID has been seen in the resync process yet. (Note: This will always be 'not' the first time because the first instance of a record at the most recent time stamp will go into the public schema where all other records will go into the history schema.)
          1. IF NOT seen:
            1. Mark the record as now having been seen.
            2. Check to see if the unique record ID exists at all on this database.
              1. IF exists: Does the record at the current time stamp exist?
                1. IF NOT at this timestamp: UPDATE the public schema (the record was already in the public schema, but it was old).
              2. IF NOT exists: INSERT it into the public schema as the record didn't exist yet.
          2. IF seen:
            1. Does it exist at this timestamp?
              1. If not at this timestamp: INSERT it into the history schema at the current timestamp.

All of these UPDATE and INSERT calls go into an array per database. When all the unified records have been processed, each database array with one or more records is then sent to the given database to be processed in one transaction.

Lastly, the hashes that stored all the unified and per-DB records is deleted to clear up memory.

Voila! Your data is now synchronized on all databases!

Resync Target-Bound Data

The only difference between resync'ing global data from target-bound records in that a constraint is used on the initial reading of data from the connected databases.

We will use scan-bond agent which monitors bonded network interfaces on each node or Striker dashboard. In all cases, the state of the bonds only matters to the one host with the actual bonds. The other nodes and dashboards don't care about it.

In this example, then, the bond records will be bound to the hosts -> host_uuid, which is stored on each machine in /etc/striker/host.uuid and is presented in ScanCore in the sys::host_uuid variable.

The read, then, looks like this;

		my $query = "
    bond_host_uuid = ".$an->data->{sys}{use_db_fh}->quote($an->data->{sys}{host_uuid})."

With the WHERE bond_host_uuid = ".$an->data->{sys}{use_db_fh}->quote($an->data->{sys}{host_uuid})." constraint, all of the data read in from the database will come from the current host machine. Bond records for other nodes and dashboard systems will be ignored.

In this way, our data will sync between the ScanCore databases we use, but we won't sync bond records for other hosts (which may sync between an entirely different set of ScanCore databases).

The rest of the synchronization is process is exactly the same as above. The unified and per-DB hashes will be processed exactly the same way (just with a subset of the data).

Easy peasy!

Unit Parsing

One of the tricker bits of magic that ScanCore pulls off is the ability to simultaneously deliver alerts to different recipients in different languages. This is tricky because the agents setting alerts don't process the messages. So we need a standard way to pass values in an alert to ScanCore in a translatable format.

This is done via the special 'alerts' table.

Note: Explain this...

When setting a string to be later translated using double-bang variables line '!!$variable!$value!!', the '$value' will be analysed for certain suffixes. Those suffixes, when found, are translates into the language, unit or human readable appropriate values. For example, '!!size!1024 bytes!!' will be translated to the language-appropriate base-2 human readable size, '1 KiB'.

Similarly, temperatures can also be unit-converted for the notification target. So a value like '#!core_temperature!30 C!!' can be translated to '30°C' or, for users preferring imperial measurements, '68°F'.

The full list of translated special suffixes are:

Note: The 'suffix' strings are case sensitive! If you want your agent's alerts to use these translation, please mind the case and spelling. This is strict to minimise the chance of accidentally formatting a string not meant to be translated by this feature.
Suffix String Key Note
% tools_suffix_0016 Percentage
W tools_suffix_0017 Watts
vDC tools_suffix_0018 Volts DC
vAC tools_suffix_0019 Volts AC
A tools_suffix_0020 Amperes
RPM tools_suffix_0021 Rotations Per Minute
Bps tools_suffix_0022 Bits per second
Kbps tools_suffix_0023 Kilobits per second
Mbps tools_suffix_0024 Megabits per second
Gbps tools_suffix_0025 Gigabits per second
Tbps tools_suffix_0026 Terabits per second
Bytes --
Note: Only whole byte values are supported. Fractional byte values will not be converted.

These will be translated to the Base-2 human readable size via the 'AN::Tools::Readable->bytes_to_hr()' method. The suffix returned are those accepted by the ISQ for base-2 short forms. The sizes returned are; KiB, MiB, GiB, TiB, PiB, EiB, ZiB and YiB. KiB is rounded to one decimal place, MiB through TiB are rounded to two decimal places and PiB through YiB are rounded to three decimal places.

sec tools_suffix_0027


Note: Only whole seconds are supported. Fractional values will not be converted.

The number of seconds given will be returned as a human-readable period of time in the short format '#w, #d, #h, #m, #s' via the 'AN::Tools::Readable->time()' method. If the number of seconds is too short for a number of minutes, hours, days or weeks, those units will be omitted.

seconds tools_suffix_0032


Note: Only whole seconds are supported. Fractional values will not be converted.

The number of seconds given will be returned as a human-readable period of time in the long format '# Weeks, # Days, # Hours, # Minutes, # Seconds' via the 'AN::Tools::Readable->time()' method. If the number of seconds is too short for a number of minutes, hours, days or weeks, those units will be omitted.

Second tools_suffix_0037 Singular "Second".
Seconds tools_suffix_0038
Note: Note that this has a capitalised 'S'.

Plural "Seconds".

Minute tools_suffix_0039 Singular "Minute"
Minutes tools_suffix_0040 Plural "Minutes"
Hour tools_suffix_0041 Singular "Hour".
Hours tools_suffix_0042 Plural "Hours".
Day tools_suffix_0043 Singular "Day".
Days tools_suffix_0044 Plural "Days".
Week tools_suffix_0045 Singular "Week".
Weeks tools_suffix_0046 Plural "Weeks".
C tools_suffix_0010


The value is in celsius. Which string is returned will depend on the notification target's preference for metric or imperial units of measurement. If metric (the default), tools_suffix_0010 is appended to the value and returned. If imperial, the value is converted to fahrenheit and the suffix tools_suffix_0012 will be appended.

In some cases, the value returned by a string is a simple string in a given language (usually English). To translate this, certain values will be translated based on the table below.

Note: Unlike 'value unit' pairs above, these are evaluated without case sensitivity.
Suffix String Key Note
Yes tools_suffix_0047 The affirmative string "Yes".
No tools_suffix_0048 The negative string "No".
Enabled tools_suffix_0049 The string "Enabled".
Disabled tools_suffix_0050 The string "Enabled".
On tools_suffix_0051 The string "On".
Off tools_suffix_0052 The string "Off".


Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support
Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.