Java Based Lamp(deprecated)

Lamp is a command line utility to interact with OpsGenie service. It provides capabilities to create and close alerts, attach files, etc. 

Lamp is used to integrate any management tool that can execute a shell script with OpsGenie. Lamp interacts with the OpsGenie service through the RESTful Web API.

Lamp has a built in contextual help system for obtaining information on available commands, and available options for their use.  If you invoke lamp with the --help option, you will see the available list of commands. If you invoke lamp with the --help option with a specific command, you will see the options for that command.

For ease of use apiKey should be set in opsgenie-integration.conf file, for some flexible use cases --apiKey parameter can also be used when executing lamp commands.

 

Installation

Prerequisites: 

  • OpsGenie account : If you don't already have one create an OpsGenie account
  • Oracle JRE version 1.6 and above or OpenJDK version 6 and above

Installation Steps for Red Hat Based Distributions

  1. Download OpsGenie Integration
  2. Run following command to install Lamp and Marid :
    rpm -i opsgenie-integration-<your_version>.rpm
If you want to update from version 201X-XX-XX to 2.X.X, you must add --force parameter. E.g.:
rpm -U --force opsgenie-integration-<your_version>.rpm

We suggest that you backup your configuration files before update!

Installation Steps for Debian Based Distributions

  1. Download OpsGenie Integration
  2. Run following command to install Lamp and Marid :
    dpkg -i opsgenie-integration-<your_version>.deb

Installation Steps for Windows

  1. Download OpsGenie Integration
  2. Unzip opsgenie integration zip file which contains Lamp and Marid packages into a directory (C:\OpsGenie is the preferred path)
    • For 32-Bit Windows use lamp.exe
    • For 64-Bit Windows use lamp_64.exe
To set JAVA_HOME environment variable, refer to Setting JAVA_HOME for more information.
To enable Ruby scripting, you need to download JRuby Complete jar file and put this jar file in lib directory (/var/lib/opsgenie/lamp On Linux, LAMP_HOME/lib on Windows systems. Will be referred as LIBS_DIR in the rest of documentation).
Note: If any exception occurs, like network connection lost, invalid request, authorization exception, etc. lamp exits with exit code 1, and prints the exception message to the output. You should check the exit code of lamp if you need to handle exceptions.
Internet Requirement : By default Lamp requires internet connection to reach OpsGenie.
If Lamp host server does not have internet connection you can configure Lamp Proxy settings, see below.
Marid can also be used as a proxy for Lamp.
 

Configuration

Application Configuration

Lamp configuration file is

  • For Windows: <LAMP_HOME>/../conf/opsgenie-integration.conf
  • For Linux: /etc/opsgenie/conf/opsgenie-integration.conf

The following are the common configuration settings for Lamp:

Lamp Configuration Settings
Setting Description Mandatory Default Value
apiKey API key used for authenticating API requests.
API key can be obtained by adding an API Integration

* Optionally --apiKey parameter can also be set when executing lamp commands, in this case the apiKey in opsgenie-integration.conf file will not be used.
No -
user Default owner of the execution. If user is not specified for Lamp action this value will be used. No  
socketTimeout Socket timeout for request executed across OpsGenie server No 30 Sec
connectionTimeout Connection timeout for request executed across OpsGenie server No 30 Sec
maxConnectionCount Max number of simultaneous requests which may be executed across OpsGenie server No 50
Lamp Proxy Configuration Settings

In order to use Lamp on systems that are behind firewalls do not have direct access to the Internet, you need to configure Lamp proxy settings to interact with OpsGenie web services API, create alerts, etc. Marid can also be used as a proxy for Lamp.

Setting Description Mandatory Default Value
proxyHost Proxy host No -
proxyPort Proxy port No -
proxyUsername Proxy authentication username No -
proxyPassword Proxy authentication password No -
proxyDomain The domain to authenticate within No -
proxyWorkstation The workstation the authentication request is originating from. Essentially, the computer name for this machine No -
proxyProtocol Proxy connection protocol. It may be one of http or https depending on your proxy servers. No http
authMethod Proxy authentication mechanism. Should be one of BASIC or NT. No NT
JVM Configuration

You can change JVM settings like max/min memory, garbage collection settings and etc. by modifying configuration files depending on your operating system.

 
On Linux

You should modify LAMP_JVM variable in /etc/opsgenie/profile file. For example to set max memory to 1024 MB you should change LAMP_JVM as

LAMP_JVM=" -Xmx1024m $LAMP_JVM"
On Windows
For 32-bit Windows

