Skip to content

Create



POST /api/v1/checker/add

Overview

Create a monitor

Body Request Parameters

Parameter Name Type Required Description
type string Monitor type, default trigger, trigger: regular monitor, smartMonitor for intelligent monitoring
Allow empty: False
Example: smartMonitor
status integer Monitor status field, 0 enabled, 2 disabled, default enabled, (added on 2025-02-19)
Allow empty: False
Optional values: [0, 2]
extend json Additional information (Incident related fields and some fields used for frontend display)
Allow empty: True
monitorUUID string Group ID
Allow empty: True
Allow empty string: True
alertPolicyUUIDs array Alert Strategies UUID
Allow empty: False
dashboardUUID string Associated dashboard ID
Allow empty: False
tags array Tag names used for filtering
Allow empty: False
Example: ['xx', 'yy']
secret string Webhook address mid unique identifier secret (usually takes random uuid, ensuring uniqueness within workspace)
Allow empty: False
Example: secret_xxxxx
jsonScript json Rule configuration
Allow empty: False
jsonScript.type string Y Check method type
Example: simpleCheck
Allow empty: False
jsonScript.windowDql string window dql
Allow empty: False
jsonScript.title string Y Generated event title
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
Maximum length: 256
jsonScript.message string Event content
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.recoverTitle string Output recovery event title template
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
jsonScript.recoverMessage string Output recovery event information template
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.noDataTitle string Output no data event title template
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
jsonScript.noDataMessage string Output no data event information template
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.openNotificationMessage boolean Whether to enable, event notification content, default not enabled (use event content as notification content)
Example: False
Allow empty: False
jsonScript.notificationMessage string Event notification content
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
jsonScript.openNoDataNotificationMessage boolean Whether to enable, data interruption event notification content, default not enabled (use data interruption event content as notification content)
Example: False
Allow empty: False
jsonScript.noDataNotificationMessage string Data interruption event notification content
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.noDataRecoverTitle string Output no data recovery upload event title template
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
jsonScript.noDataRecoverMessage string Output no data recovery upload event information template
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.every string Check frequency
Example: 1m
Allow empty: False
jsonScript.customCrontab string Custom detection frequency
Example: 0 */12 * * *
Allow empty: False
jsonScript.interval integer Query interval, i.e., the time range difference of one query
Example: 60
Allow empty: False
jsonScript.range integer Range parameter for advanced detection and mutation detection, unit s
Example: 3600
Allow empty: False
jsonScript.range_2 integer Range_2 parameter for advanced detection and mutation detection, unit s, special note (-1 represents year-on-year, 0 represents using periodBefore field)
Example: 600
Allow empty: False
jsonScript.periodBefore integer Parameter for advanced detection and mutation detection (yesterday/one hour ago), unit s
Example: 600
Allow empty: False
jsonScript.recoverNeedPeriodCount integer Specifies the number of check cycles after which an abnormality generates a recovery event. If the detection frequency is customCrontab, this field indicates the time length, unit s, otherwise, it indicates several detection frequencies
Example: 60
Allow empty: False
jsonScript.noDataInterval integer Time without data that triggers a no-data event
Example: 60
Allow empty: False
jsonScript.noDataAction string No-data handling operation
Allow empty: False
Optional values: ['none', 'checkAs0', 'noDataEvent', 'criticalEvent', 'errorEvent', 'warningEvent', 'okEvent', 'noData', 'recover']
jsonScript.checkFuncs array List of check function information
Example: [{'funcId': 'xxx', 'kwargs': {}}]
Allow empty: False
jsonScript.groupBy array Trigger dimensions
Example: ['Gender']
Allow empty: False
jsonScript.targets array Check targets
Example: [{'dql': 'M::Soldier Info:(AVG(Potential Value)) [::auto] by Gender', 'alias': 'M1'}]
Allow empty: False
jsonScript.checkerOpt json Check condition settings
Allow empty: False
jsonScript.checkerOpt.rules array Trigger condition list
Example: [{'status': 'warning', 'conditions': [{'operands': [60], 'operator': '>', 'alias': 'M1'}], 'conditionLogic': 'and', 'matchTimes': 10}]
Allow empty: False
jsonScript.checkerOpt.openOkConditions boolean Enable graded recovery, default closed false
Example: True
jsonScript.checkerOpt.openMatchTimes boolean Enable continuous trigger judgment, default closed false
Example: True
jsonScript.checkerOpt.infoEvent boolean Whether to generate info events during continuous normal state, default false
Example: True
jsonScript.checkerOpt.diffMode string Difference mode in advanced detection and mutation detection, enumerated values, value, percent
Example: value
Optional values: ['value', 'percent']
jsonScript.checkerOpt.direction string Trigger condition direction in advanced detection and mutation detection, range detection
Example: up
Optional values: ['up', 'down', 'both']
jsonScript.checkerOpt.eps float Distance parameter, value range: 0 ~ 3.0
Example: 0.5
jsonScript.checkerOpt.threshold json Premise condition setting for mutation detection
Allow empty: False
jsonScript.checkerOpt.threshold.status boolean Y Whether to enable premise conditions for mutation detection,
Example: True
jsonScript.checkerOpt.threshold.operator string Y Operation symbol for premise conditions of mutation detection
Example:
jsonScript.checkerOpt.threshold.value float Y Detection value for premise conditions of mutation detection
Example: 90
Allow empty: True
jsonScript.checkerOpt.combineExpr string Combination monitoring, combination method
Example: A && B
Allow empty string: False
jsonScript.checkerOpt.ignoreNodata boolean Combination monitoring, whether to ignore no-data results (true means need to ignore),
Example: True
jsonScript.checkerOpt.confidenceInterval integer New parameter added in V2 range detection, confidence interval range 1-100,
Example: 10
jsonScript.channels array Channel UUID list
Example: ['Name1', 'Name2']
Allow empty: False
jsonScript.atAccounts array Normal detection @ account UUID list
Example: ['xx1', 'xx2']
Allow empty: False
jsonScript.atNoDataAccounts array @ account UUID list in case of no data
Example: ['xx1', 'xx2']
Allow empty: False
jsonScript.subUri string Indicates the address suffix of the Webhook address (can be optionally set according to user business needs, no special restrictions)
Example: datakit/push
Allow empty: False
jsonScript.disableCheckEndTime boolean Whether to disable end time restriction
Example: True
Allow empty: False
jsonScript.eventChartEnable boolean Whether to enable event chart, default disabled (note that it only takes effect when the main storage engine logging is Doris)
Example: False
Allow empty: False
jsonScript.eventCharts array Event chart list
Example: True
Allow empty: False
jsonScript.eventCharts[*] None
jsonScript.eventCharts[*].dql string Query statement for event chart
Example: M::cpu:(avg(load5s)) BY host
Allow empty: False
openPermissionSet boolean Enable custom permission configuration, (default false: not enabled), after enabling, the operation permissions of this rule are based on permissionSet
Allow empty: False
permissionSet array Operation permission configuration, can configure (roles(except owner), member UUID, team UUID)
Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy']
Allow empty: False

