Field mapping for generic webhook integration

The Field mapping section lets you map the alert fields from your monitoring tool to the alert fields of Lightstep Incident Response.

Before you begin

Role required: Responder, Manager, or Administrator

Procedure

  1. Click the Field mapping tab.
  2. Enter the field mapping details to map your monitoring tool alert to a Lightstep Incident Response alert.
    Note:
    • Field mapping includes two enumerations (state and severity) and several individual fields. To add more alert fields, click +Add parameters that appears at the end of the page.
    • The sample alert is automatically updated using the details you enter in the Alert value field.

    Parameters in the generic webhook integration.

    Table 1. Fields mapping
    Fields Description
    Field name Represent the attributes of a Lightstep Incident Response alert. For example, the corresponding attribute of the description field is the short description of the alert.
    Mapping

    Enter the JSON path to the appropriate mapping field in the incoming alert payload. The path is the dot-walked representation of a specific JSON payload field. For example, the mapping field alert.state represents the value Open in the following sample JSON format.

    Here is a new JSON with sample mapping and values, which are represented in the sample alert panel:
    {
    "alert": {
        "state": "Open",
        "severity": "Very high",
        "time": "2021-10-28 12:40:00",
        "title": "90% of disk is full",
        "source": "MyMonitoringTool",
        "original": {
            "node": "Server1",
            "subsystem": "Disk",
            "kpi": "Free Capacity",
            "kpi_unit": "GB"
        }
    },
    "version": "1.0"
}
    Alert value Value entered in this field is used while generating the sample alert.
    If the value of the Mapping field is alert.state and the Alert value is Open, the sample alert would contain the following:
    "alert": {"state": "Open"}
    Note: The alert value column is used only to generate the sample alert.
    Alert value.
    +Add enumeration value

    Map the alert value with the alert state or severity by clicking +Add enumeration value and select the appropriate value from the list.

    Map the alert value with the alert state.
    Note:
    • You can also create a mapping for when the severity field is not available in your alert. In the example above, the empty field is mapped to the severity Warning, which creates an alert with priority P4-Low.
    • If a severity value is not available in your alert, and a default mapping is not created for this scenario, it is implicitly interpreted as a Warning severity, which creates an alert with priority P4-Low.
    • Similarly, an empty state value is implicitly interpreted as New.

    For state and severity, the messages Alert states and Alert severities indicate the number of values you have mapped out of all available alert values for a Lightstep Incident Response alert. It is acceptable to only configure a subset of them. For example, you could configure all 3 alert severity values from your monitoring tool to map to 3 alert severities in Lightstep Incident Response. Alternatively, you could have 7 alert severity values from your monitoring tool to map to the only 6 alert severities in Lightstep Incident Response.

    Fields used to create an alert key.

    Note: The five fields, source, node, resource_name, metric_name, and metric_type are used together to create an alert key. If that alert key does not yet exist in Lightstep Incident Response, a new alert is created. If the incoming alert contains an alert key that corresponds to another alert in Lightstep Incident Response, that new alert is used to update the existing alert and notes are added in the Alert timeline in the alert Details view.
    The state of an alert can be one of the following:
    State Description
    New The alert is unacknowledged and requires user action.
    Closing The alert is closed and no further user action is required.
    The severity of an alert can be one of the following:
    Severity Mapped to alert priority Description
    Critical P1-Critical Immediate action is required. The resource is either not functional or critical problems are imminent.
    Major P2-High Major functionality is severely impaired or performance has degraded.
    Minor P3-Moderate Partial, non-critical loss of functionality or performance degradation occurred.
    Warning P4-Low Attention is required, even though the resource is still functional.
    OK P5-Informational An alert is created. The resource is still functional.
    Clear No action is required. An alert is not created from this event. Existing alerts are closed.
    Note:
    • If the severity is not mapped to any fields, then alerts are created with a default priority of P4-Low.
    • If you pass a value from 1 through 5 as the severity, alerts will be created with the corresponding priority from P1 through P5. This is a pre-defined setting, and doesn't need mapping.
    The event_time is the time when the event occurred. The format of the incoming event time in the payload must be mentioned in the Format field as follows:
    The generic api event time.
    In the given example, the time when the event occurred is 2021-10-28 12:40:00 and the corresponding format is YYYY-MM-dd hh:mm:ss. The format string consists of the following abbreviations:
    Field Form
    Year YYYY
    Month MM
    Day of month dd
    Hour (12-hour time) hh
    Hour (24-hour time) HH
    Minute mm
    Second ss
    Note:
    • If the time format is not mentioned, the incoming time format is assumed to be the UNIX epoch time in milliseconds.
    • If an incorrect time format is given, the time when the alert is received by Lightstep Incident Response is considered.
    • If a correct time format is given but the value is incorrect, the time when the alert is received by Lightstep Incident Response is considered.
  3. Click Save.
    The generated payload can be found in the Sample alert section. Click Send sample alert to send a sample alert that contains the fields you defined. You can also copy this sample to your environment to send as an alert to Lightstep Incident Response. You can view the sample alert in Alerts.