You should modify  JVM settings in <LAMP_HOME>/lamp.vmoptions file. For example to set max memory to 1024 MB you should change -Xmx setting as

-Xmx1024m
For 64-bit Windows

You should modify  JVM settings in <LAMP_HOME>/lamp_64.vmoptions file. For example to set max memory to 1024 MB you should change -Xmx setting as

-Xmx1024m
Log Configuration

Lamp log configuration file is

  • For Windows: <LAMP_HOME>/conf/log.properties
  • For Linux: /etc/opsgenie/lamp/log.properties

This is a standard Apache Log4J configuration file. You can change log levels, log file names, appender settings and etc. Please refer to Apache Log4J Manual for a complete list of Log4J settings.
For example in order to change log level of script logger to DEBUG from WARN you should change log4j.logger.script=WARN, script as log4j.logger.script=DEBUG, script

Lamp log files will be written to (Will be referred as LOGS_DIR in the rest of documentation):
  • On Linux: /var/log/opsgenie/lamp
  • On Windows: LAMP_HOME/logs

Usage


Create Alert Command

Lamp createAlert command is used to create alerts in OpsGenie. createAlert command takes the following parameters:

Mandatory Parameters

Parameter
--message Alert text limited to 130 characters
--recipients The user names of individual users or names of groups

Optional Parameters

Parameter
--alias A user defined identifier for the alert and there can be only one alert with open status with the same alias. Provides ability to assign a known id and later use this id to perform additional actions such as log, close, attach for the same alert.
--actions A comma separated list of actions that can be executed. Custom actions can be defined to enable users to execute actions for each alert. All action executions will be posted to Outgoing Integrations like Webhook, Marid, Slack, HipChat etc
--source Field to specify source of alert. By default, it will be assigned to IP address of incoming request
--tags A comma separated list of labels attached to the alert.
--description Alert text in long form. Unlike the message field, not limited to 130 characters.
-D Additional alert properties. The syntax is -D<property name>=<property value>
--entity The entity the alert is related to.
--user Owner of execution
--note Additional alert note
--apiKey API key used for authenticating API requests * If not given the api key in the conf file will be used 
Optional API key is valid for all Lamp commands

Sample Usage:

With mandatory parameters:
lamp createAlert --message "appserver1 down" --recipients john.smith@acme.com
With optional parameters:
lamp createAlert --message "appserver1 down" --recipients john.smith@acme.com  --description "appserver1 is not responding to requests and reported as down by the monitoring tools"  --tags operations, servers --actions stop, restart -Dseverity=critical 
With optional apiKey parameter :
lamp createAlert --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --message "appserver1 down"  --recipients john.smith@acme.com

Get Alert Command

Lamp getAlert command is used to get alerts details from OpsGenie. getAlert command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be retrieved. Either alertId or alias must be provided
--alias Alias of the alert that will be retrieved. Either alertId or alias must be provided. Alias option can only be used open alert

Sample Usage:

lamp getAlert --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f
lamp getAlert --alias appserver3Down

Attach File Command

Lamp attachFile command is used to attach file to alerts in OpsGenie. attachFile command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that the file will be attached. Either alertId or alias must be provided
--alias Alias of the alert that the file will be attached. Either alertId or alias must be provided. Alias option can only be used open alerts
--attachment Absolute or relative path to the file
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp attachFile --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --attachment /tmp/lastHourCPUChart.png
lamp attachFile --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --attachment /tmp/lastHourCPUChart.png

Acknowledge Command

Lamp acknowledge command is used to acknowledge alerts in OpsGenie. acknowledge command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be acknowledged. Either alertId or alias must be provided
--alias Alias of the alert that will be acknowledged. Either alertId or alias must be provided. Alias option can only be used open alerts
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp acknowledge --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f 
lamp acknowledge --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down

Renotify Command

Lamp renotify command is used to renotify alert recipients. renotify command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that recipient will be renotified for. Either alertId or alias must be provided
--alias Alias of the alert that recipient will be renotified for. Either alertId or alias must be provided. Alias option can only be used open alerts
 

Optional Parameters

Parameter
--recipients The user names of individual users or names of groups that will be renotified for alert. If no recipient specified, all existing alert recipients will be renotified.
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp renotify --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f
lamp renotify --alias appserver3Down --recipients john.smith@xyz.com

Take Ownership Command

