Skip to content

Self-built Inspection

This document primarily introduces how to use the "Self-built Inspection" script package in the Script Market to implement inspection functions in the self-built DataFlux Func GSE edition.

Always use the latest version of DataFlux Func GSE for operations

This script package will continuously add new features, please always keep an eye on this document page

1. Official Inspection Scripts

  1. Create an API Key for performing operations in the "TrueWatch" section of "Management / API Key Management".
  2. Install "Self-built Inspection" through the "Script Market" in your self-built DataFlux Func.
  3. After installing the corresponding inspection scripts, configure the parameters.

2. Custom Inspection Scripts

To set up a self-built inspection, follow these steps:

  1. Create an API Key for performing operations in the "TrueWatch" section of "Management / API Key Management".
  2. Install the "Self-built Inspection Core Package" via the "Script Market" in your self-built DataFlux Func.
  3. Write custom inspection processing functions in your self-built DataFlux Func.
  4. Through "Management / Scheduled Tasks (Old Version: Automatic Trigger Configuration)" in your self-built DataFlux Func, create scheduled tasks for the written functions (Old Version: Automatic Trigger Configuration).

2.1 Writing Code

A typical self-built inspection processing function is as follows:

Python
 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
28
29
30
31
32
33
34
35
36
37
from guance_monitor__register import self_hosted_monitor
from guance_monitor__event_reporter import EventReporter

API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = None

# Register self-built inspection
@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
@DFF.API('Example of Self-built Inspection')
def run(param1=1, param2=True, param3=None):
    '''
    This is an example of a self-built inspection
    Parameters:
        param1 {int} Parameter 1
        param2 {bool} Parameter 2
        param3 {str} Parameter 3
    '''
    # Generate event reporter
    event_reporter = EventReporter()

    # ... Perform inspection processing and generate data
    event = {
        'title'  : 'Example of Self-built Inspection',
        'message': f'''
            The content of self-built inspections supports Markdown format, such as:

            1. The value of `param1` is `{param1}`
            2. The value of `param2` is `{param2}`
            3. The value of `param3` is `{param3}`
            ''',
        'status'        : 'error',
        'dimension_tags': { 'host': 'my_host' },
    }

    # Use the event reporter to report events
    event_reporter.report(event)

After publishing the script, you can view it in [Management/Scheduled Tasks].

2.2 Code Explanation

The following is a step-by-step explanation of the code in this example.

Import Section

In order to normally use the scripts provided by the Script Market, after installing the script package, you need to introduce these components using the import method.

Python
1
2
from guance_monitor__register import self_hosted_monitor
from guance_monitor__event_reporter import EventReporter

self_hosted_monitor is the decorator for self-built inspection functions; only functions decorated with this decorator will be registered in TrueWatch.

EventReporter is the event reporter used to report event data.

Self-built Inspection Registration, Function Definition Section

For self-built inspections that need to be registered in TrueWatch, they must simultaneously satisfy:

  1. First, decorate using the @self_hosted_monitor decorator.
  2. Then, decorate using the @DFF.API(...) decorator.
Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = None

# Register self-built inspection
@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
@DFF.API('Example of Self-built Inspection')
def run(param1=1, param2=True, param3=None):
    '''
    This is an example of a self-built inspection
    Parameters:
        param1 {int} Parameter 1
        param2 {bool} Parameter 2
        param3 {str} Parameter 3
    '''

Among them:

The decorator @self_hosted_monitor requires the API Key ID and API Key created in the "TrueWatch" section of "Management / API Key Management".

The title specified in the @DFF.API(...) decorator will appear as the title of the self-built inspection after registration.

The content in the function documentation will appear as the documentation on the configuration page of the self-built inspection after registration.

Other TrueWatch Nodes

If you need to connect to a non-default node (Hangzhou) of TrueWatch, you need to additionally pass the parameter of the TrueWatch node name, as shown in the following code example:

