maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add comments to some alerting plugin public API items (#101551) (#102130)

Browse source 
* 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>
This commit is contained in:
Kibana Machine 2021-06-14 17:51:30 -04:00 committed by GitHub
parent fabd28a8ff
commit e0f2ed9f1f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 158 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

143
api_docs/alerting.json
View file

@ -5,7 +5,42 @@
"functions": [], "functions": [],
"interfaces": [], "interfaces": [],
"enums": [], "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": [], "objects": [],
"setup": { "setup": {
"parentPluginId": "alerting", "parentPluginId": "alerting",
@ -24,44 +59,58 @@
"parentPluginId": "alerting", "parentPluginId": "alerting",
"id": "def-public.PluginSetupContract.registerNavigation", "id": "def-public.PluginSetupContract.registerNavigation",
"type": "Function", "type": "Function",
"tags": [], "tags": [
"throws"
],
"label": "registerNavigation", "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": [ "signature": [
"(consumer: string, alertType: string, handler: ", "(applicationId: string, ruleType: string, handler: ",
"AlertNavigationHandler", {
"pluginId": "alerting",
"scope": "public",
"docId": "kibAlertingPluginApi",
"section": "def-public.AlertNavigationHandler",
"text": "AlertNavigationHandler"
},
") => void" ") => void"
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 15 "lineNumber": 30
}, },
"deprecated": false, "deprecated": false,
"returnComment": [], "returnComment": [],
"children": [ "children": [
{ {
"parentPluginId": "alerting", "parentPluginId": "alerting",
"id": "def-public.consumer", "id": "def-public.applicationId",
"type": "string", "type": "string",
"tags": [], "tags": [],
"label": "consumer", "label": "applicationId",
"description": [], "description": [
"The application id that the user should be navigated to, to view a particular alert in a custom way."
],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 16 "lineNumber": 31
}, },
"deprecated": false "deprecated": false
}, },
{ {
"parentPluginId": "alerting", "parentPluginId": "alerting",
"id": "def-public.alertType", "id": "def-public.ruleType",
"type": "string", "type": "string",
"tags": [], "tags": [],
"label": "alertType", "label": "ruleType",
"description": [], "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": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 17 "lineNumber": 32
}, },
"deprecated": false "deprecated": false
}, },
@ -71,7 +120,9 @@
"type": "Function", "type": "Function",
"tags": [], "tags": [],
"label": "handler", "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": [ "signature": [
"(alert: Pick<", "(alert: Pick<",
{ {
@ -81,15 +132,7 @@
"section": "def-common.Alert", "section": "def-common.Alert",
"text": "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: ", "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
{
"pluginId": "alerting",
"scope": "common",
"docId": "kibAlertingPluginApi",
"section": "def-common.AlertType",
"text": "AlertType"
},
"<\"default\", \"recovered\">) => string | ",
{ {
"pluginId": "kibanaUtils", "pluginId": "kibanaUtils",
"scope": "common", "scope": "common",
@ -100,7 +143,7 @@
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 18 "lineNumber": 33
}, },
"deprecated": false "deprecated": false
} }
@ -112,29 +155,39 @@
"type": "Function", "type": "Function",
"tags": [], "tags": [],
"label": "registerDefaultNavigation", "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": [ "signature": [
"(consumer: string, handler: ", "(applicationId: string, handler: ",
"AlertNavigationHandler", {
"pluginId": "alerting",
"scope": "public",
"docId": "kibAlertingPluginApi",
"section": "def-public.AlertNavigationHandler",
"text": "AlertNavigationHandler"
},
") => void" ") => void"
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20 "lineNumber": 46
}, },
"deprecated": false, "deprecated": false,
"returnComment": [], "returnComment": [],
"children": [ "children": [
{ {
"parentPluginId": "alerting", "parentPluginId": "alerting",
"id": "def-public.consumer", "id": "def-public.applicationId",
"type": "string", "type": "string",
"tags": [], "tags": [],
"label": "consumer", "label": "applicationId",
"description": [], "description": [
"The application id that the user should be navigated to, to view a particular alert in a custom way."
],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20 "lineNumber": 46
}, },
"deprecated": false "deprecated": false
}, },
@ -144,7 +197,9 @@
"type": "Function", "type": "Function",
"tags": [], "tags": [],
"label": "handler", "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": [ "signature": [
"(alert: Pick<", "(alert: Pick<",
{ {
@ -154,15 +209,7 @@
"section": "def-common.Alert", "section": "def-common.Alert",
"text": "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: ", "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
{
"pluginId": "alerting",
"scope": "common",
"docId": "kibAlertingPluginApi",
"section": "def-common.AlertType",
"text": "AlertType"
},
"<\"default\", \"recovered\">) => string | ",
{ {
"pluginId": "kibanaUtils", "pluginId": "kibanaUtils",
"scope": "common", "scope": "common",
@ -173,7 +220,7 @@
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 20 "lineNumber": 46
}, },
"deprecated": false "deprecated": false
} }
@ -192,7 +239,7 @@
"description": [], "description": [],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 22 "lineNumber": 48
}, },
"deprecated": false, "deprecated": false,
"children": [ "children": [
@ -224,7 +271,7 @@
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 23 "lineNumber": 49
}, },
"deprecated": false, "deprecated": false,
"returnComment": [], "returnComment": [],
@ -238,7 +285,7 @@
"description": [], "description": [],
"source": { "source": {
"path": "x-pack/plugins/alerting/public/plugin.ts", "path": "x-pack/plugins/alerting/public/plugin.ts",
"lineNumber": 23 "lineNumber": 49
}, },
"deprecated": false "deprecated": false
} }
@ -3857,7 +3904,7 @@
"label": "ReservedActionGroups", "label": "ReservedActionGroups",
"description": [], "description": [],
"signature": [ "signature": [
"\"recovered\" | RecoveryActionGroupId" "RecoveryActionGroupId | \"recovered\""
], ],
"source": { "source": {
"path": "x-pack/plugins/alerting/common/builtin_action_groups.ts", "path": "x-pack/plugins/alerting/common/builtin_action_groups.ts",

3
api_docs/alerting.mdx
View file

@ -29,6 +29,9 @@ import alertingObj from './alerting.json';
### Start ### Start
<DocDefinitionList data={[alertingObj.client.start]}/> <DocDefinitionList data={[alertingObj.client.start]}/>
### Consts, variables and types
<DocDefinitionList data={alertingObj.client.misc}/>
## Server ## Server
### Functions ### Functions

4
x-pack/plugins/alerting/README.md
View file

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

8
x-pack/plugins/alerting/public/alert_navigation_registry/alert_navigation_registry.test.ts
View file

@ -23,7 +23,7 @@ const mockAlertType = (id: string): AlertType => ({
}); });
describe('AlertNavigationRegistry', () => { describe('AlertNavigationRegistry', () => {
function handler(alert: SanitizedAlert, alertType: AlertType) { function handler(alert: SanitizedAlert) {
return {}; return {};
} }
@ -143,7 +143,7 @@ describe('AlertNavigationRegistry', () => {
test('returns registered handlers by consumer & Alert Type', () => { test('returns registered handlers by consumer & Alert Type', () => {
const registry = new AlertNavigationRegistry(); const registry = new AlertNavigationRegistry();
function indexThresholdHandler(alert: SanitizedAlert, alertType: AlertType) { function indexThresholdHandler(alert: SanitizedAlert) {
return {}; return {};
} }
@ -155,7 +155,7 @@ describe('AlertNavigationRegistry', () => {
test('returns default handlers by consumer when there is no handler for requested alert type', () => { test('returns default handlers by consumer when there is no handler for requested alert type', () => {
const registry = new AlertNavigationRegistry(); const registry = new AlertNavigationRegistry();
function defaultHandler(alert: SanitizedAlert, alertType: AlertType) { function defaultHandler(alert: SanitizedAlert) {
return {}; return {};
} }
@ -168,7 +168,7 @@ describe('AlertNavigationRegistry', () => {
registry.register('siem', mockAlertType('indexThreshold'), () => ({})); registry.register('siem', mockAlertType('indexThreshold'), () => ({}));
function defaultHandler(alert: SanitizedAlert, alertType: AlertType) { function defaultHandler(alert: SanitizedAlert) {
return {}; return {};
} }

16
x-pack/plugins/alerting/public/alert_navigation_registry/types.ts
View file

@ -6,9 +6,15 @@
*/ */
import { JsonObject } from '../../../../../src/plugins/kibana_utils/common'; import { JsonObject } from '../../../../../src/plugins/kibana_utils/common';
import { AlertType, SanitizedAlert } from '../../common'; import { SanitizedAlert } from '../../common';
export type AlertNavigationHandler = ( /**
alert: SanitizedAlert, * Returns information that can be used to navigate to a specific page to view the given rule.
alertType: AlertType *
) => JsonObject | string; * @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
x-pack/plugins/alerting/public/index.ts
View file

@ -6,7 +6,8 @@
*/ */
import { AlertingPublicPlugin } from './plugin'; 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() { export function plugin() {
return new AlertingPublicPlugin(); return new AlertingPublicPlugin();

50
x-pack/plugins/alerting/public/plugin.ts
View file

@ -12,12 +12,38 @@ import { loadAlert, loadAlertType } from './alert_api';
import { Alert, AlertNavigation } from '../common'; import { Alert, AlertNavigation } from '../common';
export interface PluginSetupContract { export interface PluginSetupContract {
/**
* Register a customized view of the particular rule type. Stack Management provides a generic overview, but a developer can register a
* custom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do
* anything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently
* the trigger_actions_ui plugin uses it to expose the link from the generic rule details view in Stack Management.
*
* @param applicationId The application id that the user should be navigated to, to view a particular alert in a custom way.
* @param ruleType The rule type that has been registered with Alerting.Server.PluginSetupContract.registerType. If
* no 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
* because it was causing flaky test failures with https://github.com/elastic/kibana/issues/59229 and needs to be
* investigated more.
* @param handler The navigation handler should return either a relative URL, or a state object. This information can be used,
* in conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details.
* @throws an error if the given applicationId and ruleType combination has already been registered.
*/
registerNavigation: ( registerNavigation: (
consumer: string, applicationId: string,
alertType: string, ruleType: string,
handler: AlertNavigationHandler handler: AlertNavigationHandler
) => void; ) => void;
registerDefaultNavigation: (consumer: string, handler: AlertNavigationHandler) => void;
/**
* Register a customized view for all rule types with this application id. Stack Management provides a generic overview, but a developer can register a
* custom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do
* anything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently
* the trigger_actions_ui plugin uses it to expose the link from the generic rule details view in Stack Management.
*
* @param applicationId The application id that the user should be navigated to, to view a particular alert in a custom way.
* @param handler The navigation handler should return either a relative URL, or a state object. This information can be used,
* in conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details.
*/
registerDefaultNavigation: (applicationId: string, handler: AlertNavigationHandler) => void;
} }
export interface PluginStartContract { export interface PluginStartContract {
getNavigation: (alertId: Alert['id']) => Promise<AlertNavigation | undefined>; getNavigation: (alertId: Alert['id']) => Promise<AlertNavigation | undefined>;
@ -29,23 +55,25 @@ export class AlertingPublicPlugin implements Plugin<PluginSetupContract, PluginS
this.alertNavigationRegistry = new AlertNavigationRegistry(); this.alertNavigationRegistry = new AlertNavigationRegistry();
const registerNavigation = async ( const registerNavigation = async (
consumer: string, applicationId: string,
alertTypeId: string, ruleTypeId: string,
handler: AlertNavigationHandler handler: AlertNavigationHandler
) => { ) => {
const alertType = await loadAlertType({ http: core.http, id: alertTypeId }); const alertType = await loadAlertType({ http: core.http, id: ruleTypeId });
if (!alertType) { if (!alertType) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.log( console.log(
`Unable to register navigation for alert type "${alertTypeId}" because it is not registered on the server side.` `Unable to register navigation for rule type "${ruleTypeId}" because it is not registered on the server side.`
); );
return; return;
} }
this.alertNavigationRegistry!.register(consumer, alertType, handler); this.alertNavigationRegistry!.register(applicationId, alertType, handler);
}; };
const registerDefaultNavigation = async (consumer: string, handler: AlertNavigationHandler) => const registerDefaultNavigation = async (
this.alertNavigationRegistry!.registerDefault(consumer, handler); applicationId: string,
handler: AlertNavigationHandler
) => this.alertNavigationRegistry!.registerDefault(applicationId, handler);
return { return {
registerNavigation, registerNavigation,
@ -69,7 +97,7 @@ export class AlertingPublicPlugin implements Plugin<PluginSetupContract, PluginS
if (this.alertNavigationRegistry!.has(alert.consumer, alertType)) { if (this.alertNavigationRegistry!.has(alert.consumer, alertType)) {
const navigationHandler = this.alertNavigationRegistry!.get(alert.consumer, alertType); const navigationHandler = this.alertNavigationRegistry!.get(alert.consumer, alertType);
const state = navigationHandler(alert, alertType); const state = navigationHandler(alert);
return typeof state === 'string' ? { path: state } : { state }; return typeof state === 'string' ? { path: state } : { state };
} }
}, },

4
x-pack/test/functional_with_es_ssl/fixtures/plugins/alerts/public/plugin.ts
View file

@ -8,7 +8,7 @@
import React from 'react'; import React from 'react';
import { Plugin, CoreSetup, AppMountParameters } from 'kibana/public'; import { Plugin, CoreSetup, AppMountParameters } from 'kibana/public';
import { PluginSetupContract as AlertingSetup } from '../../../../../../plugins/alerting/public'; import { PluginSetupContract as AlertingSetup } from '../../../../../../plugins/alerting/public';
import { AlertType, SanitizedAlert } from '../../../../../../plugins/alerting/common'; import { SanitizedAlert } from '../../../../../../plugins/alerting/common';
import { TriggersAndActionsUIPublicPluginSetup } from '../../../../../../plugins/triggers_actions_ui/public'; import { TriggersAndActionsUIPublicPluginSetup } from '../../../../../../plugins/triggers_actions_ui/public';
export type Setup = void; export type Setup = void;
@ -24,7 +24,7 @@ export class AlertingFixturePlugin implements Plugin<Setup, Start, AlertingExamp
alerting.registerNavigation( alerting.registerNavigation(
'alerting_fixture', 'alerting_fixture',
'test.noop', 'test.noop',
(alert: SanitizedAlert, alertType: AlertType) => `/rule/${alert.id}` (alert: SanitizedAlert) => `/rule/${alert.id}`
); );
triggersActionsUi.alertTypeRegistry.register({ triggersActionsUi.alertTypeRegistry.register({