diff --git a/plugins/cost-insights/README.md b/plugins/cost-insights/README.md index a103b58a77..bbd047be14 100644 --- a/plugins/cost-insights/README.md +++ b/plugins/cost-insights/README.md @@ -144,6 +144,6 @@ costInsights: The CostInsightsApi `getAlerts` method may return any type of alert or recommendation (called collectively "Action Items" in Cost Insights) that implements the [Alert type](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/src/types/Alert.ts). This allows you to deliver any alerts or recommendations specific to your infrastructure or company migrations. -The Alert type includes an `element` field to supply the JSX Element that will be rendered in the Cost Insights "Action Items" section; we recommend using Backstage's [InfoCard](https://backstage.io/storybook/?path=/story/layout-information-card--default) and [Recharts](http://recharts.org/en-US/) to show actionable visualizations. +To learn more about using Cost Insights' ready-to-use alerts, see the alerts [README](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/src/alerts/README.md). -The Alert `url` should link to documentation or instructions for resolving the alert. This may be omitted if no external link is needed. +Example implementations of custom alerts, forms and components can be found in the [examples](https://github.com/backstage/backstage/tree/master/plugins/cost-insights/src/example) directory. diff --git a/plugins/cost-insights/src/alerts/README.md b/plugins/cost-insights/src/alerts/README.md new file mode 100644 index 0000000000..4b24e4005f --- /dev/null +++ b/plugins/cost-insights/src/alerts/README.md @@ -0,0 +1,125 @@ +# Cost Insights Alerts + +Cost Insights supports custom and ready-to-use alerts such as [project growth](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/src/alerts/ProjectGrowthAlert.tsx) and [unlabeled dataflow](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/src/alerts/UnlabeledDataflowAlert.tsx) alerts. These exported alerts do not require any UI or additional configuration but are extendable for custom implementations. + +### Basic Setup + +Project growth alerts, for example, can be used to alert users to increased cost growth in a Google Cloud project within the past 30 days. + +![project-growth-alert-basic](../assets/project-growth-alert-basic.png) + +```ts +// client.ts +import { ProjectGrowthAlert, ProjectGrowthData } from '@backstage/plugin-cost-insights'; + +export class CostInsightsClient extends CostInsightsApi { + + ... + + async getAlerts(group: string): Promise { + const data: ProjectGrowthData = await getAlertDataSomehow(group); + return [ + new ProjectGrowthAlert({ + project: data.project, + products: data.products, + periodEnd: data.periodEnd, + periodStart: data.periodStart, + aggregation: data.aggregation, + change: data.change + }) + ] + } +} + +``` + +### Custom Setup + +Default properties such as the title, subtitle and instructions page url can be overridden - even default UI such as chart itself. Additionally, alerts can be extended to support actions such as snoozing or dismissing. + +![project-growth-alert-custom](../assets/project-growth-alert-custom.png) + +```ts +// ./ProjectGrowthAlert.ts + +import { + Alert, + AlertOptions, + AlertDismissFormData, + AlertSnoozeFormData, + ProjectGrowthAlert as DefaultProjectGrowthAlert, + ProjectGrowthData +} from '@backstage/plugin-cost-insights'; + +export class ProjectGrowthAlert extends DefaultProjectGrowthAlert { + + constructor(data: ProjectGrowthData){ + super(data); + } + + get url(){ + return '/path/to/your/docs'; + } + + get title(){ + return `Custom title for ${this.data.project}`; + } + + get subtitle(){ + return 'A custom subtitle for a project growth alert'; + } + + // render a custom component in the Action Items section + get element(){ + return + } + + async onAccepted(options: AlertOptions): Promise{ + ... + } + + async onDismissed(options: AlertOptions): Promise{ + ... + } + + async onSnoozed(options: AlertOptions): Promise{ + ... + } +} +``` + +```ts +// client.ts +import { ProjectGrowthAlert } from './ProjectGrowthAlert'; + +export class CostInsightsClient extends CostInsightsApi { + + ... + + async getAlerts(group: string): Promise { + const data: ProjectGrowthData = await getAlertDataSomehow(group); + return [ + new ProjectGrowthAlert({ + project: data.project, + products: data.products, + periodEnd: data.periodEnd, + periodStart: data.periodStart, + aggregation: data.aggregation, + change: data.change + }) + ] + } +} +``` + +### Advanced Setup + +Alerts can render their own custom forms for actions such as snoozing or dismissing if the default UI is insufficient. + +Cost Insights exports several core UI components such as the `BarChart` and `LegendItem` to support custom implementations. + +**Note**: We recommend using Backstage's [InfoCard](https://backstage.io/storybook/?path=/story/layout-information-card--default) and [Recharts](http://recharts.org/en-US/) to show actionable visualizations. + +For more advanced usage, see example [KubernetesMigrationAlert](https://github.com/backstage/backstage/blob/master/plugins/cost-insights/src/example/alerts/KubernetesMigrationAlert.tsx). + +![project-growth-alert-advanced](../assets/project-growth-alert-advanced.png) diff --git a/plugins/cost-insights/src/assets/project-growth-alert-advanced.png b/plugins/cost-insights/src/assets/project-growth-alert-advanced.png new file mode 100644 index 0000000000..03e98fd420 Binary files /dev/null and b/plugins/cost-insights/src/assets/project-growth-alert-advanced.png differ diff --git a/plugins/cost-insights/src/assets/project-growth-alert-basic.png b/plugins/cost-insights/src/assets/project-growth-alert-basic.png new file mode 100644 index 0000000000..397a053368 Binary files /dev/null and b/plugins/cost-insights/src/assets/project-growth-alert-basic.png differ diff --git a/plugins/cost-insights/src/assets/project-growth-alert-custom.png b/plugins/cost-insights/src/assets/project-growth-alert-custom.png new file mode 100644 index 0000000000..5146b331f5 Binary files /dev/null and b/plugins/cost-insights/src/assets/project-growth-alert-custom.png differ