Skip to content

Commit

Permalink
Add comments to some alerting plugin public API items (#101551) (#102130
Browse files Browse the repository at this point in the history 
)

* Add comments. Remove ruleType as the second param, not needed.

* Add comments. Remove ruleType as the second param, not needed.

* Fix bad type check and update docs

* update docs

* Remove unused import

* change exports to type to avoid increasing bundle size

* Update x-pack/plugins/alerting/public/plugin.ts

Co-authored-by: ymao1 <ying.mao@elastic.co>

* Update x-pack/plugins/alerting/public/plugin.ts

Co-authored-by: ymao1 <ying.mao@elastic.co>

* Update x-pack/plugins/alerting/public/plugin.ts

Co-authored-by: ymao1 <ying.mao@elastic.co>

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: ymao1 <ying.mao@elastic.co>

Co-authored-by: Stacey Gammon <gammon@elastic.co>
Co-authored-by: ymao1 <ying.mao@elastic.co>
  • Loading branch information
@kibanamachine @stacey-gammon @ymao1
3 people authored Jun 14, 2021
1 parent fabd28a commit e0f2ed9
Show file tree
Hide file tree
Showing 8 changed files with 158 additions and 73 deletions.
143 changes: 95 additions & 48 deletions api_docs/alerting.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,42 @@
"functions": [],
"interfaces": [],
"enums": [],
"misc": [],
"misc": [
{
"parentPluginId": "alerting",
"id": "def-public.AlertNavigationHandler",
"type": "Type",
"tags": [],
"label": "AlertNavigationHandler",
"description": [
"\nReturns information that can be used to navigate to a specific page to view the given rule.\n"
],
"signature": [
"(alert: Pick<",
{
"pluginId": "alerting",
"scope": "common",
"docId": "kibAlertingPluginApi",
"section": "def-common.Alert",
"text": "Alert"
},
"<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
{
"pluginId": "kibanaUtils",
"scope": "common",
"docId": "kibKibanaUtilsPluginApi",
"section": "def-common.JsonObject",
"text": "JsonObject"
}
],
"source": {
"path": "x-pack/plugins/alerting/public/alert_navigation_registry/types.ts",
"lineNumber": 20
},
"deprecated": false,
"initialIsOpen": false
}
],
"objects": [],
"setup": {
"parentPluginId": "alerting",
Expand All @@ -24,44 +59,58 @@
"parentPluginId": "alerting",
"id": "def-public.PluginSetupContract.registerNavigation",
"type": "Function",
"tags": [],
"tags": [
"throws"
],
"label": "registerNavigation",
"description": [],
"description": [
"\nRegister a customized view of the particular rule type. Stack Management provides a generic overview, but a developer can register a\ncustom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do\nanything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently\nthe trigger_actions_ui plugin uses it to expose the link from the generic rule view in Stack Management.\n"
],
"signature": [
"(consumer: string, alertType: string, handler: ",
"AlertNavigationHandler",
"(applicationId: string, ruleType: string, handler: ",
{
"pluginId": "alerting",
"scope": "public",
"docId": "kibAlertingPluginApi",
"section": "def-public.AlertNavigationHandler",
"text": "AlertNavigationHandler"
},
") => void"
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 15
"lineNumber": 30
},
"deprecated": false,
"returnComment": [],
"children": [
{
"parentPluginId": "alerting",
"id": "def-public.consumer",
"id": "def-public.applicationId",
"type": "string",
"tags": [],
"label": "consumer",
"description": [],
"label": "applicationId",
"description": [
"The application id that the user should be navigated to, to view a particular alert in a custom way."
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 16
"lineNumber": 31
},
"deprecated": false
},
{
"parentPluginId": "alerting",
"id": "def-public.alertType",
"id": "def-public.ruleType",
"type": "string",
"tags": [],
"label": "alertType",
"description": [],
"label": "ruleType",
"description": [
"The rule type that has been registered with Alerting.Server.PluginSetupContract.registerType. If\nno such rule with that id exists, a warning is output to the console log. It used to throw an error, but that was temporarily moved\nbecause it was causing flaky test failures with https://github.com/elastic/kibana/issues/59229 and needs to be\ninvestigated more."
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 17
"lineNumber": 32
},
"deprecated": false
},
Expand All @@ -71,7 +120,9 @@
"type": "Function",
"tags": [],
"label": "handler",
"description": [],
"description": [
"The navigation handler should return either a relative URL, or a state object. This information can be used,\nin conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details."
],
"signature": [
"(alert: Pick<",
{
Expand All @@ -81,15 +132,7 @@
"section": "def-common.Alert",
"text": "Alert"
},
"<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">, alertType: ",
{
"pluginId": "alerting",
"scope": "common",
"docId": "kibAlertingPluginApi",
"section": "def-common.AlertType",
"text": "AlertType"
},
"<\"default\", \"recovered\">) => string | ",
"<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
{
"pluginId": "kibanaUtils",
"scope": "common",
Expand All @@ -100,7 +143,7 @@
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 18
"lineNumber": 33
},
"deprecated": false
}
Expand All @@ -112,29 +155,39 @@
"type": "Function",
"tags": [],
"label": "registerDefaultNavigation",
"description": [],
"description": [
"\nRegister a customized view for all rule types. Stack Management provides a generic overview, but a developer can register a\ncustom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do\nanything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently\nthe trigger_actions_ui plugin uses it to expose the link from the generic rule view in Stack Management.\n"
],
"signature": [
"(consumer: string, handler: ",
"AlertNavigationHandler",
"(applicationId: string, handler: ",
{
"pluginId": "alerting",
"scope": "public",
"docId": "kibAlertingPluginApi",
"section": "def-public.AlertNavigationHandler",
"text": "AlertNavigationHandler"
},
") => void"
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20
"lineNumber": 46
},
"deprecated": false,
"returnComment": [],
"children": [
{
"parentPluginId": "alerting",
"id": "def-public.consumer",
"id": "def-public.applicationId",
"type": "string",
"tags": [],
"label": "consumer",
"description": [],
"label": "applicationId",
"description": [
"The application id that the user should be navigated to, to view a particular alert in a custom way."
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20
"lineNumber": 46
},
"deprecated": false
},
Expand All @@ -144,7 +197,9 @@
"type": "Function",
"tags": [],
"label": "handler",
"description": [],
"description": [
"The navigation handler should return either a relative URL, or a state object. This information can be used,\nin conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details."
],
"signature": [
"(alert: Pick<",
{
Expand All @@ -154,15 +209,7 @@
"section": "def-common.Alert",
"text": "Alert"
},
"<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">, alertType: ",
{
"pluginId": "alerting",
"scope": "common",
"docId": "kibAlertingPluginApi",
"section": "def-common.AlertType",
"text": "AlertType"
},
"<\"default\", \"recovered\">) => string | ",
"<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
{
"pluginId": "kibanaUtils",
"scope": "common",
Expand All @@ -173,7 +220,7 @@
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20
"lineNumber": 46
},
"deprecated": false
}
Expand All @@ -192,7 +239,7 @@
"description": [],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 22
"lineNumber": 48
},
"deprecated": false,
"children": [
Expand Down Expand Up @@ -224,7 +271,7 @@
],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 23
"lineNumber": 49
},
"deprecated": false,
"returnComment": [],
Expand All @@ -238,7 +285,7 @@
"description": [],
"source": {
"path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 23
"lineNumber": 49
},
"deprecated": false
}
Expand Down Expand Up @@ -3857,7 +3904,7 @@
"label": "ReservedActionGroups",
"description": [],
"signature": [
"\"recovered\" | RecoveryActionGroupId"
"RecoveryActionGroupId | \"recovered\""
],
"source": {
"path": "x-pack/plugins/alerting/common/builtin_action_groups.ts",
Expand Down
3 changes: 3 additions & 0 deletions api_docs/alerting.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ import alertingObj from './alerting.json';
### Start
<DocDefinitionList data={[alertingObj.client.start]}/>

### Consts, variables and types
<DocDefinitionList data={alertingObj.client.misc}/>

## Server

### Functions
Expand Down
4 changes: 2 additions & 2 deletions x-pack/plugins/alerting/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -619,7 +619,7 @@ The _registerNavigation_ api allows you to register a handler for a specific ale
alerting.registerNavigation(
'my-application-id',
'my-application-id.my-rule-type',
(alert: SanitizedAlert, alertType: AlertType) => `/my-unique-rule/${rule.id}`
(alert: SanitizedAlert) => `/my-unique-rule/${rule.id}`
);
```

Expand All @@ -635,7 +635,7 @@ The _registerDefaultNavigation_ API allows you to register a handler for any rul
```
alerting.registerDefaultNavigation(
'my-application-id',
(alert: SanitizedAlert, alertType: AlertType) => `/my-other-rules/${rule.id}`
(alert: SanitizedAlert) => `/my-other-rules/${rule.id}`
);
```

Expand Down
8 changes: 4 additions & 4 deletions x-pack/plugins/alerting/public/alert_navigation_registry/alert_navigation_registry.test.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const mockAlertType = (id: string): AlertType => ({
});

describe('AlertNavigationRegistry', () => {
function handler(alert: SanitizedAlert, alertType: AlertType) {
function handler(alert: SanitizedAlert) {
return {};
}

Expand Down Expand Up @@ -143,7 +143,7 @@ describe('AlertNavigationRegistry', () => {
test('returns registered handlers by consumer & Alert Type', () => {
const registry = new AlertNavigationRegistry();

function indexThresholdHandler(alert: SanitizedAlert, alertType: AlertType) {
function indexThresholdHandler(alert: SanitizedAlert) {
return {};
}

Expand All @@ -155,7 +155,7 @@ describe('AlertNavigationRegistry', () => {
test('returns default handlers by consumer when there is no handler for requested alert type', () => {
const registry = new AlertNavigationRegistry();

function defaultHandler(alert: SanitizedAlert, alertType: AlertType) {
function defaultHandler(alert: SanitizedAlert) {
return {};
}

Expand All @@ -168,7 +168,7 @@ describe('AlertNavigationRegistry', () => {

registry.register('siem', mockAlertType('indexThreshold'), () => ({}));

function defaultHandler(alert: SanitizedAlert, alertType: AlertType) {
function defaultHandler(alert: SanitizedAlert) {
return {};
}

Expand Down
16 changes: 11 additions & 5 deletions x-pack/plugins/alerting/public/alert_navigation_registry/types.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,15 @@
*/

import { JsonObject } from '../../../../../src/plugins/kibana_utils/common';
import { AlertType, SanitizedAlert } from '../../common';
import { SanitizedAlert } from '../../common';

export type AlertNavigationHandler = (
alert: SanitizedAlert,
alertType: AlertType
) => JsonObject | string;
/**
* Returns information that can be used to navigate to a specific page to view the given rule.
*
* @param rule The rule to view
* @returns A URL that is meant to be relative to your application id, or a state object that your application uses to render
* the rule. This information is intended to be used with cores NavigateToApp function, along with the application id that was
* originally registered to {@link PluginSetupContract.registerNavigation}.
*
*/
export type AlertNavigationHandler = (alert: SanitizedAlert) => JsonObject | string;
3 changes: 2 additions & 1 deletion x-pack/plugins/alerting/public/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
*/

import { AlertingPublicPlugin } from './plugin';
export { PluginSetupContract, PluginStartContract } from './plugin';
export type { PluginSetupContract, PluginStartContract } from './plugin';
export type { AlertNavigationHandler } from './alert_navigation_registry';

export function plugin() {
return new AlertingPublicPlugin();
Expand Down
Loading

0 comments on commit e0f2ed9

Please sign in to comment.