Supplementary Parameter Explanation

Data explanation.

jsonScript Parameter Explanation

1. Check type jsonScript.type Explanation

key Description
simpleCheck Threshold detection
seniorMutationsCheck Mutation detection
seniorRangeCheck Range detection
seniorRangeV2Check Range detection V2
outlierCheck Outlier detection
loggingCheck Log detection
processCheck Process anomaly detection
objectSurvivalCheck Infrastructure survival detection
objectSurvivalV2Check Infrastructure survival detection V2, supports only Doris space
objectChangeCheck Infrastructure change detection
apmCheck Application performance metric detection
rumCheck User access metric detection
securityCheck Security inspection anomaly detection
cloudDialCheck Synthetic Testing Anomaly Detection
networkCheck Network data detection
OuterEventChecker External event detection
smartHostCheck Intelligent monitoring, host intelligent detection
smartLogCheck Intelligent monitoring, log intelligent detection
smartApmCheck Intelligent monitoring, application intelligent detection
smartRumCheck Intelligent monitoring, user access intelligent detection
smartKubeCheck Intelligent monitoring, Kubernetes intelligent detection
smartCloudBillingCheck Intelligent monitoring, cloud billing intelligent detection
combinedCheck Combined monitoring

2. Deprecated check types jsonScript.type Explanation

