Skip to content

Integrate Guance Webhook Custom Alerts

This document primarily describes how to integrate the custom alert notifications of Guance's Webhook.

1. Introduction

In the SaaS version of Guance, email and SMS notifications for monitoring alerts are directly sent using the platform account held by ZYUN Company.

However, in addition to the SaaS version, Guance also supports private deployment (i.e., PaaS version). Since the privately deployed Guance is not under the ZYUN account, it cannot send emails or SMS messages but can be integrated via "Webhook Customization."

Moreover, for those who require special notification channels beyond the existing methods provided by Guance (email, SMS, DingTalk, WeChat), they can also integrate through "Webhook Customization."

2. Details of Guance "Webhook Custom" Alert Notifications

Selecting "Webhook Custom" in Guance's alert notification objects indicates sending notifications via HTTP requests.

Guance's HTTP alert notifications are in the form of a [fixed format POST request], with the request body format being application/json, sent to the configured address.

A typical "Webhook Custom" alert notification [partial content] is as follows:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
POST {Custom Webhook Address}
Content-Type: application/json

{
    "timestamp"                     : 1625638440,
    "df_status"                     : "warning",
    "df_event_id"                   : "event-xxxxxxxxxx",
    "df_title"                      : "web001 Exists",
    "df_message"                    : "web001 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 fields": "Omitted",

    // Below are legacy fields
    "date"          : 1625638440,
    "workspace_uuid": "wksp_xxxxxxxxxx",
    "workspace_name": "My Workspace",
}

Field definitions are as follows:

Field Name Type Required Description
timestamp Integer Required Generated time. Unix timestamp, in seconds
df_status Enum Required Status. 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 (first anomaly value for big data algorithms)
df_monitor_checker_value_dumps str(JSON) Value at the time of detection trigger (JSON serialized)
Convenient for deserialization to obtain original values
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
date Integer [Legacy] Generated time. Unix timestamp, in seconds
workspace_uuid String [Legacy] Belonging workspace UUID
workspace_name String [Legacy] Belonging workspace name

Generally, when integrating with third-party messaging platforms, only the df_title and df_message fields are needed.

3. Integration Method Selection

Based on actual customer scenarios, there are two methods:

Integration Method Overview
Direct Integration Fill in the customer system/third-party system URL directly in the "Webhook Custom" section
DataFlux Func Relay Integration Fill in the DataFlux Func sync API (legacy: authorized link) address in the "Webhook Custom" section,
and use functions written in DataFlux Func to send requests to the customer system/third-party system

The URL refers to the content starting from 'http://', such as: http://api.somedomain.com. Do not write it as a Shell command curl -X POST http://api.somedomain.com

3.1 Direct Integration

That is, when Guance generates an event, it directly sends a fixed-format HTTP request to the customer system/third-party system URL.

Using this method requires that the customer system/third-party system can handle the type of request issued by Guance; see the specific request format in the previous section titled "Details of Guance 'Webhook Custom' Alert Notifications."

If you choose this integration method, then the rest of this document can be ignored as it has no substantial relationship with DataFlux Func.

3.2 DataFlux Func Relay Integration

That is, when Guance generates an event, it sends a fixed-format HTTP request to the DataFlux Func sync API (legacy: authorized link), and then the script written in DataFlux Func sends a request to the customer system/third-party system.

Since most customer systems/third-party systems do not have built-in interfaces for handling "Webhook Custom" notifications from Guance, most situations involve the existence of an interface in the customer system/third-party system but differing from the HTTP request format issued by Guance's "Webhook Custom" method. Therefore, DataFlux Func can be used as a converter between Guance and the customer system/third-party system.

If you adopt this method, the reader should already understand or master the following:

  • Usage of DataFlux Func
  • Basic Python development knowledge

Additionally, appropriate network conditions are required:

  • Guance can access DataFlux Func
  • DataFlux Func can access the third-party message-sending platform

It is recommended to use independently installed DataFlux Func for this integration.

If you insist on using the attached Func version of Guance for this integration, ensure all operations and modifications will not affect Guance. If you are unsure whether it will affect Guance, choose the independently installed Func.

4. Specific Operations for DataFlux Func Relay Integration

This section introduces the specific operations for using DataFlux Func relay integration.

