Generating Events Using the API

Download this manual as a PDF file

The /alert API resource can be used to generate alerts in SL1 that will appear as log messages in the Device Logs & Messages page, similar to how SL1 processes inbound syslog and trap messages. You can optionally create one or more event policies that will trigger when an alert generated through the API meets the criteria specified in the policy.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all of the menu options, click the Advanced menu icon ().

Generating Alerts

To generate an alert, you must perform a POST request to the /alert resource index. The content you POST must have the following structure:

{

"force_ytype":"0",

"force_yid":"0",

"force_yname":"",

"message":"",

"value":"0",

"threshold":"0",

"message_time":"0",

"aligned_resource":""

}

Supply the following values in each field:

  • force_ytype. Optional. The type of sub-entity on a device that you want to associate the alert with. This field can be set to the following numeric values that represent sub-entity types:
    • 1. CPU
    • 2. Disk
    • 3. File System
    • 4. Memory
    • 5. Swap
    • 6. Hardware Component
    • 7. Interface
    • 9. Process
    • 10. Port
    • 11. Windows Service
    • 12. Web Content
    • 13. Email Monitor

    For example, to associate the alert with a specific interface on a device, supply "7" in this field. If you are not supplying information about a sub-entity, supply 0 (zero) in this field.

  • force_yid. Optional. The ID value of the specific sub-entity on the device that you want to associate the alert with. For example, if you are associating the alert with the interface with ID 2, supply "2" in this field. If you are not supplying information about a sub-entity, supply 0 (zero) in this field.
  • force_yname. Optional. The name of the specific sub-entity on the device that you want to associate the alert with. For example, if you are associating the alert with the interface called "eth0", supply "eth0" in this field. If you are not supplying information about a sub-entity, supply en empty string in this field.

    • If an event policy is configured to clear another event policy, an instance of the event is cleared only when the clearing event has a matching sub-entity type, sub-entity ID, and sub-entity name.

  • message. Enter message text to associate with the alert. If the alert does not match an event, this text will be displayed in the Device Logs & Messages page. This text will be used to match against the First Match String and Second Match String values in event policies. If the alert triggers an event, this text will be substituted for the %M substitution character in the event message.
  • value. Optionally, supply the numeric value that triggered the alert. For example, if an alert indicates that CPU usage is high, you might pass the current CPU usage in this field. If you are not supplying a specific value, supply 0 (zero) in this field.
  • threshold. Optionally, supply the numeric threshold that was exceeded for this alert to be generated. This threshold can be used in an event policy message by using the %T substitution. If you are not supplying a specific threshold, supply 0 (zero) in this field.
  • message_time. The timestamp to associate with the alert in unix time format. The device log message will be listed at this date and time. Valid values include a timestamp or an empty string, "0" (zero), or "now", the latter three of which default to the current timestamp.

  • When creating a new API alert, the /api/alert endpoint now allows a custom timestamp. Valid values for message_time include a timestamp or an empty string, 0, or now, the latter three of which default to the current timestamp.

  • aligned_resource. The relative URI of the device with which you want to associate the alert. For example, to align the alert with device ID 1, supply /device/1.

Defining API Event Policies

All alerts generated using the /alert resources are matched against event policies of type "API".

When you create API event policies, the event messages are generated by inserting messages into the main database. These messages can be inserted by a snippet automation action, a snippet Dynamic Application, or by a request to the ScienceLogic API.

To define an API event policy:

  1. Go to Event Policies page (Events > Event Policies).
  1. In the Event Policies page, click the Create Event Policy button. The Policy Description tab of the Event Policy Editor appears.
  2. On the Policy Description tab, enter the following information:
  • Policy Name. Type a name for the event policy.
  • Enable Event Policy. Turn this toggle on to enable the event policy, or toggle it off to disable the event policy.
  • Policy Description. Type a description of the event policy.
  1. Click the Match Logic tab, then enter the following information:
  • Event Source. Specifies the source for the event. Select API.
  1. After selecting and defining your Event Source, enter values in the fields on the right side of the Match Logic tab:
  • String/Regular Expression. Use this drop-down to select String or Regular Expression.
  • Match String. Type a text string or a regular expression to match against the originating log message field of each alert generated through the API. The event will be generated if the message matches the Match String and the optional Second Match String values. This string can be up to 512 characters and length and can be any combination of alpha-numeric and multi-byte characters.

If you do not supply a value in the Match String field, your event policy will match all alerts generated through the API.

SL1's expression matching is case-sensitive.

  • Second Match String (Optional). Optionally, a second text string or regular expression to match against the originating log message field of each alert generated through the API. The event will be generated if the message matches the Match String and the Second Match String values.

The other fields on this page can be used to define specific event behavior or enable advanced event features. For a description of every option on this page, see the section on The Match Logic Tab.

  1. Click the Event Message tab, then enter the following information:
  • Event Message. Define the message that appears in the Event Console page or the Viewing Events page when this event occurs.

For more information about the Event Message field and descriptions of the other fields on this page that can be used to define the event severity, event masking, and other options, see the section on The Event Message Tab.

  1. Optionally, you can click the Suppression tab, where you can define specific devices or device groups for which the event should not appear.

For more information about the Suppression tab and the fields that appear on this page, see the section on The Suppression Tab.

  1. After entering information in each tab, click Save to save your new event policy.

Defining API Event Policies in the Classic SL1 User Interface

All alerts generated using the /alert resources are matched against event policies of type "API".

To create an event policy of type "API" in the classic SL1 user interface: 

  1. Go to the Event Policy Manager page (Registry > Events > Event Manager).
  2. Click the Create button. The Event Policy Editor page is displayed.
  3. Supply values in the following fields:
    • Event Source. Select API.
    • Operational State. Select whether the event policy is enabled or disabled.
    • Policy Name. Enter a name for your event policy.
    • Event Message. Enter the event message that will be displayed in the event console when this event is generated. You can use the %M (message), %V (value), and %T (threshold) substitution characters in this field to include information from the API request.
    • Policy Description. Enter descriptive text about your event policy. This text is displayed when a user selects the information icon () for an instance of this event.

    The Use Modifier checkbox is not applicable to API event policies.

  4. Click the Advanced tab. The advanced options are displayed.
  5. Supply values in the following fields:
    • First Match String. Enter text or a regular expression to match against the message field of each alert generated through the API. The event will be generated if the message matches the First Match String and the Second Match String values.

      • If you do not supply a value in the First Match String field, your event policy will match all alerts generated through the API.

    • Second Match String. Optionally, a second text string or regular expression to match against the message field of each alert generated through the API. The event will be generated if the message matches the First Match String and the Second Match String values.
    • Match Logic. Specifies whether the First Match String and Second Match String values are matched as text strings or regular expressions.

    The other fields on this page can be used to define specific event behavior or enable advanced event features. For a description of every option on this page, see the section on Defining Event Policies in the Classic SL1 User Interface.

  6. Click the Save button.