key Description
seniorCheck Advanced check, deprecated
mutationsCheck Mutation check, deprecated, updated to seniorMutationsCheck
waterLevelCheck Water level check, deprecated
rangeCheck Range check, deprecated, updated to seniorRangeCheck

3. **Trigger condition comparison operator explanation (checkerOpt.rules parameter explanation)

Parameter Name type Required Description
conditions Array[Dict] Must Conditions
conditions[#].alias String Must Detection object alias, i.e., the above targets[#].alias
conditions[#].operator String Must Operator. = , > , < etc.
conditions[#].operands Array[Any] Must Operand array. ( between , in etc. operators require multiple operands)
conditionLogic string Must Condition intermediate logic. and , or
status string Must When conditions are met, output event status. Values match event status
direction string 【Range/Water level/Mutation parameters】Detection direction, values: "up", "down", "both"
periodNum integer 【Range/Water level/Mutation parameters】Only detect the most recent data points quantity
checkPercent integer 【Range parameters】 Abnormal percentage threshold, values: 1 ~ 100
checkCount integer 【Water level/Mutation parameters】Continuous abnormal point count
strength integer 【Water level/Mutation parameters】Detection strength, values: 1=weak, 2=medium, 3=strong
matchTimes integer Enable continuous trigger configuration (checkerOpt.openMatchTimes) Continuous trigger configuration times [1,10]
okConditions Array[Dict] Recovery conditions
okConditions[#].alias String Detection object alias, i.e., the above targets[#].alias
okConditions[#].operator String Operator. = , > , < etc.
okConditions[#].operands Array[Any] Operand array. ( between , in etc. operators require multiple operands)

4. Simple/Log/Water level/Mutation/Range check jsonScript.type in (simpleCheck, loggingCheck, waterLevelCheck, mutationsCheck, rangeCheck, securityCheck) Parameter Information

Parameter Name type Required Description
title string Y Output failure event title template
message string N Output failure event information template
recoverTitle string N Output recovery event title template
recoverMessage string N Output recovery event information template
noDataTitle string N Output no data event title template
noDataMessage string N Output no data event information template
noDataRecoverTitle string N Output no data recovery upload event title template
noDataRecoverMessage string N Output no data recovery upload event information template
openNotificationMessage boolean N Whether to enable, event notification content
notificationMessage string N Event notification content
openNoDataNotificationMessage string N Whether to enable, data interruption event notification content
noDataNotificationMessage string N Data interruption event notification content
name string Y Rule name
type string Y Rule type
every string Y Check frequency, unit is (1m/1h/1d)
customCrontab string N Custom check frequency crontab
interval integer Y Data time range difference, i.e., time_range difference, unit: seconds
recoverNeedPeriodCount integer Y Generate recovery event after exceeding specified check cycle counts. If the detection frequency is customCrontab, this field indicates the time length, unit s, otherwise, it indicates several detection frequencies
noDataInterval integer N How long without data to trigger a no-data event
noDataAction string N No-data handling operation
targets array Y Simple check target list
targets[*].dql string Y DQL query statement
targets[*].alias string Y Alias
targets[*].monitorCheckerId string Y Combined monitoring, monitor ID (rul_xxxxx)
checkerOpt json N Check configuration, optional
checkerOpt.rules array Y Check rule list
checkerOpt.openMatchTimes boolean N Whether to enable continuous trigger judgment, default closed false
checkerOpt.openOkConditions boolean N Enable recovery condition configuration, default closed false

5. jsonScript.noDataAction Parameter Information

Parameter Name Description
none No action (i.e., same as [turn off no-data related processing])
checkAs0 Query result treated as 0
noDataEvent Trigger recovery event(noData)
criticalEvent Trigger critical event(crtical)
errorEvent Trigger important event(error)
warningEvent Trigger warning event(warning)
okEvent Trigger recovery event(ok)
noData Generate no-data event, this parameter was discontinued on April 10, 2024, its functional logic is equivalent to noDataEvent, can be directly replaced with noDataEvent
recover Trigger recovery event, this parameter was discontinued on April 10, 2024, its functional logic is equivalent to okEvent, can be directly replaced with okEvent

6. Advanced check jsonScript.type in (seniorCheck) Parameter Information

Parameter Name type Required Description
title string Y Output failure event title template
message string N Output failure event information template
recoverTitle string N Output recovery event title template
recoverMessage string N Output recovery event information template
noDataTitle string N Output no data event title template
noDataMessage string N Output no data event information template
noDataRecoverTitle string N Output no data recovery upload event title template
noDataRecoverMessage string N Output no data recovery upload event information template
type string Y Rule type
every string Y Check frequency, unit is (1m/1h/1d)
customCrontab string N Custom check frequency crontab
checkFuncs array Y Advanced check function list, note it has and only has one element
checkFuncs[#].funcId string Y Function ID, can get custom check function list with funcTags=monitorType|custom via 【External Functions】List interface
checkFuncs[#].kwargs json N Parameter data required by this advanced function

7. Mutation check seniorMutationsCheck Parameter Explanation

Parameter Name type Required Description
jsonScript.range integer N Result time segment 1 of the detection indicator
jsonScript.range_2 integer N Result time segment 2 of the detection indicator, Special Note: (-1 represents year-on-year, 0 represents using periodBefore field)
jsonScript.periodBefore integer N When jsonScript.range_2 is 0, this field indicates (yesterday/one hour ago)
jsonScript.checkerOpt.diffMode string N Difference mode of mutation detection (difference: value, difference percentage: percent
jsonScript.checkerOpt.threshold.status boolean N Premise condition setting for mutation detection, Enable/Disable
jsonScript.checkerOpt.threshold.operator string N Premise condition setting for mutation detection, Operator
jsonScript.checkerOpt.threshold.value float N Premise condition setting for mutation detection, Detection value

8. Combined Monitoring Related Field Parameter Explanation

Parameter Name type Required Description
jsonScript.checkerOpt.combineExpr string Y Combination method, e.g.: A && B
jsonScript.checkerOpt.ignoreNodata boolean N Whether to ignore no-data results (true means need to ignore)

9. External Event Detection jsonScript.type in (OuterEventChecker) Related Field Parameter Explanation

Parameter Name type Required Description
secret string Y Any length random string, unique within workspace, used to identify the monitor of the event.
jsonScript.subUri string Indicates the address suffix of the Webhook address (can be optionally set according to user business needs, no special restrictions)

10. Field disableCheckEndTime Explanation

The processing logic of reported data Guance includes two modes: append write and update overwrite. Based on the characteristics of these two data types, different treatment is needed for monitoring. This distinction applies to all modules including monitors, intelligent monitoring, and intelligent inspections. For all data types configured with the overwrite update mechanism, to avoid the phenomenon where fixed-time-range data escapes due to a 1-minute delay in monitor execution, the detection interval of such monitor types does not specify an end time. Monitors involved: threshold detection, mutation detection, range detection, outlier detection, process anomaly detection, infrastructure survival detection, user access metric detection (some metrics, see the table below)

Data Type Namespace Write Mode
Metrics M Append
Events E Append
Unresolved Events UE Overwrite
Infrastructure - Objects O Overwrite
Infrastructure - Custom Objects CO Overwrite
Infrastructure - Object History OH Append
Infrastructure - Custom Object History COH Append
Logs / Synthetic Tests / CI Visualization L Append
APM - Trace T Append
APM - Profile P Append
RUM - Session R::session Overwrite
RUM - View R::view Overwrite
RUM - Resource R::resource Append
RUM - Long Task R::long_task Append
RUM - Action R::action Append
RUM - Error R::error Append
Security Checks S

All data types with write mode as overwrite need to specify disableCheckEndTime as true.


11. Range Detection V2 Version Related Parameter Field Explanation

Parameter Name type Required Description
jsonScript.checkerOpt.confidenceInterval integer Y Confidence interval range, value range 1-100%

12. Monitor Operation Permission Configuration Parameter Explanation

Parameter Name type Description
openPermissionSet boolean Whether to enable custom permission configuration, default false
permissionSet array Operation permission configuration

**permissionSet, openPermissionSet Field Explanation (Newly added field on June 26, 2024): ** After configuring openPermissionSet, only the space owner and roles, teams, members in the permissionSet configuration can perform editing/enabling/disabling/deleting. When openPermissionSet is turned off (default), deletion/enabling/disabling/editing permissions follow the original interface editing/enabling/disabling/deleting permissions.

permissionSet field can be configured with role UUID(wsAdmin, general, readOnly, role_xxxxx), team UUID(group_yyyy), member UUID(acnt_xxx) permissionSet field example:

  ["wsAdmin", "general", "group_yyyy", "acnt_xxxx"]


13. Associated Incident Configuration Explanation

Parameter Name type Description
extend.isNeedCreateIssue boolean Whether to associate Incident, default not associated
extend.issueDfStatus array Optional 4 types (critical, error, warning, nodata), if issueDfStatus exists: The df_status of events generated by the monitor in issueDfStatus will create Issue, if issueDfStatus does not exist, all will create Issues
extend.issueLevelUUID string Issue level UUID
extend.manager array Responsible person information when creating Issue (email/space member/team), Example: ["xxx@guance.com","acnt_yyyy", "group_"]
extend.needRecoverIssue boolean Whether event recovery needs to close Issue synchronously, default false
jsonScript.channels string When isNeedCreateIssue is true, this field is mandatory. Issue channel information, Example: ["chan_xxx", "chan_yyy"]

Request Example

curl 'https://openapi.guance.com/api/v1/checker/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"extend":{"funcName":"","isNeedCreateIssue":false,"issueLevelUUID":"","needRecoverIssue":false,"querylist":[{"datasource":"dataflux","qtype":"dql","query":{"alias":"","code":"Result","dataSource":"ssh","field":"ssh_check","fieldFunc":"count","fieldType":"float","funcList":[],"groupBy":["host"],"groupByTime":"","namespace":"metric","q":"M::`ssh`:(count(`ssh_check`)) BY `host`","type":"simple"},"uuid":"aada629a-672e-46f9-9503-8fd61065c382"}],"rules":[{"conditionLogic":"and","conditions":[{"alias":"Result","operands":["90"],"operator":">="}],"status":"critical"},{"conditionLogic":"and","conditions":[{"alias":"Result","operands":["0"],"operator":">="}],"status":"error"}]},"jsonScript":{"atAccounts":[],"atNoDataAccounts":[],"channels":[],"checkerOpt":{"infoEvent":false,"rules":[{"conditionLogic":"and","conditions":[{"alias":"Result","operands":["90"],"operator":">="}],"status":"critical"},{"conditionLogic":"and","conditions":[{"alias":"Result","operands":["0"],"operator":">="}],"status":"error"}]},"disableCheckEndTime":false,"every":"1m","groupBy":["host"],"interval":300,"message":">等级:{status}  \n>主机:{host}  \n>内容:主机 SSH 状态 {{ Result |  to_fixed(2) }}%  \n>建议:检查主机 SSH 服务状态","noDataMessage":"","noDataTitle":"","recoverNeedPeriodCount":2,"targets":[{"alias":"Result","dql":"M::`ssh`:(count(`ssh_check`)) BY `host`","qtype":"dql"}],"title":"主机 {{ host }} SSH 服务异常-添加告警策略","type":"simpleCheck"},"alertPolicyUUIDs":["altpl_xxxx32","altpl_xxxx32"]}' \
--compressed 

Response

{
    "code": 200,
    "content": {
        "alertPolicyUUIDs": [
            "altpl_xxxx32",
            "altpl_xxxx32"
        ],
        "createAt": 1710831393,
        "createdWay": "manual",
        "creator": "wsak_xxxx",
        "crontabInfo": {
            "crontab": "*/1 * * * *",
            "id": "cron-2n8ZyrMWKXB8"
        },
        "declaration": {
            "b": [
                "asfawfgajfasfafgafwba",
                "asfgahjfaf"
            ],
            "business": "aaa",
            "organization": "64fe7b4062f74d0007b46676"
        },
        "deleteAt": -1,
        "extend": {
            "funcName": "",
            "isNeedCreateIssue": false,
            "issueLevelUUID": "",
            "needRecoverIssue": false,
            "querylist": [
                {
                    "datasource": "dataflux",
                    "qtype": "dql",
                    "query": {
                        "alias": "",
                        "code": "Result",
                        "dataSource": "ssh",
                        "field": "ssh_check",
                        "fieldFunc": "count",
                        "fieldType": "float",
                        "funcList": [],
                        "groupBy": [
                            "host"
                        ],
                        "groupByTime": "",
                        "namespace": "metric",
                        "q": "M::`ssh`:(count(`ssh_check`)) BY `host`",
                        "type": "simple"
                    },
                    "uuid": "aada629a-672e-46f9-9503-8fd61065c382"
                }
            ],
            "rules": [
                {
                    "conditionLogic": "and",
                    "conditions": [
                        {
                            "alias": "Result",
                            "operands": [
                                "90"
                            ],
                            "operator": ">="
                        }
                    ],
                    "status": "critical"
                },
                {
                    "conditionLogic": "and",
                    "conditions": [
                        {
                            "alias": "Result",
                            "operands": [
                                "0"
                            ],
                            "operator": ">="
                        }
                    ],
                    "status": "error"
                }
            ]
        },
        "id": null,
        "isLocked": false,
        "jsonScript": {
            "atAccounts": [],
            "atNoDataAccounts": [],
            "channels": [],
            "checkerOpt": {
                "infoEvent": false,
                "rules": [
                    {
                        "conditionLogic": "and",
                        "conditions": [
                            {
                                "alias": "Result",
                                "operands": [
                                    "90"
                                ],
                                "operator": ">="
                            }
                        ],
                        "status": "critical"
                    },
                    {
                        "conditionLogic": "and",
                        "conditions": [
                            {
                                "alias": "Result",
                                "operands": [
                                    "0"
                                ],
                                "operator": ">="
                            }
                        ],
                        "status": "error"
                    }
                ]
            },
            "disableCheckEndTime": false,
            "every": "1m",
            "groupBy": [
                "host"
            ],
            "interval": 300,
            "message": ">等级:{status}  \n>主机:{host}  \n>内容:主机 SSH 状态 {{ Result |  to_fixed(2) }}%  \n>建议:检查主机 SSH 服务状态",
            "name": "主机 {{ host }} SSH 服务异常-添加告警策略",
            "noDataMessage": "",
            "noDataTitle": "",
            "recoverNeedPeriodCount": 2,
            "targets": [
                {
                    "alias": "Result",
                    "dql": "M::`ssh`:(count(`ssh_check`)) BY `host`",
                    "qtype": "dql"
                }
            ],
            "title": "主机 {{ host }} SSH 服务异常-添加告警策略",
            "type": "simpleCheck"
        },
        "monitorName": "default",
        "monitorUUID": "monitor_xxxx32",
        "refKey": "",
        "secret": "",
        "status": 0,
        "tagInfo": [],
        "type": "trigger",
        "updateAt": null,
        "updator": null,
        "uuid": "rul_xxxx32",
        "workspaceUUID": "wksp_xxxx32"
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-014A6CF1-E9D8-4EA7-9527-D3C39CC3A94A"
} 

Feedback

Is this page helpful? ×