Integration with Guance and TrueWatch Self-built Notification Targets

Added in version 2.5.2

1. Background

In some cases, the alert notification methods provided by Guance and TrueWatch may not meet actual business needs. Using a "Custom Webhook" requires users to modify their existing business systems or set up a separate receiving system, which can be inconvenient.

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

2. Preparations

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

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

3. Specific Steps

The following are the detailed steps:

3.1 Enable the Guance and TrueWatch Connector

In "Management / Experimental Features," enable the "Guance and TrueWatch Connector."

Go to "Development / Connectors / Add Connector," select the type as "Guance and TrueWatch," 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.

For functions used for self-built notifications, there are fixed requirements:

1. The function must use @DFF.API(...) decoration and add category='guance.alertFunc'.
2. There is no restriction on the function name, but it must have exactly one parameter event. For details about the parameter value, see the appendix.

As an example, here is the complete code for sending DingTalk notifications:

Sending DingTalk notifications can be configured directly in Guance and TrueWatch without needing a self-built notification target; the code below is only for demonstration purposes and has no practical significance.

Documentation related to DingTalk robots can be found in the appendix.

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 robot Webhook URL
    webhook = 'https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxx'
    # DingTalk robot signature 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 DingTalk robot request
    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 writing the code, don't forget to publish it.

3.3 Confirm the Self-built Notification Target in Guance and TrueWatch

In Guance and TrueWatch's "Monitoring / Notification Target Management," you can see the previously written and published notification target functions in the list.

3.4 Select the Self-built Notification Target in Monitors

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

3.5 Receive Self-built Notifications

Based on the previously written code, we extract the title and content of the event and add an additional line: "This message was sent via a self-built notification target."

Assume that the "Event Content" in the monitor is simply configured as follows:

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

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

X. Appendix

The following is the appendix.

X.1 DingTalk Robot Related Documentation

• Group Robots: https://open.dingtalk.com/document/robots/custom-robot-access
• Group Robot Signature Instructions: https://open.dingtalk.com/document/robots/customize-robot-security-settings

X.2 Parameters of the Event Argument for Self-built Notification Functions

The event argument received by self-built notification functions is a dict with the following fields:

Field Name	Type	Required	Description
timestamp	Integer	Required	Time of generation. Unix timestamp, in 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, such as {"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 at the time of detection trigger
df_monitor_checker_value_dumps	str(JSON)		Value at the time of detection trigger (JSON serialized) Convenient for deserialization
df_event_link	String		Event jump link
df_workspace_uuid	String		UUID of the workspace
df_workspace_name	String		Name of the workspace
Result	Float		Detection value
{Other Additional Fields}			Omitted

Generally speaking, when integrating with 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 Exist issues",
    "df_message"                    : "web001 Exist issues, 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 item 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",
}