Create¶
POST /api/v1/checker/add
Overview¶
Create a Monitor
Body Request Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| configVersion | integer | The current configuration version, required for V2 modifications; returns 409 if expired. Not required by the legacy OpenAPI. $minValue: 1 |
|
| generationId | string | Candidate credential newly created or regenerated by Front AI; obtained from the response header of the generation API |
|
| queryType | string | DQL frontend echo mode used and validated when extend.querylist is not passed. simple indicates that Studio parses and injects the simple-mode fields; dql indicates DQL text mode. Default: dql. When extend.querylist is explicitly passed, it is used as-is with priority and the injection semantics of queryType are ignored. If simple conversion fails, it automatically falls back to dql without changing the DQL actually executed in jsonScript.targetsAllow empty: False Example: simple |
|
| type | string | Monitor type. Default: trigger. trigger: regular Monitor; aiMonitor: AI semantic monitor; smartMonitor: Smart MonitoringAllow empty: False Example: smartMonitor |
|
| status | integer | Monitor status field. 0: enabled; 2: disabled; enabled by default. (Added in the 2025-02-19 iteration)Allow empty: False Allowed values: [0, 2] |
|
| extend | json | Additional information (Incident-related fields and some fields for frontend echo) Allow empty: True |
|
| alertPolicyUUIDs | array | Alert Policy 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 | The unique secret in the middle segment of the Webhook URL (usually a random UUID to ensure uniqueness within the workspace)Allow empty: False Example: secret_xxxxx |
|
| jsonScript | json | Rule configuration Allow empty: False |
|
| jsonScript.targetWorkspaceUUID | string | Target workspace for cross-workspace queries; only supports threshold detection types (Added in the 2025-08-13 iteration) 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 | Title of the generated event 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 | Template for the recovery event title Example: Monitor: {{monitor_name}} Checker: {{monitor_checker_name}} Trigger value: {{M1}} Allow empty: False Allow empty string: True |
|
| jsonScript.recoverMessage | string | Template for the recovery event message Example: status: {{status}}, title: {{title}} Allow empty: False Allow empty string: True |
|
| jsonScript.noDataTitle | string | Template for the no-data event title Example: Monitor: {{monitor_name}} Checker: {{monitor_checker_name}} Trigger value: {{M1}} Allow empty: False Allow empty string: True |
|
| jsonScript.noDataMessage | string | Template for the no-data event message Example: status: {{status}}, title: {{title}} Allow empty: False Allow empty string: True |
|
| jsonScript.openNotificationMessage | boolean | Whether to enable the event notification content. Disabled by default (the event content is used as the 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 the no-data event notification content. Disabled by default (the no-data event content is used as the 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 | Template for the no-data recovery event title Example: Monitor: {{monitor_name}} Checker: {{monitor_checker_name}} Trigger value: {{M1}} Allow empty: False Allow empty string: True |
|
| jsonScript.noDataRecoverMessage | string | Template for the no-data recovery event message 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.delaySeconds | integer | Data waiting window for regular Monitors, in seconds; 0 means no waiting. Not supported by Smart MonitoringExample: 60 Allow empty: False Allowed values: [0, 60, 120, 180, 300, 600, 900, 1800] |
|
| jsonScript.interval | integer | Query interval, i.e., the time range span of a single query Example: 60 Allow empty: False |
|
| jsonScript.range | integer | The range parameter for advanced detection and mutation detection, in secondsExample: 3600 Allow empty: False |
|
| jsonScript.range_2 | integer | The range_2 parameter for advanced detection and mutation detection, in seconds. Special notes: -1 indicates period-over-period comparison; 0 indicates using the periodBefore fieldExample: 600 Allow empty: False |
|
| jsonScript.periodBefore | integer | The (yesterday / one hour ago) parameter for advanced detection and mutation detection, in seconds Example: 600 Allow empty: False |
|
| jsonScript.recoverNeedPeriodCount | integer | Specifies after how many check periods a recovery event is generated. If the detection frequency is a custom customCrontab, this field represents a time length in seconds; otherwise, it represents the number of detection frequenciesExample: 60 Allow empty: False |
|
| jsonScript.noDataInterval | integer | How long data can be absent before a no-data event is generated Example: 60 Allow empty: False |
|
| jsonScript.noDataAction | string | No-data handling action Allow empty: False Allowed values: ['none', 'checkAs0', 'noDataEvent', 'fatalEvent', '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: ['性别'] Allow empty: False |
|
| jsonScript.targets | array | Check targets Example: [{'dql': 'M:: 士兵信息:(AVG(潜力值)) [::auto] by 性别', 'alias': 'M1'}] Allow empty: False |
|
| jsonScript.checkerOpt | json | Check condition settings Allow empty: False |
|
| jsonScript.checkerOpt.enableStreamingAggregation | boolean | Monitor streaming aggregation acceleration. When absent or null, follows the workspace setting; true enables it independently; false disables it independentlyAllow empty: True |
|
| jsonScript.checkerOpt.yamlConfig | string | Full V2 source YAML text, up to 256 KiB. It is not a JSON object and must not be wrapped in Markdown fences |
|
| jsonScript.checkerOpt.disableLargeScaleEventProtect | boolean | Whether to disable large-scale event protection. Default: falseExample: True |
|
| jsonScript.checkerOpt.script | string | Script content for programmable monitoring Allow empty: False Allow empty string: True |
|
| jsonScript.checkerOpt.rules | array | List of trigger conditions Example: [{'status': 'warning', 'conditions': [{'operands': [60], 'operator': '>', 'alias': 'M1'}], 'conditionLogic': 'and', 'matchTimes': 10}] Allow empty: False |
|
| jsonScript.checkerOpt.openOkConditions | boolean | Enable graded recovery. Disabled by default (false)Example: True |
|
| jsonScript.checkerOpt.openMatchTimes | boolean | Enable consecutive trigger judgment. Disabled by default (false)Example: True |
|
| jsonScript.checkerOpt.infoEvent | boolean | Whether to generate info events while the status remains continuously normal. Default: falseExample: True |
|
| jsonScript.checkerOpt.infoEventCondition | json | Condition for generating info events; supported only by threshold Monitors. An empty object means the event is generated unconditionally Example: {'alias': 'M1', 'operator': '>=', 'operands': [60]} Allow empty: False |
|
| jsonScript.checkerOpt.infoEventCondition.alias | string | Alias of the judgment target |
|
| jsonScript.checkerOpt.infoEventCondition.operator | string | Judgment operator |
|
| jsonScript.checkerOpt.infoEventCondition.operands | array | List of judgment operands |
|
| jsonScript.checkerOpt.diffMode | string | Difference mode for mutation detection in advanced detection. Enum values: value, percentExample: value Allowed values: ['value', 'percent'] |
|
| jsonScript.checkerOpt.direction | string | Trigger condition direction for mutation detection and range detection in advanced detection Example: up Allowed values: ['up', 'down', 'both'] |
|
| jsonScript.checkerOpt.eps | float | Distance parameter. Value range: 0 ~ 3.0 Example: 0.5 |
|
| jsonScript.checkerOpt.threshold | json | Trigger precondition settings for mutation detection Allow empty: False |
|
| jsonScript.checkerOpt.threshold.status | boolean | Y | Whether the mutation detection trigger precondition is enabled Example: True |
| jsonScript.checkerOpt.threshold.operator | string | Y | Operator of the mutation detection trigger precondition Example: |
| jsonScript.checkerOpt.threshold.value | float | Y | Detection value of the mutation detection trigger precondition Example: 90 Allow empty: True |
| jsonScript.checkerOpt.combineExpr | string | Combination expression for combined monitoring Example: A && B Allow empty string: False |
|
| jsonScript.checkerOpt.ignoreNodata | boolean | Whether to ignore no-data results in combined monitoring (true means they should be ignored)Example: True |
|
| jsonScript.checkerOpt.confidenceInterval | integer | New parameter for Range Detection V2. Confidence interval range: 1-100 Example: 10 |
|
| jsonScript.checkerOpt.category | string | AI monitoring category metadata Allow empty: False |
|
| jsonScript.checkerOpt.userPrompt | string | AI user prompt. Cannot be empty when provided. Up to 20,000 characters Allow empty: False Allow empty string: True Max length: 20000 |
|
| jsonScript.checkerOpt.systemPrompt | string | AI system prompt. Cannot be empty when provided. Up to 20,000 characters Allow empty: False Allow empty string: True Max length: 20000 |
|
| jsonScript.checkerOpt.mentions | array | List of DQL references. Each item must include type=dql, namespace, and datasource; index is optional and should be filled in when logs are selected. Up to 20,000 characters after serializationAllow empty: False |
|
| jsonScript.checkerOpt.mentions[*] | None | ||
| jsonScript.checkerOpt.mentions[*].type | string | Y | Datasource type Allowed values: ['dql'] |
| jsonScript.checkerOpt.mentions[*].namespace | string | Y | DQL namespace Allow empty string: False |
| jsonScript.checkerOpt.mentions[*].index | string | DQL index; fill in when logs are selected Allow empty string: False |
|
| jsonScript.checkerOpt.mentions[*].datasource | string | Y | DQL datasource Allow empty string: False |
| jsonScript.checkerOpt.model | string | Model used for this detection Allow empty: False |
|
| jsonScript.checkerOpt.contextWindowLimit | integer | Context window token limit; must be greater than 0 Allow empty: False $minValue: 1 |
|
| jsonScript.checkerOpt.maxChatRounds | integer | Maximum number of chat rounds; must be greater than or equal to 1 Allow empty: False $minValue: 1 |
|
| jsonScript.checkerOpt.maxDQLQueries | integer | Maximum number of DQL queries; must be greater than or equal to 0 Allow empty: False $minValue: 0 |
|
| jsonScript.checkerOpt.creditSoftBudget | number | Soft credit budget per detection; must be greater than 0 Allow empty: False |
|
| jsonScript.channels | array | List of channel UUIDs Example: ['名称1', '名称2'] Allow empty: False |
|
| jsonScript.atAccounts | array | List of account UUIDs to @-mention during normal detection Example: ['xx1', 'xx2'] Allow empty: False |
|
| jsonScript.atNoDataAccounts | array | List of account UUIDs to @-mention when there is no data Example: ['xx1', 'xx2'] Allow empty: False |
|
| jsonScript.subUri | string | Webhook URL suffix for OuterEventChecker. Required when creating; uniqueness is not requiredExample: datakit/push Allow empty: False |
|
| jsonScript.isChangeEvent | boolean | Whether OuterEventChecker is treated as a change event. Default: false; existing rules missing this field are also treated as falseExample: False Allow empty: False |
|
| jsonScript.disableCheckEndTime | boolean | Whether to disable the end time restriction Example: True Allow empty: False |
|
| jsonScript.eventChartEnable | boolean | Whether to enable event charts. Disabled by default (Note: only takes effect when the primary storage engine for logging is Doris) Example: False Allow empty: False |
|
| jsonScript.eventCharts | array | List of event charts Example: True Allow empty: False |
|
| jsonScript.eventCharts[*] | None | ||
| jsonScript.eventCharts[*].dql | string | Query statement of the event chart Example: M:: cpu:(avg(load5s)) BY host Allow empty: False |
|
| openPermissionSet | boolean | Enable custom permission configuration. Default: false (disabled). Once enabled, the operation permissions of this rule are based on permissionSetAllow empty: False |
|
| permissionSet | array | Operation permission configuration. Can include roles (except the owner), member UUIDs, and team UUIDs Example: ['wsAdmin', 'acnt_xxxx', 'group_yyyy'] Allow empty: False |
Supplementary Parameter Notes¶
Before saving, basic Jinja2 syntax parsing is performed on jsonScript.message and, for applicable Monitors, jsonScript.noDataMessage. Templates, DQL, and variables/functions/filters are not executed.
Syntax errors return HTTP 406 with ft.InvalidParameterV2; content includes field (field path), line (line number starting from 1), and reason (reason for the parsing error).
The no-data content check does not apply to object survival, object change, programmable, Smart Monitoring, or AI semantic Monitors. Titles, custom notification content, and recovery templates are not covered by this syntax check. Additional Jinja2 extensions are not enabled by default.
Smart Monitoring V2 uses the outer type=smartMonitor, jsonScript.type=smartMonitorV2Check, and checkerOpt.yamlConfig.
It runs every 10 minutes, and queries come only from the YAML. Modifications are limited to DQL, existing threshold configurations, and existing public algorithm parameters. Rule sets, algorithm types, dimensions, time, and templates cannot be modified.
extend.smartMonitor stores the source, prompt, and server-side configuration version. Front rejects old-version creation, import, and editing. Existing instances can still be deleted and enabled/disabled. Legacy OpenAPI capabilities remain compatible.
Data Notes.
jsonScript parameter notes
1. Check type jsonScript.type
| 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; only supports Doris workspaces |
| objectChangeCheck | Infrastructure change detection |
| apmCheck | APM metric detection |
| rumCheck | RUM metric detection |
| securityCheck | Security check anomaly detection |
| cloudDialCheck | Synthetic testing anomaly detection |
| networkCheck | Network data detection |
| OuterEventChecker | External event detection |
| smartHostCheck | Smart Monitoring: host intelligent detection |
| smartLogCheck | Smart Monitoring: log intelligent detection |
| smartApmCheck | Smart Monitoring: application intelligent detection |
| smartRumCheck | Smart Monitoring: RUM intelligent detection |
| smartKubeCheck | Smart Monitoring: Kubernetes intelligent detection |
| smartCloudBillingCheck | Smart Monitoring: cloud billing intelligent detection |
| combinedCheck | Combined monitoring |
| programmableCheck | Programmable Monitor |
| aiMonitor | AI semantic Monitor; saved as an independent Rule.type=aiMonitor and executed by Func scheduled tasks |
2. Retired check types jsonScript.type
| key | Description |
|---|---|
| seniorCheck | Advanced check, retired |
| mutationsCheck | Mutation check, retired; replaced by seniorMutationsCheck |
| waterLevelCheck | Water level check, retired |
| rangeCheck | Range check, retired; replaced by seniorRangeCheck |
3. Trigger condition comparison operators (parameters in checkerOpt.rules)
| Parameter | Type | Required | Description |
|---|---|---|---|
| conditions | Array[Dict] | Required | Conditions |
| conditions[#].alias | String | Required | Alias of the detection target, i.e., targets[#].alias above |
| conditions[#].operator | String | Required | Operator: =, >, <, etc. |
| conditions[#].operands | Array[Any] | Required | Array of operands. Operators such as between and in require multiple operands |
| conditionLogic | string | Required | Logic between conditions: and, or |
| status | string | Required | The status of the event output when the conditions are met. Values are the same as the event status |
| direction | string | [Range/water level/mutation parameters] Detection direction. Values: up, down, both |
|
| periodNum | integer | [Range/water level/mutation parameters] Only check the number of the most recent data points | |
| checkPercent | integer | [Range parameters] Abnormal percentage threshold. Values: 1 ~ 100 | |
| checkCount | integer | [Water level/mutation parameters] Number of consecutive abnormal points | |
| strength | integer | [Water level/mutation parameters] Detection strength. Values: 1=weak, 2=medium, 3=strong | |
| matchTimes | integer | Number of consecutive triggers when consecutive trigger configuration (checkerOpt.openMatchTimes) is enabled. Range: [1,10] |
|
| okConditions | Array[Dict] | Recovery conditions | |
| okConditions[#].alias | String | Alias of the detection target, i.e., targets[#].alias above |
|
| okConditions[#].operator | String | Operator: =, >, <, etc. |
|
| okConditions[#].operands | Array[Any] | Array of operands. Operators such as between and in require multiple operands |
4. Parameters for simple/log/water level/mutation/range checks (jsonScript.type in (simpleCheck, loggingCheck, waterLevelCheck, mutationsCheck, rangeCheck, securityCheck))
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Y | Template for the fault event title |
| message | string | N | Template for the fault event message |
| recoverTitle | string | N | Template for the recovery event title |
| recoverMessage | string | N | Template for the recovery event message |
| noDataTitle | string | N | Template for the no-data event title |
| noDataMessage | string | N | Template for the no-data event message |
| noDataRecoverTitle | string | N | Template for the no-data recovery event title |
| noDataRecoverMessage | string | N | Template for the no-data recovery event message |
| openNotificationMessage | boolean | N | Whether to enable the event notification content |
| notificationMessage | string | N | Event notification content |
| openNoDataNotificationMessage | string | N | Whether to enable the 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. Units: (1m/1h/1d) |
| customCrontab | string | N | Crontab for custom check frequency |
| delaySeconds | integer | N | Data waiting window, in seconds. Supported values: 0, 60, 120, 180, 300, 600, 900, 1800. Default: 0 |
| interval | integer | Y | Time offset of the data time range, i.e., the time_range offset, in seconds |
| recoverNeedPeriodCount | integer | Y | Generate a recovery event after the specified number of check periods. If the detection frequency is a custom customCrontab, this field represents a time length in seconds; otherwise, it represents the number of detection frequencies |
| noDataInterval | integer | N | How long data can be absent before a no-data event is generated |
| noDataAction | string | N | No-data handling action |
| targets | array | Y | List of check targets in simple checks |
| targets[*].dql | string | Y | DQL query statement |
| targets[*].alias | string | Y | Alias |
| targets[*].monitorCheckerId | string | Y | Monitor ID for combined monitoring (rul_xxxxx) |
| checkerOpt | json | N | Check configuration, optional |
| checkerOpt.rules | array | Y | List of check rules |
| checkerOpt.openMatchTimes | boolean | N | Whether to enable consecutive trigger judgment. Disabled by default (false) |
| checkerOpt.openOkConditions | boolean | N | Whether to enable recovery condition configuration. Disabled by default (false) |
| checkerOpt.disableLargeScaleEventProtect | boolean | N | Whether to disable large-scale event protection. Default: false |
For a regular simpleCheck, jsonScript.targets are the actual execution targets. Target aliases must be unique and consistent with the references in the check conditions. Multiple query nodes required for editing or echo should be placed in extend.querylist. combinedCheck follows the existing multi-target semantics of combined monitoring.
5. jsonScript.noDataAction parameter values
| Parameter | Description |
|---|---|
| none | No action (same as disabling no-data handling) |
| checkAs0 | Treat the query result as 0 |
| noDataEvent | Trigger a recovery event (noData) |
| fatalEvent | Trigger a fatal event (fatal) |
| criticalEvent | Trigger a critical event (critical) |
| errorEvent | Trigger an error event (error) |
| warningEvent | Trigger a warning event (warning) |
| okEvent | Trigger a recovery event (ok) |
| noData | Generate a no-data event. This parameter was retired on 2024-04-10. Its functionality is equivalent to noDataEvent and can be directly replaced with noDataEvent |
| recover | Trigger a recovery event. This parameter was retired on 2024-04-10. Its functionality is equivalent to okEvent and can be directly replaced with okEvent |
6. Parameters for advanced checks (jsonScript.type in (seniorCheck))
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Y | Template for the fault event title |
| message | string | N | Template for the fault event message |
| recoverTitle | string | N | Template for the recovery event title |
| recoverMessage | string | N | Template for the recovery event message |
| noDataTitle | string | N | Template for the no-data event title |
| noDataMessage | string | N | Template for the no-data event message |
| noDataRecoverTitle | string | N | Template for the no-data recovery event title |
| noDataRecoverMessage | string | N | Template for the no-data recovery event message |
| type | string | Y | Rule type |
| every | string | Y | Check frequency. Units: (1m/1h/1d) |
| customCrontab | string | N | Crontab for custom check frequency |
| delaySeconds | integer | N | Data waiting window, in seconds. Supported values: 0, 60, 120, 180, 300, 600, 900, 1800. Default: 0 |
| checkFuncs | array | Y | List of advanced check functions. Note: it contains exactly one element |
| checkFuncs[#].funcId | string | Y | Function ID. You can obtain the list of custom check functions with funcTags=monitorType|custom via the List External Functions API |
| checkFuncs[#].kwargs | json | N | Parameter data required by this advanced function |
7. Parameters for mutation check seniorMutationsCheck
| Parameter | Type | Required | Description |
|---|---|---|---|
| jsonScript.range | integer | N | Result time period 1 of the detection metric |
| jsonScript.range_2 | integer | N | Result time period 2 of the detection metric. Special notes: (-1 indicates period-over-period comparison; 0 indicates using the periodBefore field) |
| jsonScript.periodBefore | integer | N | When jsonScript.range_2 is 0, this field represents (yesterday / one hour ago) |
| jsonScript.checkerOpt.diffMode | string | N | Difference mode for mutation detection (difference: value; difference percentage: percent) |
| jsonScript.checkerOpt.threshold.status | boolean | N | Trigger precondition settings for mutation detection: enabled/disabled |
| jsonScript.checkerOpt.threshold.operator | string | N | Trigger precondition settings for mutation detection: operator |
| jsonScript.checkerOpt.threshold.value | float | N | Trigger precondition settings for mutation detection: detection value |
8. Parameters for combined monitoring fields
| Parameter | Type | Required | Description |
|---|---|---|---|
| jsonScript.checkerOpt.combineExpr | string | Y | Combination expression, e.g., A && B |
| jsonScript.checkerOpt.ignoreNodata | boolean | N | Whether to ignore no-data results (true means they should be ignored) |
9. Parameters for external event detection (jsonScript.type in (OuterEventChecker))
| Parameter | Type | Required | Description |
|---|---|---|---|
| secret | string | N | Used to identify the Monitor to which an event belongs. Globally unique. If omitted during creation, Studio generates it; Import does not reuse old values. |
| jsonScript.subUri | string | Y | Webhook URL suffix. Required when creating. Uniqueness is not required. |
| jsonScript.isChangeEvent | boolean | N | Whether to treat as a change event. Default: false; existing rules missing this field are also treated as false. |
Parameters for AI semantic Monitors with jsonScript.type=aiMonitor
The AI semantic Monitor is an independent Rule.type=aiMonitor type. It reuses the checker APIs for creating, modifying, enabling/disabling, and deleting, as well as the permission and lifecycle logic of Smart Monitoring. Tags use the independent AiCheckerRefTagObject association type. Studio creates/modifies Func scheduled tasks for it, which always call guance__api.ai_monitor.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jsonScript.title | string | Y | Monitor name; reuses the existing checker request field and is passed as Func checker_opt.name |
| jsonScript.every | string | Y | Check frequency; supports the existing s/m/h period formats. It is recommended to be no less than 30 minutes |
| jsonScript.customCrontab | string | N | Custom Cron expression; reuses existing checker validation |
| jsonScript.checkerOpt.userPrompt | string | Y | AI user prompt. Cannot be empty after trimming leading/trailing whitespace. Up to 20,000 characters |
| jsonScript.checkerOpt.systemPrompt | string | N | AI system prompt. Cannot be empty after trimming leading/trailing whitespace. Up to 20,000 characters |
| jsonScript.checkerOpt.category | string | N | AI monitoring category metadata |
| jsonScript.checkerOpt.infoEvent | boolean | N | Whether to generate info events. Default: false |
| jsonScript.checkerOpt.mentions | array | N | List of DQL references. Default: []. Up to 20,000 characters after serialization. Each item has type fixed to dql and requires non-empty namespace and datasource; fill in index when logs are selected |
| jsonScript.checkerOpt.model | string | N | Model identifier; when absent, Func uses the default model |
| jsonScript.checkerOpt.contextWindowLimit | integer | N | Context window limit; must be greater than 0 |
| jsonScript.checkerOpt.maxChatRounds | integer | N | Maximum number of chat rounds; must be greater than or equal to 1 |
| jsonScript.checkerOpt.maxDQLQueries | integer | N | Maximum number of DQL queries; must be greater than or equal to 0 |
| jsonScript.checkerOpt.creditSoftBudget | number | N | AI soft budget; must be greater than 0 |
checker_opt.id in the Func input parameters is filled by Studio using the Rule UUID. workspace_agent_api_key uses the workspace AI general-purpose system AK prefixed with the current site. Workspace token rotation only updates workspace_token and does not rotate this built-in AK. Data delay uses Func's CUSTOM_DB_DATA_DELAY instead of the regular Monitor's delaySeconds.
10. The disableCheckEndTime field
The processing logic of TrueWatch for reported data includes two modes: append-write and update-overwrite. Based on the characteristics of these two data types, monitoring must treat detection differently. This distinction covers all modules, including Monitors, Smart Monitoring, and Intelligent Inspection.
When Monitor detection is configured for all data types that use the update-overwrite mechanism, to prevent data in update mode from escaping the fixed time range due to the Monitor's 1-minute delay, the detection interval for these Monitor types does not specify an end time.
Monitor types involved: threshold detection, mutation detection, range detection, outlier detection, process anomaly detection, infrastructure survival detection, and RUM metric detection (a few metrics; see the table below).
| Data Type | Namespace | Write Mode |
|---|---|---|
| Metrics | M | Append |
| Events | E | Append |
| Unrecovered 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 Monitoring / CI Visualization | L | Append |
| APM traces | T | Append |
| APM profiles | P | Append |
| RUM sessions | R::session | Overwrite |
| RUM views | R::view | Overwrite |
| RUM resources | R::resource | Append |
| RUM long tasks | R::long_task | Append |
| RUM actions | R::action | Append |
| RUM errors | R::error | Append |
| Security Check | S |
All data types with write mode Overwrite must set disableCheckEndTime to true.
11. Fields for Range Detection V2
| Parameter | Type | Required | Description |
|---|---|---|---|
| jsonScript.checkerOpt.confidenceInterval | integer | Y | Confidence interval range. Values: 1-100% |
12. Monitor operation permission configuration
| Parameter | Type | Description |
|---|---|---|
| openPermissionSet | boolean | Whether to enable custom permission configuration. Default: false |
| permissionSet | array | Operation permission configuration |
permissionSet and openPermissionSet field notes (fields added in the 2024-06-26 iteration):
When openPermissionSet is enabled, only the workspace owner and the roles, teams, and members in the permissionSet configuration can edit, enable, disable, or delete.
When openPermissionSet is disabled (default), the delete, enable, disable, and edit permissions follow the original API's edit/enable/disable/delete permissions.
The permissionSet field can be configured with role UUIDs (wsAdmin, general, readOnly, role_xxxxx), team UUIDs (group_yyyy), and member UUIDs (acnt_xxx).
Example of the permissionSet field:
13. Incident association configuration
| Parameter | Type | Description |
|---|---|---|
| extend.isNeedCreateIssue | boolean | Whether to associate with an Incident. Disabled by default |
| extend.issueDfStatus | array | Five optional types (fatal, critical, error, warning, nodata). When issueDfStatus is present, an Issue is created only if the df_status of the event generated by the Monitor is included in issueDfStatus. When issueDfStatus is absent, an Issue is created for all events |
| extend.issueLevelUUID | string | Issue level UUID |
| extend.manager | array | Person in charge when creating an Issue (email / workspace member / team). Example: ["xxx@truewatch.com", "acnt_yyyy", "group_"] |
| extend.needRecoverIssue | boolean | Whether event recovery should close the Issue synchronously. Default: false |
| jsonScript.channels | string | Required when isNeedCreateIssue is true. Issue channel information. Example: ["chan_xxx", "chan_yyy"] |
14. DQL echo mode queryType
When extend.querylist is not passed, queryType is an optional outer field that controls automatic injection. Only simple and dql are supported; default is dql when not passed. When simple is passed, Studio uses the local DQL parser to parse and inject the simple-mode fields from jsonScript.targets. If parsing or conversion fails, it automatically falls back to DQL text mode. When extend.querylist is explicitly passed, the caller's structure is preserved in full and the injection semantics of queryType are ignored.
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 '{"queryType":"simple","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"
}