Connect Guance Self-built Notification Targets

Added in version 2.5.2

1. Background

In some cases, the alarm notification methods provided by Guance cannot meet actual business needs. Using the "Custom Webhook" method requires users to modify their existing business systems or separately build a receiving system, which can be inconvenient.

At this point, you can use Guance's "Self-built Notification Targets" to send alert notifications directly to a specific function in local DataFlux Func, allowing for subsequent operations to be executed.

2. Preparation

To implement self-built notification targets, the following preparations need to be completed:

Preparation	Reference Documentation
Upgrade DataFlux Func to version 2.5.2 or higher	Deployment and Maintenance / Daily Maintenance / System Upgrade
Create an API Key in Guance	Guance Documentation / Workspace Management / API Key Management

3. Specific Steps

Below are the detailed steps:

3.1 Enable the Guance Connector

In "Management / Experimental Features," enable the "Guance Connector"

Go to "Development / Connectors / Add Connector," select the type as "Guance," and fill in the relevant configuration parameters.

3.2 Write the Self-built Notification Function

Go to "Development / Script Library" and create a script to store the self-built notification function.

The self-built notification function has fixed requirements:

1. It must use @DFF.API(...) decoration and add category='guance.alertFunc'
2. The function name is unrestricted, but there must be one and only one parameter event. For details on the parameter values, see the appendix.

Taking sending DingTalk notifications as an example, the complete code is as follows:

Sending DingTalk notifications can be configured directly in Guance without needing a self-built notification target; this code is merely an example and has no practical significance.

Refer to the appendix for documentation related to DingTalk bots.

import time
import hmac
import hashlib
import base64
import urllib.parse

import requests

@DFF.API('Custom Notification Target Example', category='guance.alertFunc')
def test(event=None):
    # DingTalk bot Webhook URL
    webhook = 'https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxx'
    # DingTalk bot signing key
    secret  = 'SECxxxxxxxxxx'

    # Calculate and add the signature
    timestamp = str(round(time.time() * 1000))
    secret_enc = secret.encode('utf-8')
    string_to_sign = '{}\n{}'.format(timestamp, secret)
    string_to_sign_enc = string_to_sign.encode('utf-8')
    hmac_code = hmac.new(secret_enc, string_to_sign_enc, digestmod=hashlib.sha256).digest()
    sign = urllib.parse.quote_plus(base64.b64encode(hmac_code))
    webhook += f'&timestamp={timestamp}&sign={sign}'

    # Send request to DingTalk bot
    event = event or {}
    title   = event.get('df_title')   or 'No specific title'
    message = event.get('df_message') or 'No specific content'
    data = {
         'msgtype': 'markdown',
         'markdown': {
             'title': title,
             'text' : f"#### {title} \n\n {message} \n\n This message was sent via a self-built notification target."
         }
     }
    r = requests.post(webhook, json=data)
    return r.text

After completing the code writing, don't forget to publish it.

3.3 Confirm the Self-built Notification Target in Guance

In Guance's "Monitoring / Notification Targets Management," you should see the previously written and published notification target function in the list.

3.4 Select the Self-built Notification Target in Monitors

In Guance's "Monitoring / Monitors," configure the alert strategy for the monitor and select the newly created self-built notification target.

3.5 Receive the Self-built Notification

Based on the code written earlier, we extracted the event's title and content, and added an extra line: "This message was sent via a self-built notification target."

Assuming the "Event Content" in the monitor is simply configured with the following content:

- Status: {df_status}
- Result: {Result}

Then, after processing through the self-built notification target, the final message received by the DingTalk bot will look like this:

X. Appendix

Below is the appendix.

X.1 DingTalk Bot Related Documentation

• Group Bots: https://open.dingtalk.com/document/robots/custom-robot-access
• Group Bot Signing Explanation: https://open.dingtalk.com/document/robots/customize-robot-security-settings

X.2 Self-built Notification Target Function event Parameter

The event parameter received by the self-built notification target is a dict, with the following internal fields:

Field Name	Type	Required	Description
timestamp	Integer	Required	Generation time. Unix timestamp, unit seconds
df_status	Enum	Required	Status. Possible values: ok, info, warning, error, critical, nodata
df_event_id	String	Required	Event ID
df_title	String	Required	Title
df_message	String		Detailed description
df_dimension_tags	String(JSON-format)	Required	Detection dimension tags, e.g., {"host":"web01"}
df_monitor_id	String		Monitor group ID
df_monitor_name	String		Monitor group name
df_monitor_checker_id	String		Monitor ID
df_monitor_checker_name	String		Monitor name
df_monitor_checker_value	String		Value when the detection triggers an event
df_monitor_checker_value_dumps	str(JSON)		Value when the detection triggers an event (JSON serialized) Convenient for deserialization by the user to get the original value
df_event_link	String		Event jump link
df_workspace_uuid	String		Belonging workspace UUID
df_workspace_name	String		Belonging workspace name
Result	Float		Detection value
{Other additional fields}			Omitted

Generally speaking, when connecting to third-party messaging platforms, only the df_title and df_message fields are needed.

Example:

{
    "timestamp"                     : 1625638440,
    "df_status"                     : "warning",
    "df_event_id"                   : "event-xxxxxxxxxx",
    "df_title"                      : "web001 issue exists",
    "df_message"                    : "web001 issue exists, nCPU usage greater than 90\n Memory usage greater than 90",
    "df_dimension_tags"             : "{\"host\":\"web001\"}",
    "df_monitor_id"                 : "monitor_xxxxxxxxxx",
    "df_monitor_name"               : "Anomaly detection name",
    "df_monitor_checker_id"         : "rul_xxxxxxxxxx",
    "df_monitor_checker_name"       : "Anomaly detection project name",
    "df_monitor_checker_value"      : "99",
    "df_monitor_checker_value_dumps": "99",
    "df_event_link"                 : "https://console.guance.com/keyevents/monitorChart?xxxxxxxxxx",
    "df_workspace_uuid"             : "wksp_xxxxxxxxxx",
    "df_workspace_name"             : "My workspace",
    "Result"                        : 99,
    "... Other additional fields": "Omitted",
}