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

SettingDescriptionMandatoryDefault Value
apiKeyAPI 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-
userDefault owner of the execution. If user is not specified for Lamp action this value will be used.No
socketTimeoutSocket timeout for request executed across Opsgenie serverNo30 Sec
connectionTimeoutConnection timeout for request executed across Opsgenie serverNo30 Sec
macConnectionCountMax number of simultaneous requests which may be executed across Opsgenie serverNo50

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.

SettingDescriptionMandatoryDefault Value
proxyHostProxy hostNo-
proxyPortProxy portNo-
proxyUsernameProxy authentication usernameNo-
proxyPasswordProxy authentication passwordNo-
proxyDomainThe domain to authenticate withinNo-
proxyWorkstationThe workstation the authentication request is originating from. Essentially, the computer name for this machineNo-
proxyProtocolProxy connection protocol. It may be one of http or https depending on your proxy servers.No-
authMethodProxy authentication mechanism. Should be one of BASIC or NT.No-

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*

Create Alert Command

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

Mandatory Parameters

Parameter
--messageAlert text limited to 130 character
--recipientsThe user names of individual user or names of groups

Optional Parameters

Parameter
--aliasA 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.
--actionsA 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
--sourceField to specify source of alert. By default, it will be assigned to IP address of incoming request
--tagsA comma separated list of labels attached to the alert.
--descriptionAlert text in long form. Unlike the message field, not limited to 130 characters.
-DAdditional alert properties. The syntax is -D=
--entityThe entity the alert is related to.
--userOwner of execution
--noteAdditional alert note
--apiKeyAPI 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 [email protected]

With optional parameters:

lamp createAlert --message "appserver1 down" --recipients [email protected]  --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 :

Get Alert Command

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

Mandatory Parameters

Parameter
--alertIdId of the alert that will be retrieved. Either alertId or alias must be provided
--aliasAlias 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
--alertIdId of the alert that the file will be attached. Either alertId or alias must be provided
--aliasAlias of the alert that the file will be attached. Either alertId or alias must be provided. Alias option can only be used open alerts
--attachmentAbsolute or relative path to the file

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--sourceSource 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
--alertIdId of the alert that will be acknowledged. Either alertId or alias must be provided
--aliasAlias 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
--userOwner of execution
--noteAdditional alert note
--sourceSource 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

--alertIdId of the alert that recipient will be renotified for. Either alertId or alias must be provided
--aliasAlias 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

--recipientsThe 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.
--userOwner of execution
--noteAdditional alert note
--sourceSource of action

Sample Usage:

lamp renotify --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f
lamp renotify --alias appserver3Down --recipients [email protected]

Take Ownership Command

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

Mandatory Parameters

Parameter
--alertIdId of the alert that will be owned. Either alertId or alias must be provided
--aliasAlias 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
--userOwner of execution
--noteAdditional alert note
--sourceSource 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
--alertIdId of the alert that will be assigned. Either alertId or alias must be provided
--aliasAlias of the alert that will be assigned. Either alertId or alias must be provided. Alias option can only be used open alerts
--ownerThe users who will be the owner of the alert after the execution.

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--sourceSource of action

Sample Usage:

lamp assign --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --owner [email protected]
lamp assign --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --owner [email protected]

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
--alertIdId of the alert that the new team will be added. Either alertId or alias must be provided
--aliasAlias 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
--teamThe team that will be added to the alert.

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--sourceSource 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
--alertIdId of the alert that the new recipient will be added. Either alertId or alias must be provided
--aliasAlias 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
--recipientThe recipient that will be added to the alert.

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--sourceSource of action

Sample Usage:

lamp addRecipient --alertId 44d2e383-df30-49e1-820e-65e8e6e6387f --recipient [email protected]
lamp addRecipient --apiKey ab5454992-fabb2-4ba2-ad44f-1af65ds8b5c079 --alias appserver3Down --recipient [email protected]

Add Note Command

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

Mandatory Parameters

Parameter
--alertIDId of the alert that will be retrieved. Either alertId or alias must be provided
--aliasAlias of the alert will be retrieved. Either alertId or alias must be provided. Alias option can only be used open alerts
--noteNote Text

Optional Parameters

Parameter
--userOwner of execution
--sourceSource 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
--alertIdId of the alert that the action will be executed on. Either alertId or alias must be provided
--aliasAlias 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
--actionAction to execute

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--sourceSource 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
--alertIdId of the alert that will be closed. Either alertId or alias must be provided
--aliasAlias of the alert that will be closed. Either alertId or alias must be provided.

Optional Parameters

Parameter
--userOwner of execution
--noteAdditional alert note
--notifyComma separated list of user and groups which will be notified. Also special values "all", "recipients" and "owner" is accepted.
--sourceSource 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
--alertIdId of the alert that will be deleted.

Optional Parameters

Parameter
--userOwner of execution
--sourceSource 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
--nameName 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
--idId of the integration/policy that will be enabled. Either id or name must be provided
--typeType of the entity that will be enabled. It must be integration or policy.
--nameName 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
--idId of the integration/policy that will be disabled. Either id or name must be provided
--typeType of the entity that will be disabled. It must be integration or policy.
--nameName 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
--nameName 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

ExtensionScripting LanguageEngine Download Link
.groovyGroovyAlready bundled Lamp
.rbRubyLatest 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
-DParameters which will be passed to script. The syntax is -D=. Parameters can be accessed from script via params variable.

Variables Passed to Script

Parameter
paramsThe variable to access parameters which are passed by -D option of executeScript command.
loggerLogging utility. All script logs will be written to <LOGS_DIR>/script.log file.
confThe variable to access parameters specified in opsgenie-integration.conf file.
opsgenieThe 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.