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. Fill the alert mapping details to map your 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.

    Parameters in the generic webhook integration.

    With the details that you entered for each alert field, the sample alert is created.

    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 is used while generating 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 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: In the example above, it is explicitly stated that a blank severity value is interpreted as a Warning severity. If a blank value is not specified, it will be implicitly interpreted as a Warning severity. Similarly, if a blank state value is not specified, it will be 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 which 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 Description
    Critical Immediate action is required. The resource is either not functional or critical problems are imminent.
    Major Major functionality is severely impaired or performance has degraded.
    Minor Partial, non-critical loss of functionality or performance degradation occurred.
    Warning Attention is required, even though the resource is still functional.
    OK 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.
    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 just defined. You can also copy this to your environment to send as an alert to Lightstep Incident Response. You can view the sample alert in Alerts.