Lamp takeOwnership command is used to take ownership of alerts in OpsGenie. takeOwnership command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be owned. Either alertId or alias must be provided
--alias Alias of the alert that will be owned. Either alertId or alias must be provided. Alias option can only be used open alerts
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp takeOwnership --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f 
lamp takeOwnership --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down

Assign Command

Lamp assign command is used to assign the ownership of alerts in OpsGenie. assign command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be assigned. Either alertId or alias must be provided
--alias Alias of the alert that will be assigned. Either alertId or alias must be provided. Alias option can only be used open alerts
--owner The users who will be the owner of the alert after the execution.
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp assign --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --owner john.smith@acme.com
lamp assign --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --owner john.smith@acme.com

Add Team Command

Lamp addTeam command is used to add new teams to alerts in OpsGenie. addRecipient command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that the new team will be added. Either alertId or alias must be provided
--alias Alias of the alert that the new team will be added. Either alertId or alias must be provided. Alias option can only be used open alerts
--team The team that will be added to the alert.
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp addTeam --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --team operations
lamp addTeam --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --team operations

Add Recipient Command

Lamp addRecipient command is used to add new recipients to alerts in OpsGenie. addRecipient command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that the new recipient will be added. Either alertId or alias must be provided
--alias Alias of the alert that the new recipient will be added. Either alertId or alias must be provided. Alias option can only be used open alerts
--recipient The recipient that will be added to the alert.
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp addRecipient --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --recipient john.smith@acme.com
lamp addRecipient --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --recipient john.smith@acme.com

Add Note Command

Lamp addNote command is used to add notes to alerts in OpsGenie. addNote command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be retrieved. Either alertId or alias must be provided
--alias Alias of the alert that will be retrieved. Either alertId or alias must be provided. Alias option can only be used open alerts
--note Note text
 

Optional Parameters

Parameter
--user Owner of execution
--source Source of action
 

Sample Usage:

lamp addNote --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --note I'll work on this
lamp addNote --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --note I'll work on this

Execute Alert Action Command

Lamp executeAction command is used to execute custom actions on alerts in OpsGenie. executeAction command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that the action will be executed on. Either alertId or alias must be provided
--alias Alias of the alert that the action will be executed on. Either alertId or alias must be provided. Alias option can only be used open alerts
--action Action to execute
 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--source Source of action
 

Sample Usage:

lamp executeAction --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --action restartEntity
lamp executeAction --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --action restartEntity

Close Alert Command

Lamp closeAlert command is close open alerts in OpsGenie. closeAlert command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be closed. Either alertId or alias must be provided
--alias Alias of the alert that will be closed. Either alertId or alias must be provided. 

Optional Parameters

Parameter
--user Owner of execution
--note Additional alert note
--notify Comma separated list of user and groups which will be notified. Also special values "all", "recipients" and "owner" is accepted.
--source Source of action
 

Sample Usage:

lamp closeAlert --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f 
lamp closeAlert --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down

Delete Alert Command

Lamp deleteAlert command is delete alerts in OpsGenie. deleteAlert command takes the following parameters:

Mandatory Parameters

Parameter
--alertId Id of the alert that will be deleted.

Optional Parameters

Parameter
--user Owner of execution
--source Source of action

Sample Usage:

lamp deleteAlert --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f 

Heartbeat Command

Lamp heartbeat command is used send periodic heartbeat messages to OpsGenie. The heartbeat should be added to OpsGenie before sending a heartbeat, If a heartbeat with 10 minutes interval is added and OpsGenie does not get a heartbeat message within 10 minutes, OpsGenie creates an alert to notify the specified people. heartbeat command takes the following parameters.

For more information please refer to Heartbeat Monitoring and Heartbeat API pages.

Mandatory Parameters

Parameter
--name Name of the heartbeat on OpsGenie

Sample Usage:

lamp heartbeat --name ServerX

Enable Command

Lamp enable command is used to enable integrations and policies. enable command takes the following parameters.

Mandatory Parameters

Parameter
--id Id of the integration/policy that will be enabled. Either id or name must be provided
--type Type of the entity that will be enabled. It must be integration or policy.
--name Name of the integration/policy that will be enabled. Either id or name must be provided

Sample Usage:

lamp enable --id ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079
lamp enable --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --name Nagios Integration

Disable Command

Lamp disable command is used to disable integrations and policies. disable command takes the following parameters.

Mandatory Parameters

Parameter
--id Id of the integration/policy that will be disabled. Either id or name must be provided
--type Type of the entity that will be disabled. It must be integration or policy.
--name Name of the integration/policy that will be disabled. Either id or name must be provided

Sample Usage:

