Skip to content

Create



POST /api/v1/checker/add

Overview

Create a monitor

Body Parameters

Parameter Type Required Description
type string Monitor type, default trigger, trigger: normal monitor, smartMonitor for intelligent monitor
Allow empty: False
Example: smartMonitor
status integer Monitor status field, 0 enabled, 2 disabled, default enabled status, (2025-02-19 iteration added)
Allow empty: False
Options: [0, 2]
extend json Additional information (Incident related fields and some fields for frontend display)
Allow empty: True
monitorUUID string Group id
Allow empty: True
Allow empty string: True
alertPolicyUUIDs array Alert policy UUID
Allow empty: False
dashboardUUID string Associated dashboard id
Allow empty: False
tags array Tag names for filtering
Allow empty: False
Example: ['xx', 'yy']
secret string Webhook address middle segment unique identifier secret (usually a random uuid, ensuring uniqueness within the workspace)
Allow empty: False
Example: secret_xxxxx
jsonScript json Rule configuration
Allow empty: False
jsonScript.targetWorkspaceUUID None Target workspace, cross-space query, only supports threshold detection type (2025-08-13 iteration added)
Allow empty: False
Allow empty string: 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 Event title
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
Max length: 256
jsonScript.message string Event content
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.recoverTitle string 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 Recovery event message template
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.noDataTitle string 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 No data event message template
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.openNotificationMessage boolean Whether to enable event notification content, default disabled (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 no data event notification content, default disabled (use no data event content as notification content)
Example: False
Allow empty: False
jsonScript.noDataNotificationMessage string No data event notification content
Example: status: {status}, title:{title}
Allow empty: False
Allow empty string: True
jsonScript.noDataRecoverTitle string No data recovery event title template
Example: Monitor: {monitor_name} Checker:{monitor_checker_name} Trigger value:{M1}
Allow empty: False
Allow empty string: True
jsonScript.noDataRecoverMessage string No data recovery event message 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 check frequency
Example: 0 */12 * * *
Allow empty: False
jsonScript.interval integer Query interval, i.e., the time range difference for one query
Example: 60
Allow empty: False
jsonScript.range integer For advanced detection, mutation detection range parameter, unit s
Example: 3600
Allow empty: False
jsonScript.range_2 integer For advanced detection, mutation detection range_2 parameter, unit s, special note (-1 represents chain ratio, 0 represents using periodBefore field)
Example: 600
Allow empty: False
jsonScript.periodBefore integer For advanced detection, mutation detection (yesterday/one hour ago) parameter, unit s
Example: 600
Allow empty: False
jsonScript.recoverNeedPeriodCount integer Specify the number of check periods after which an exception generates a recovery event. If the check frequency is custom customCrontab, this field represents the time length, unit s, otherwise, it represents the number of check frequencies
Example: 60
Allow empty: False
jsonScript.noDataInterval integer How long without data to generate a no data event
Example: 60
Allow empty: False
jsonScript.noDataAction string No data processing operation
Allow empty: False
Options: ['none', 'checkAs0', 'noDataEvent', 'criticalEvent', 'errorEvent', 'warningEvent', 'okEvent', 'noData', 'recover']
jsonScript.checkFuncs array Check function information list
Example: [{'funcId': 'xxx', 'kwargs': {}}]
Allow empty: False
jsonScript.groupBy array Trigger dimension
Example: ['Gender']
Allow empty: False
jsonScript.targets array Check targets
Example: [{'dql': 'M::Soldier Information:(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 disabled false
Example: True
jsonScript.checkerOpt.openMatchTimes boolean Enable continuous trigger judgment, default disabled false
Example: True
jsonScript.checkerOpt.infoEvent boolean Whether to generate info event during continuous normal, default false
Example: True
jsonScript.checkerOpt.diffMode string In advanced detection, mutation detection difference mode, enum value, value, percent
Example: value
Options: ['value', 'percent']
jsonScript.checkerOpt.direction string In advanced detection, mutation detection, interval detection trigger condition direction
Example: up
Options: ['up', 'down', 'both']
jsonScript.checkerOpt.eps float Distance parameter, range: 0 ~ 3.0
Example: 0.5
jsonScript.checkerOpt.threshold json Mutation detection trigger prerequisite settings
Allow empty: False
jsonScript.checkerOpt.threshold.status boolean Y Mutation detection, whether to enable trigger prerequisite condition,
Example: True
jsonScript.checkerOpt.threshold.operator string Y Mutation detection, trigger prerequisite condition operator
Example:
jsonScript.checkerOpt.threshold.value float Y Mutation detection, trigger prerequisite condition detection value
Example: 90
Allow empty: True
jsonScript.checkerOpt.combineExpr string Combined monitoring, combination method
Example: A && B
Allow empty string: False
jsonScript.checkerOpt.ignoreNodata boolean Combined monitoring, whether to ignore no data results (true means need to ignore),
Example: True
jsonScript.checkerOpt.confidenceInterval integer Interval detection V2 new parameter, 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 No data @ account UUID list
Example: ['xx1', 'xx2']
Allow empty: False
jsonScript.subUri string Webhook address suffix (optional setting based on user business needs, no special restrictions)
Example: datakit/push
Allow empty: False
jsonScript.disableCheckEndTime boolean Whether to disable end time limit
Example: True
Allow empty: False
jsonScript.eventChartEnable boolean Whether to enable event chart, default disabled (note only effective when 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 Event chart query statement
Example: M::cpu:(avg(load5s)) BY host
Allow empty: False
openPermissionSet boolean Enable custom permission configuration, (default false: not enabled), when enabled, the operation permissions of this rule are based on permissionSet
Allow empty: False
permissionSet array Operation permission configuration, can configure (role (except owner), member uuid, team uuid)
Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy']
Allow empty: False

Parameter Additional Explanation

Data Explanation.

jsonScript Parameter Explanation

1. Check Type jsonScript.type Explanation

key Explanation
simpleCheck Threshold detection
seniorMutationsCheck Mutation detection
seniorRangeCheck Interval detection
seniorRangeV2Check Interval detection V2
outlierCheck Outlier detection
loggingCheck Log detection
processCheck Process anomaly detection
objectSurvivalCheck Infrastructure survival detection
objectSurvivalV2Check Infrastructure survival detection V2, only supports doris space
objectChangeCheck Infrastructure change detection
apmCheck APM metrics detection
rumCheck RUM metrics detection
securityCheck Security Check 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, APM intelligent detection
smartRumCheck Intelligent monitoring, RUM 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 Explanation
seniorCheck Advanced check, deprecated
mutationsCheck Mutation check, deprecated, updated to seniorMutationsCheck
waterLevelCheck Water level check, deprecated
rangeCheck Interval check, deprecated, updated to seniorRangeCheck

3. **Trigger Condition Comparison Operator Explanation (checkerOpt.rules Parameter Explanation)

Parameter Type Required Explanation
conditions Array[Dict] Required Conditions
conditions[#].alias String Required Detection object alias, i.e., the above targets[#].alias
conditions[#].operator String Required Operator. = , > , < etc.
conditions[#].operands Array[Any] Required Operand array. (between , in etc. operators require multiple operands)
conditionLogic string Required Condition intermediate logic. and , or
status string Required When conditions are met, output event status. Same as event status
direction string [Interval/Water level/Mutation parameter] Detection direction, options: "up", "down", "both"
periodNum integer [Interval/Water level/Mutation parameter] Only detect the most recent data point count
checkPercent integer [Interval parameter] Anomaly percentage threshold, range: 1 ~ 100
checkCount integer [Water level/Mutation parameter] Continuous anomaly point count
strength integer [Water level/Mutation parameter] Detection strength, options: 1=weak, 2=medium, 3=strong
matchTimes integer Enable continuous trigger configuration (checkerOpt.openMatchTimes) continuous trigger configuration count [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/Interval Check jsonScript.type in (simpleCheck, loggingCheck, waterLevelCheck, mutationsCheck, rangeCheck, securityCheck) Parameter Information

Parameter Type Required Explanation
title string Y Output fault event title template
message string N Output fault event message template
recoverTitle string N Output recovery event title template
recoverMessage string N Output recovery event message template
noDataTitle string N Output no data event title template
noDataMessage string N Output no data event message template
noDataRecoverTitle string N Output no data recovery event title template
noDataRecoverMessage string N Output no data recovery event message template
openNotificationMessage boolean N Whether to enable event notification content
notificationMessage string N Event notification content
openNoDataNotificationMessage string N Whether to enable no data event notification content
noDataNotificationMessage string N No data event notification content
name string Y Rule name
type string Y Rule type
every string Y Check frequency, unit (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 After exceeding the specified check period count, generate a recovery event. If the check frequency is custom customCrontab, this field represents the time length, unit s, otherwise, it represents the number of check frequencies
noDataInterval integer N How long without data to generate a no data event
noDataAction string N No data processing 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 disabled false
checkerOpt.openOkConditions boolean N Enable recovery condition configuration, default disabled false

**5. jsonScript.noDataAction Parameter Information **

Parameter Explanation
none No action (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 deprecated on 2024-04-10, its function logic is the same as noDataEvent, can be directly replaced with noDataEvent
recover Trigger recovery event, this parameter was deprecated on 2024-04-10, its function logic is the same as okEvent, can be directly replaced with okEvent

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

Parameter Type Required Explanation
title string Y Output fault event title template
message string N Output fault event message template
recoverTitle string N Output recovery event title template
recoverMessage string N Output recovery event message template
noDataTitle string N Output no data event title template
noDataMessage string N Output no data event message template
noDataRecoverTitle string N Output no data recovery event title template
noDataRecoverMessage string N Output no data recovery event message template
type string Y Rule type
every string Y Check frequency, unit (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 be obtained through 【External Function】List interface, funcTags=monitorType|custom custom check function list
checkFuncs[#].kwargs json N Parameters required by this advanced function

7. Mutation Check seniorMutationsCheck Parameter Explanation

Parameter Type Required Explanation
jsonScript.range integer N Detection metric Result time period1
jsonScript.range_2 integer N Detection metric Result time period2, special note: (-1 represents chain ratio, 0 represents using periodBefore field)
jsonScript.periodBefore integer N When jsonScript.range_2 is 0, this field represents (yesterday/one hour ago)
jsonScript.checkerOpt.diffMode string N Mutation detection difference mode (difference: value, difference percentage: percent
jsonScript.checkerOpt.threshold.status boolean N Mutation detection trigger prerequisite settings, enable/disable
jsonScript.checkerOpt.threshold.operator string N Mutation detection trigger prerequisite settings, operator
jsonScript.checkerOpt.threshold.value float N Mutation detection trigger prerequisite settings, detection value

8. Combined Monitoring Related Field Parameter Explanation

Parameter Type Required Explanation
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 Type Required Explanation
secret string Y A random string of any length, unique within the workspace, used to identify the event's monitor.
jsonScript.subUri string Webhook address suffix (optional setting based on user business needs, no special restrictions)

10. Field disableCheckEndTime Explanation

Reported data TrueWatch processing logic includes append write, update overwrite two modes. According to these two data characteristics, monitoring needs to do detection differentiation. This differentiation scope includes monitor, intelligent monitoring, intelligent inspection all modules. All overwrite update mechanism data types configuration monitor detection, to avoid because monitor execution delay 1 minute leads to update mode data in fixed time range has escape phenomenon, such monitor type detection interval does not specify end time. Involved monitor types: threshold detection, mutation detection, interval detection, outlier detection, process anomaly detection, infrastructure survival detection, RUM metrics detection (individual metrics, see below table)

Data Type Namespace Write Mode
Metrics M Append
Event E Append
Unrecovered Event UE Overwrite
Infrastructure-Object O Overwrite
Infrastructure-Custom Object CO Overwrite
Infrastructure-Object History OH Append
Infrastructure-Custom Object History COH Append
Log / 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 Check S

All write mode is overwrite need to specify disableCheckEndTime as true


11. Interval Detection V2 Version Related Parameter Field Explanation

Parameter Type Required Explanation
jsonScript.checkerOpt.confidenceInterval integer Y Confidence interval range, value 1-100%

12. Monitor Operation Permission Configuration Parameter Explanation

Parameter Type Explanation
openPermissionSet boolean Whether to enable custom permission configuration, default false
permissionSet array Operation permission configuration

**permissionSet, openPermissionSet Field Explanation(2024-06-26 iteration added field): ** When openPermissionSet is enabled, only workspace owner and roles, teams, members in permissionSet configuration can edit/enable/disable/delete When openPermissionSet is disabled (default), then delete/enable/disable/edit permissions follow original interface edit/enable/disable/delete permissions

permissionSet field can configure, 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 Type Explanation
extend.isNeedCreateIssue boolean Whether to associate incident, default not associated
extend.issueDfStatus array Optional 4 types(critical, error, warning, nodata), when issueDfStatus exists: monitor generated event df_status in issueDfStatus will create Issue, when issueDfStatus does not exist, will create Issue
extend.issueLevelUUID string Issue level UUID
extend.manager array Issue creator information (email/workspace member/team) , example: ["[email protected]","acnt_yyyy", "group_"]
extend.needRecoverIssue boolean Whether event recovery needs to synchronously close issue, default false
jsonScript.channels string When isNeedCreateIssue is true, this field is required. issue channel information, example: ["chan_xxx", "chan_yyy"]

Request Example

curl 'https://openapi.truewatch.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":">Level:{status}  \n>Host:{host}  \n>Content:Host SSH Status {{ Result |  to_fixed(2) }}%  \n>Suggestion:Check Host SSH Service Status","noDataMessage":"","noDataTitle":"","recoverNeedPeriodCount":2,"targets":[{"alias":"Result","dql":"M::`ssh`:(count(`ssh_check`)) BY `host`","qtype":"dql"}],"title":"Host {{ host }} SSH Service Exception-Add Alert Policy","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": ">Level:{status}  \n>Host:{host}  \n>Content:Host SSH Status {{ Result |  to_fixed(2) }}%  \n>Suggestion:Check Host SSH Service Status",
            "name": "Host {{ host }} SSH Service Exception-Add Alert Policy",
            "noDataMessage": "",
            "noDataTitle": "",
            "recoverNeedPeriodCount": 2,
            "targets": [
                {
                    "alias": "Result",
                    "dql": "M::`ssh`:(count(`ssh_check`)) BY `host`",
                    "qtype": "dql"
                }
            ],
            "title": "Host {{ host }} SSH Service Exception-Add Alert Policy",
            "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"
}