Skip to main content

Programmatic LAM

The Programmatic Link Access Module (LAM) is a custom polling LAM. It is an advanced version of the REST Client LAM. The REST Client LAM accepts a single API call and parses the responses it receives into Moogsoft Enterprise events. The Programmatic LAM can accept multiple calls but you must define the processing yourself in the LAMbot using JavaScript.

Before you begin

Before you start to configure the LAM, ensure you have met the following requirements:

  • You have the details of the API to query.

  • You can write JavaScript.

Configure the LAM

Edit the configuration file to control the behavior of the Programmatic LAM. You can find the file at $MOOGSOFT_HOME/config/programmatic_lam.conf.

  1. Configure the behavior of the LAM:

    • request_interval: Length of time to wait between calls to the execute method, in seconds. Defaults to 60.

    • num_threads: Number of worker threads to use for processing events. Defaults to 5.

  2. Optionally configure the LAM identification and logging details in the agent and log_config sections of the file:

    • name: Identifies events the LAM sends to the Message Bus.

    • capture_log: Name and location of the LAM's log file.

    • configuration_file: Name and location of the LAM's process log configuration file.

Example LAM configuration

An example Programmatic LAM configuration is as follows:

monitor:
{
   name: "Programmatic LAM",
   request_interval: 60,
   num_threads: 5
   agent:
   {
      name: "ProgrammaticLam",
      capture_log: "$MOOGSOFT_HOME/log/data-capture/programmatic_lam.log"
   },
   log_config:
   {
      configuration_file: "$MOOGSOFT_HOME/config/logging/custom.log.json"
   }
}

Configure the LAMbot

You must configure the Programmatic LAMbot with JavaScript code to process and filter events and send them to the Message Bus.

You can find the LAMbot file at $MOOGSOFT_HOME/bots/lambots/ProgrammaticLam.js. It contains the following functions.

onLoad

The LAMbot calls the onLoad function when it is first initialized. Use it to set up any structures and variables required for subsequent processing.

execute

The execute function takes a single argument, programmaticApi. It allows you to pass state information from one execute call to another. For example, if you are polling an endpoint that requires a time variable, you can pass the last time value so that the next poll can start from that time.

Moogsoft Enterprise saves the state to the MoogDb database for use during failover from active to passive in a high availability (HA) environment. When passive becomes active the LAMbot reads the state from the database and uses the correct information in its next poll.

The execute function calls the following modules:

  • REST.V2: Use this module to query an external endpoint. See REST.V2 for more information.

  • ExternalDb: Use this module to execute queries on databases that support JDBC connections. See ExternalDb for more information.

The execute function contains the following methods:

  • getState: Allows you to pass state information from one execute call to another. State is automatically set by the return object of the execute function call. For example:

    return { events [], state {} };
  • captureLog: Allows you to write raw event data to the log file defined in the capture_log property in the LAM's configuration file.

Example return object

An example return object from the execute function containing an event with description, class and host information is as follows:

return 
{    
   "events": [ { "description": "Loss of Signal","class":"Gigabit Ethernet","host":"S-CARP282" } ],    
   "state": { "last_poll_time": 649077928 }    
};

presend

The LAMbot calls the presend function every time it assembles an event to publish on the Message Bus. If the function returns true, the event is published on the bus. If it returns false, the event is discarded. Moogfarmd processes published events and turns them into alerts and Situations.

Use the presend function to define the conditions in which events will and will not be published. You can also use the function to partition event streams for differential processing in a distributed environment.