Skip to main content

Test LAM

The Test LAM produces dummy data for profiling, prototyping, building scripts, and integration testing, all undertaken in a controllable way. You can configure a number of event templates and source templates in test_lam.conf. For each of the source definitions you reference in the event template, the LAM semi-randomly sends one event onto the event bus. The semi-random aspect means that you can configure an interval between events, including the degree of variance in that interval. The LAM sends the events and the average period between events forms a distribution in line with your configuration.

You can also configure event templates to be chained. For example, you can test link up/link down style functionality where you would never want the link up to arrive before the corresponding link down; therefore, you would chain a link up template to follow a link down.

Configure the LAM

Like all other LAM’s, the Test LAM has a configuration file, test_lam.conf with an associated Lambot, test_lam.js.

The sections below describe how to format your inputs, and the parameters the config object contains.

Quoting

In some instances the attribute strings are quoted. Our JSON parser is forgiving, but we recommend that you quote all strings.

Hash

To comment out lines, prepend them with a hash.

Monitor object

The monitor section allows you to define all the templates and control the generation of the events . Do not change the name or class properties, these are documentation values that the code requires:

monitor: 
{ 
        name    : "Test File Monitor", 
        class   : "CTestMonitor", 
}

data_rate

data_rate allows you to instruct the test LAM to generate a given quantity of output in a minute. You define the output as the number of events per minute. The test LAM then compresses time to adjust the period for each template and achieve the rate you supply.

The follow example specifies a data rate of 500 events per minute:

data_rate : 500, 

If you define one template with one source host that sends an event every 20 seconds, your actual rate is three events per minute. But if you want the LAM to send 30 events per minute, the system compresses the period from 20 to two seconds to achieve 30 events per minute.

The system's minimum time between sending events is one millisecond. We do not recommend sending out that many events in a single LAM (for one template and source this equates to 60,000 events per minute), as doing so overloads the relevant systems.

total_events

The default value for total_events is -1. Setting a value above 0 causes the LAM to produce that many events and then exit. For example if total_events is set to 100, the LAM will generate 100 events and then complete. Setting a value below 0 causes the LAM to continue indefinitely.

total_events : -1, 

resolution

resolution is an internal field that controls the execution of the templates and the number of slices the LAM divides one minute into. The Test LAM attempts to distribute the generation of events evenly across a minute and uses these subdivisions to fill with individual template/source combinations. Internal execution of the LAM effectively evaluates all event templates for execution.

In all normal implementations resolution is set to 1, which causes no time slicing and every template is checked every second.

resolution : 1, 

resolution is effectively the granularity of time to use in the LAM. For example, if you have 20 seconds as a period, resolution controls whether it is 20 seconds exactly (set to 1), or, plus or minus five seconds (set to 12). If you divide time slices into a second, you can have periods that are resolved up to a second. If you divide time slices into 5, if you then have a period of 18, it would either execute on 15 seconds or 20 seconds.

The reason you configure this is that the wider the resolution, the less compute the LAM uses to generate events; the trade-off is the greater the error in the randomness.

resolution determines how closely packed you can put exemplar's for an event template. If you define a template for every 20 seconds and you have 10,000 hosts, what you must avoid is on the 0 second sending 10,000 events, and then, sending nothing until the next 20 seconds before sending 10,000 more. The system spreads out in time the load so that you end up with a consistent event rate (which averages to the value set in data_rate). Therefore avoid overloading the system and returning an unrealistic event rate that exhibits high kurtosis.

sources

sources defines the imaginary sources or hosts that the events will come from. You can define these in one of two ways.

The first way is to define a simple list of source names:

sources: 
{ 
        "switches" : [ "switchA","switchB","switchC","switchD" ], 
}

An event template that use switches will generate an event for Switch A, an event for Switch B, an event for Switch C, and so on. While this generates a number of events from different sources, the methodology is time-consuming.

The second way is to use autohost, which allows the autogeneration of a long list of similar hosts, where you define the template hostname; in the following example it is xldn%dpap . You must also define a range with a start and a count:

"autohost": 
{ 
        "template" : "xldn%dpap", 
        "range": 
        { 
                "start" : 12, 
                "count" : 10 
        } 
} 

This substitutes for %d a number that starts at 12 and produces 10 instances. So you would have 12, 13, 14, 15, 16 all the way up to 21 in this instance. This is a good way to generate a high volume of events from a variety of sources. For example, you can have a start of 1 and have a count of 10,000, which results in 10,000 events from 10,000 different sources.

sources is an object that contains entries that take a list, or, in the case of an autohost, take an object that takes a template and a range, which is an object.

events is a list of event templates, which are JSON objects. Each event template allows you to provide it with a name. This is important because by default, the signature for the generated event is composed of “$name:$source”:

events:[ 
{ 
        "name" : "DBRestart
}]

The template name and source thus enable you to deduplicate alerts from an event template. To do so, you specify which source definition to combine with the template to generate the events. The sources must therefore match a definition of sources:

#"sources"   : "hosts", 
"sources"    : "autohost", 

timing

You can either send the events with a fixed period, or, if you specify a time period (in seconds), you can randomise the period between events.

