Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[HTTP/OAS] Add description in create rule request body #183564

Merged
merged 2 commits into from
May 21, 2024
Merged

[HTTP/OAS] Add description in create rule request body #183564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d170259
Add descriptions in alerting schemas
lcawl May 15, 2024
08d40bc
Merge branch 'main' into rule-descriptions
kibanamachine May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 158 additions & 46 deletions x-pack/plugins/alerting/common/routes/rule/apis/create/schemas/v1.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,60 +11,172 @@ import { notifyWhenSchemaV1, alertDelaySchemaV1 } from '../../../response';
import { alertsFilterQuerySchemaV1 } from '../../../../alerts_filter_query';

export const actionFrequencySchema = schema.object({
summary: schema.boolean(),
summary: schema.boolean({
meta: { description: 'Indicates whether the action is a summary.' },
}),
notify_when: notifyWhenSchemaV1,
throttle: schema.nullable(schema.string({ validate: validateDurationV1 })),
});

export const actionAlertsFilterSchema = schema.object({
query: schema.maybe(alertsFilterQuerySchemaV1),
timeframe: schema.maybe(
schema.object({
days: schema.arrayOf(
schema.oneOf([
schema.literal(1),
schema.literal(2),
schema.literal(3),
schema.literal(4),
schema.literal(5),
schema.literal(6),
schema.literal(7),
])
),
hours: schema.object({
start: schema.string({
validate: validateHoursV1,
}),
end: schema.string({
validate: validateHoursV1,
}),
}),
timezone: schema.string({ validate: validateTimezoneV1 }),
throttle: schema.nullable(
schema.string({
validate: validateDurationV1,
meta: {
description:
'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if `notify_when` is set to `onThrottleInterval`. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.',
},
})
),
});

export const actionSchema = schema.object({
group: schema.maybe(schema.string()),
id: schema.string(),
params: schema.recordOf(schema.string(), schema.maybe(schema.any()), { defaultValue: {} }),
frequency: schema.maybe(actionFrequencySchema),
uuid: schema.maybe(schema.string()),
alerts_filter: schema.maybe(actionAlertsFilterSchema),
use_alert_data_for_template: schema.maybe(schema.boolean()),
});
export const actionAlertsFilterSchema = schema.object(
{
query: schema.maybe(alertsFilterQuerySchemaV1),
timeframe: schema.maybe(
schema.object(
{
days: schema.arrayOf(
schema.oneOf([
schema.literal(1),
schema.literal(2),
schema.literal(3),
schema.literal(4),
schema.literal(5),
schema.literal(6),
schema.literal(7),
]),
{
meta: {
description:
'Defines the days of the week that the action can run, represented as an array of numbers. For example, `1` represents Monday. An empty array is equivalent to specifying all the days of the week.',
},
}
),
hours: schema.object(
{
start: schema.string({
validate: validateHoursV1,
meta: { description: 'The start of the time frame in 24-hour notation (`hh:mm`).' },
}),
end: schema.string({
validate: validateHoursV1,
meta: { description: 'The end of the time frame in 24-hour notation (`hh:mm`).' },
}),
},
{
meta: {
description:
'Defines the range of time in a day that the action can run. If the `start` value is `00:00` and the `end` value is `24:00`, actions be generated all day.',
},
}
),
timezone: schema.string({
validate: validateTimezoneV1,
meta: {
description:
'The ISO time zone for the `hours` values. Values such as `UTC` and `UTC+1` also work but lack built-in daylight savings time support and are not recommended.',
},
}),
},
{ meta: { description: 'Defines a period that limits whether the action runs.' } }
)
),
},
{
meta: {
description:
'Conditions that affect whether the action runs. If you specify multiple conditions, all conditions must be met for the action to run. For example, if an alert occurs within the specified time frame and matches the query, the action runs.',
},
}
);

export const actionSchema = schema.object(
{
group: schema.maybe(
schema.string({
meta: {
description:
"The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to `default`.",
},
})
),
id: schema.string({
meta: { description: 'The identifier for the connector saved object.' },
}),
params: schema.recordOf(schema.string(), schema.maybe(schema.any()), {
defaultValue: {},
meta: {
description:
'The parameters for the action, which are sent to the connector. The `params` are handled as Mustache templates and passed a default set of context.',
},
}),
frequency: schema.maybe(actionFrequencySchema),
uuid: schema.maybe(
schema.string({
meta: { description: 'A universally unique identifier (UUID) for the action.' },
})
),
alerts_filter: schema.maybe(actionAlertsFilterSchema),
use_alert_data_for_template: schema.maybe(schema.boolean()),
},
{
meta: { description: 'An action that runs under defined conditions.' },
}
);

export const createBodySchema = schema.object({
name: schema.string(),
rule_type_id: schema.string(),
enabled: schema.boolean({ defaultValue: true }),
consumer: schema.string(),
tags: schema.arrayOf(schema.string(), { defaultValue: [] }),
throttle: schema.maybe(schema.nullable(schema.string({ validate: validateDurationV1 }))),
params: schema.recordOf(schema.string(), schema.maybe(schema.any()), { defaultValue: {} }),
schedule: schema.object({
interval: schema.string({ validate: validateDurationV1 }),
name: schema.string({
meta: {
description:
'The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.',
},
}),
rule_type_id: schema.string({
meta: { description: 'The rule type identifier.' },
}),
enabled: schema.boolean({
defaultValue: true,
meta: {
description:
'Indicates whether you want to run the rule on an interval basis after it is created.',
},
}),
consumer: schema.string({
meta: {
description:
'The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.',
},
}),
tags: schema.arrayOf(schema.string(), {
defaultValue: [],
meta: { description: 'The tags for the rule.' },
}),
throttle: schema.maybe(
schema.nullable(
schema.string({
validate: validateDurationV1,
meta: {
description:
'Use the `throttle` property in the action `frequency` object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.',
},
})
)
),
params: schema.recordOf(schema.string(), schema.maybe(schema.any()), {
defaultValue: {},
meta: { description: 'The parameters for the rule.' },
}),
schedule: schema.object(
{
interval: schema.string({
validate: validateDurationV1,
meta: { description: 'The interval is specified in seconds, minutes, hours, or days.' },
}),
},
{
meta: {
description:
'The check interval, which specifies how frequently the rule conditions are checked.',
},
}
),
actions: schema.arrayOf(actionSchema, { defaultValue: [] }),
notify_when: schema.maybe(schema.nullable(notifyWhenSchemaV1)),
alert_delay: schema.maybe(alertDelaySchemaV1),
Expand Down
24 changes: 20 additions & 4 deletions x-pack/plugins/alerting/common/routes/rule/response/schemas/v1.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,13 @@ export const notifyWhenSchema = schema.oneOf(
schema.literal(ruleNotifyWhenV1.ACTIVE),
schema.literal(ruleNotifyWhenV1.THROTTLE),
],
{ validate: validateNotifyWhenV1 }
{
validate: validateNotifyWhenV1,
meta: {
description:
'Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify `notify_when` at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.',
},
}
);

const intervalScheduleSchema = schema.object({
Expand Down Expand Up @@ -183,9 +189,19 @@ export const ruleSnoozeScheduleSchema = schema.object({
skipRecurrences: schema.maybe(schema.arrayOf(schema.string())),
});

export const alertDelaySchema = schema.object({
active: schema.number(),
});
export const alertDelaySchema = schema.object(
{
active: schema.number({
meta: { description: 'The number of consecutive runs that must meet the rule conditions.' },
}),
},
{
meta: {
description:
'Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.',
},
}
);

export const ruleResponseSchema = schema.object({
id: schema.string(),
Expand Down