4.1 Overall Processing Logic Flow

The overall processing logic flow for integrating alert notifications is very simple, as shown below:

4.2 Typical Operation Steps

Assume there is a private deployment version of Guance, and you need Guance to send SMS messages via the customer's own SMS platform.

Writing the Integration Function

Assume the customer's SMS platform call method is as follows:

Text Only
1
GET http://some-domain/send-sms?to=13000000000&msg=SMS Body

Then, combining the content above regarding "Guance Alert Notification Details," the following script can be written:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import requests

SMS_API = 'http://some-domain/send-sms'

@DFF.API('Webhook Integration')
def webhook_accept(**event):
    print(f'Event data: {event}')

    params = {
        'to' : '13000000000',
        'msg': event.get('df_title') or 'You have a new event',
    }
    r = requests.get(SMS_API, params=params, timeout=3)
    print(f'Interface return: {r.status_code} {r.text}')

    return r.status_code, r.text

This code uses the requests library as the HTTP client. You can visit the requests official documentation for more detailed information.

After completing and publishing the script, you can add a Sync API (Legacy: Authorized Link) for the function in the "Manage / Sync API (Legacy: Authorized Link)" section of DataFlux Func.

After creating the Sync API (Legacy: Authorized Link), copy the URL in the "Example" section that ends with /s or /simplified.

Do not forget to publish the script; unpublished scripts are drafts and will not take effect.

The URL refers to the content starting from 'http://', such as: http://myfunc.somedomain.com:8088/api/v1/al/auln-xxxxx/s. Do not write it as a Shell command curl -X POST http://myfunc.somedomain.com:8088/api/v1/al/auln-xxxxx/s

Adding Alert Notifications

Go to Guance, select "Manage / Notification Targets Management / Create Notification Target / Webhook Custom", and fill in the Webhook address from the "POST Simplified Request" URL in the previous step.

5. Viewing the Integration Function Run Logs

Functions running via "Sync API (Legacy: Authorized Link)" do not save each task record.

If the integration function is complex and contains many print(...) contents requiring subsequent troubleshooting, you can use "Async API (Legacy: Batch Processing)" instead of "Sync API (Legacy: Authorized Link)."

To view function run logs, simply check each task record directly.

6. Troubleshooting

If notifications are not received despite correct configurations, the following possibilities may exist, which can be checked sequentially:

  1. Guance cannot access DataFlux Func
  2. DataFlux Func cannot access the third-party interface
  3. External reasons such as issues with the third-party interface itself

When troubleshooting, carefully read the interface return information; having a response does not necessarily mean normal operation.

6.1 Guance Cannot Access DataFlux Func

Based on different combinations of Guance and DataFlux Func versions, connectivity between Guance and DataFlux Func can be checked according to the following table:

Guance Version DataFlux Func Version Troubleshooting Method
SaaS Version Independent Deployment Directly access DataFlux Func domain via public network using a browser
PaaS Version Independent Deployment Enter the message-desk-worker container of the PaaS-deployed Guance
Execute curl {DataFlux Func domain}
PaaS Version Built-in DataFlux Func Enter the message-desk-worker container of the PaaS-deployed Guance
Execute curl {DataFlux Func domain}
or curl server-inner.func2:8088 (internal cluster network)

In the case of 'PaaS Guance + Built-in DataFlux Func,' the Webhook URL domain for the notification target must use a domain that can connect to DataFlux Func.

6.2 DataFlux Func Cannot Access Third-Party Interface

Checking DataFlux Func's access to the third-party interface mainly involves the following two steps, both of which must run normally to ensure connectivity:

  1. Directly run the test_webhook_accept() function mentioned in the example within DataFlux Func to check if it runs normally.

  2. Execute the following Shell command to invoke the Sync API (Legacy: Authorized Link):

Bash
1
2
3
curl -X POST -H "application/json" \
    http://{DataFlux Func domain}/api/v1/al/auln-webhook/simplified \
    -d '{"df_title":"Test Webhook Integration"}'

6.3 Issues with the Third-Party Interface Itself or Other External Reasons

These types of problems are numerous and varied, ranging from simple network issues and IP whitelist restrictions to third-party interface bugs.

It is recommended to conduct this problem's investigation last and report the third-party interface's specific behavior and return information to the third-party interface provider.