Python
1
2
3
4
5
6
API_KEY_ID  = 'xxxxx'
API_KEY     = 'xxxxx'
GUANCE_NODE = 'aws'

@self_hosted_monitor(API_KEY_ID, API_KEY, GUANCE_NODE)
# Omitted ...

The optional values for the GUANCE_NODE parameter can be found in the "Node" column of the table in Manual / Interface and Operations / TrueWatch Node.

For Deployment Plan TrueWatch, you can specify the node using a full URL address, such as:

Python
1
2
3
4
GUANCE_NODE = {
    'open_api': 'http://openapi.mydomain.com',
    'openway' : 'http://openway.mydomain.com',
}

Both OpenAPI access address and OpenWay access address need to be configured

Event Section

The event data to be reported is a simple dict, like:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    event = {
        'dimension_tags': { 'host': 'my_host' },

        'status' : 'error',
        'title'  : 'Example of Self-built Inspection',
        'message': f'''
            The content of self-built inspections supports Markdown format, such as:

            1. The value of `param1` is `{param1}`
            2. The value of `param2` is `{param2}`
            3. The value of `param3` is `{param3}`
            ''',
    }

Specific field definitions are as follows:

Field Type Required Description
title str Required Event title, single-line plain text
message str Required Event content, supports basic Markdown syntax
status str Required Event level
Optional values: info, warning, error, critical, ok
dimension_tags dict Detection dimensions, such as: { "host": "my_host" }

Since DingTalk bots, Lark bots, and WeCom bots do not support all Markdown syntax, please make appropriate choices when specifying the message field.

EventReporter Usage Section

The usage of the event reporter is very simple, but note that the EventReporter object must be instantiated inside the function body.

Correct example:

Python
1
2
3
4
5
6
7
8
@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('Example of Self-built Inspection')
def run(param1=1, param2=True, param3=None):
    event_reporter = EventReporter() # Correct example

    event = { ... }

    event_reporter.report(event)

Incorrect example:

Python
1
2
3
4
5
6
7
8
event_reporter = EventReporter() # Incorrect example

@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('Example of Self-built Inspection')
def run(param1=1, param2=True, param3=None):
    event = { ... }

    event_reporter.report(event)

Additionally, the EventReporter.report(...) method also supports reporting multiple events at once, such as:

Python
1
2
3
4
5
6
7
8
@self_hosted_monitor(API_KEY_ID, API_KEY)
@DFF.API('Example of Self-built Inspection')
def run(param1=1, param2=True, param3=None):
    event_reporter = EventReporter()

    events = [ { ... } ] # Multiple event data as an array

    event_reporter.report(events)

4. Configuring Scheduled Tasks in Self-built DataFlux Func (Old Version: Automatic Trigger Configuration)

After completing and publishing the code, go to "Management / Scheduled Tasks (Old Version: Automatic Trigger Configuration)" in your self-built DataFlux Func to create scheduled tasks (Old Version: Automatic Trigger Configuration) for the function, so that the function actually runs.

After running for some time, you can then view the generated events in TrueWatch.

5. Precautions

When using self-built inspections, pay attention to the following points.

5.1 Association Between Functions and Self-built Inspections

Self-built inspection functions in self-built DataFlux Func will generate association keys based on "Function ID + DataFlux Func Secret Configuration" and associate them with self-built inspections on the TrueWatch platform.

Therefore, if any of the following items are modified, the function will be associated with different self-built inspections:

  • Function name (def xxxx part)
  • Function script ID
  • Function script set ID
  • Different DataFlux Funcs (i.e., different Secrets)

5.2 Function Registration

Functions added with the @self_hosted_monitor decorator will attempt to access TrueWatch and register the function every time they execute.

After registration, the decorator will download the corresponding self-built inspection configurations (parameter specifications) from TrueWatch and run the function with the parameters specified in the self-built inspection configuration, while the parameters configured in the automatic trigger will not take effect.

X. Appendix

X.1 Documentation on Markdown Support for Various IM Platform Bots