"timing": 
{ 
        "randomised" : true, 
}

Setting randomised to true randomises the exact period between events. If, for example, the core period you specify is 20 seconds, this sets the average period over time but you will also receive individual events spaced with a random period i.e., 18 seconds, 21 seconds. The way it averages up to the 20 is defined in distribution, which defines a tuned probabilistic distribution for the periods.

You can also specify a distribution class to specify the distribution of periods, which controls the sequence of intervals between events from a given template according to a class, which implements a given probability density function. In this case CUniformDist randomly selects periods (up to max_period) in increments of increment, but ensures that over sample_norm, chunks of max_period that each period (in this case 0 (we actually use 1 second rather than 0),10,20,30,40,50,60) occur equally likely, and the period will average to 30.143 (a period of 0 seconds is not allowable, which is why the answer is not exactly 30!).

"distribution": 
{ 
        class           : "CUniformDist", 
        max_period      : 60, 
        increment       : 10, 
        sample_norm : 2 
} 

The above example specifies:

  • class is an internal class used to achieve the distribution. A uniform distribution is a type of probability distribution where each of the possible outcomes has equal probability. In the example above you would want the average to be 30, but you want the probability of having 40 seconds versus 20 seconds to be identical. This is sometimes referred to as a flat distribution. Using this you will end up with an equal number of 10 seconds, an equal number of 20 seconds, an equal number of 30 seconds and so on over a very long period of time, which will present an average period of 30 seconds

Moogsoft Onprem currently only supports uniform distribution, which splits max_period into increment chunks and then randomly chooses from amongst that event set with equal probability. The sample_norm is the time over which the engine guarantees that the mean is max_period/2.

In future releases Moogsoft will support normal distribution, and be able to define the kurtosis, the standard deviation and variance.

fields

fields defines all the various components of events that are sent on the events bus. For example in your test environment you can specify: the class, a description, an external identifier etc., as shown below:

"fields": 
{ 
        "agent_location"      : "localhost", 
        "class"                       : "AppMon", 
        "description"                 : "Database instance has restarted",
        "external_id"                 : "12345", 
        "manager"                     : "PATROL", 
        "severity"                    : 2,    
        "type"                                : "DBFail", 
        "entropy"                     : 0.8 
} 

Moogsoft Onprem will fill in the first occurred, the last occurred, the agent time etc. The whole of the file is a sequence of these templates. There are different examples of timing parameters and distribution.

LinkDown

For example in the LinkDown, in timing you have an interval of 60, randomised set to true, and a variance of 20.

"name"               : "LinkDown", 
"sources"     : "switches", 
"timing"      : { 
                                "interval" : 60, 
                                "randomised" : true, 
                                "variance" : 20 
              },

The above example specifies:

  • On average the period is going to be 60 seconds but the variance specifies that it can range from 40 to 80 seconds, and take a random value between these two values, which averages to 60

LinkUp

The LinkUp template has the precedent field, which references the LinkDown template, which means you can only get a Link Up once there has been a Link Down for the given defined source (switches).

"name"               : "LinkUp", 
"sources"     : "switches", 
"precedent" : "LinkDown", 
"timing"      : { 
                                "interval" : 60, 
                                "randomised" : true, 
                                "variance" : 20 
                          }, 

The above example specifies:

  • On average the period is going to be 60 seconds after the Link Down, with a variant ranging from 40 to 80 seconds.

Web Server Down Trap

In the Web Server Trap Down, you only have two fields: randomised and variance.

"name"               : "Web Server Down Trap", 
"sources"     : "hosts", 
"timing"      : { 
                                "randomised" : true, 
                                "variance" : 180 
              }, 
  • With randomised set to true and variance set to 180 you will get a period between occurrences that is a random number between one and 180 seconds. On average you will get an event every 90 seconds

Agent and Process Log

The Agent and Process Log sections of the Test LAM configuration file enable you to define the following properties:

  • name: Maps to $Laminstancename, so that the agent field indicates events Moogsoft Onprem ingests from this LAM.

  • capture_log: Name and location of the LAM's capture log file, which it writes to for debugging purposes.

  • configuration_file: Name and location of the LAM's process log configuration file. See Configure Logging for more information.Configure Logging

Filter

The filter defines whether Moog uses a LamBot. If you comment out the presend value, no filter is applied to the events produced and all events are sent unchanged to the MooMs bus. If a LamBot is defined, for every event the system assembles using this configuration, the event is passed to the LamBot (via the presend function defined in the LamBot).

filter: 
{ 
        presend: "TestLam.js" 
} 

Therefore you must define a presend function in your JavaScript file.

The return value of the presend function will determine whether the event is sent on to the MooMs bus. The presend function can also define sub-streams that events are sent out on, so events can be sent to different farmd’s.

You can provide an additional parameter to presend called modules that takes a JSON list. The JSON list is a list of optional JavaScript files that are loaded into the context of the LamBot and executed; thus, you can share modules between LAMs. For example, you can write a generic Syslog processing module that is used in both the Socket LAM and the log file LAM. You therefore do not need to needlessly replicate code in the Moobot for each of the LAMs.