lamp disable --id ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079
lamp disable --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --name Nagios Integration

Execute Script Command

Script Directories (Will be referred as SCRIPTS_DIR in the rest of documentation)

  • On Linux: /var/opsgenie/lamp/scripts
  • On Windows: <LAMP_HOME>/scripts

executeScript command will execute a script (groovy, ruby, perl, etc) on lamp. Scripting capability will simplify the integration process.

Mandatory Parameters

Parameter
--name Name of the script to be executed. Script should be put into <SCRIPTS_DIR> directory
  • Lamp will determine the script engine via script file extension. For example if script is HelloWorld.groovy then Groovy scripting engine will be used to execute speicified script.
  • In order to enable your favorite scripting engine, you need to download engine and put it into directory <LIBS_DIR>.
Supported Scripting Languages
Extension Scripting Language Engine Download Link
.groovy Groovy Already bundled Lamp
.rb Ruby Latest JRuby Complete jar at http://jruby.org/download
Parameters are passed as global variables to Ruby scripts hence they should be accessed as $parameter_name. For example, logger parameter can be accessed as $logger in Ruby script.

Optional Parameters

Parameter
-D Parameters which will be passed to script. The syntax is -D<parameter name>=<parameter value>. Parameters can be accessed from script via params variable.

Variables Passed to Script

Parameter
params The variable to access parameters which are passed by -D option of executeScript command.
logger Logging utility. All script logs will be written to <LOGS_DIR>/script.log file.
conf The variable to access parameters specified in opsgenie-integration.conf file.
opsgenie The variable to execute an operation on opsgenie server.
Please refer to Script Proxy for Marid documentation for a list of available operations.  
  

Default Lamp Scripts

Lamp downloadable comes with handy scripts :

  • HelloWorld.groovy & HelloWorld.rb : Print parameters
  • CreateAlert.groovy  &  CreateAlert.rb  : Create a sample alert with given parameters
  • processOldAlerts.groovy : Utility script to close / ack / delete alerts older than X days
  • alertActionsDemo.groovy: Demonstration of alert actions.

HelloWorld Lamp Script

Sample Usage 

lamp executeScript --name HelloWorld.groovy -Dparam1=value1 -Dparam2=value2
Content of <SCRIPTS_DIR>/HelloWorld.groovy file :
logger.warn("Parameter list:");
params.each{paramName, paramValue->
    logger.warn("${paramName}:${paramValue}");
}
Expected Output in log file <LOGS_DIR>/script.log :
12/06/18 16:44:08.288 WARN: Parameter list:
12/06/18 16:44:08.304 WARN: param1:value1
12/06/18 16:44:08.304 WARN: param2:value2

CreateAlert Lamp Script

Sample Usage

lamp executeScript --name CreateAlert.groovy -Dmessage=an alert
Content of <SCRIPTS_DIR>/CreateAlert.groovy file
logger.warn("Creating alert with message ${params["message"]}");
alertprops = [:]
alertprops["message"] = params["message"];
alertprops["recipients"] = "all"
def response = opsgenie.createAlert(alertprops);
logger.warn("Alert is created with id ${response["alertId"]}")
Expected Output in log file <LOGS_DIR>/script.log:
12/06/18 17:01:06.772 WARN: Creating alert with message message1
12/06/18 17:01:11.460 WARN: Alert is created with id :3418a79c-e41f-45d4-8d84-d2ce123fb79b

processOldAlerts Lamp Script

This script helps executing bulk actions on old alerts, script processes all alerts regardless of recipients.

Sample Usage:

Default :  closes open alerts older than 2 days

lamp executeScript --name processOldAlerts.groovy

Test Param : Lists open alerts older than 2 days but does not perform any actions

lamp executeScript --name processOldAlerts.groovy -Dtest=true

Day Param : closes open alerts older than 8 days

lamp executeScript --name processOldAlerts.groovy -Dday=8

Action Param : acknowledges open alerts older than 5 days

lamp executeScript --name processOldAlerts.groovy -Daction=ack -Dday=5

Status Param : deletes closed alerts older than 2 days

lamp executeScript --name processOldAlerts.groovy -Daction=delete -Dstatus=closed

alertActionsDemo Lamp Script

This script demonstrates the use of simple scripting by using Script Proxy for Marid 
It creates a demo alert, executes different actions on it.

Sample Usage:

   
lamp executeScript --name alertActionsDemo.groovy

Version Command

It prompts the current Lamp Version

Sample Usage 

lamp version

Source

The source code is available at GitHub.