From cf4dd7474f7eede200b18730c8a3f3f838a71323 Mon Sep 17 00:00:00 2001 From: Federico Zambelli Date: Thu, 2 May 2024 17:34:27 +0200 Subject: [PATCH 1/6] docs: update docs --- README.md | 18 ++++++++------ docs/python.md | 39 ++++++++++++++++++++++++++++++ docs/typescript.md | 17 +++++++------ src/application-cost-monitoring.ts | 26 ++++++++++++-------- 4 files changed, 74 insertions(+), 26 deletions(-) create mode 100644 docs/python.md diff --git a/README.md b/README.md index bee682e..f0748d2 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,17 @@ Cost Monitoring Construct is a CDK library that helps monitor costs for AWS clou With the Cost Monitoring Construct, you can share the responsibility of cost management between developers and business holders. This is achieved through the creation of meaningful reports that enable the business team to make informed decisions. Additionally, the Construct generates boilerplate code that can be used to apply these decisions in practice, making it easier to stay on top of your budget. -# How to use Cost Monitoring Construct? +## How to use Cost Monitoring Construct? To use Cost Monitoring Construct, all you need is to have the AWS CDK installed and set up. Once you have that, you can install the package from the repository of your choice. For more information on using this Construct in TypeScript checkout the [TypeScript documentation](docs/typescript.md). You can also check the typescript example from [sample folder](https://github.com/DataChefHQ/cost-monitoring-construct/tree/main/sample) on the GitHub repository. -# Why do you need it? +## Why do you need it? Cloud services can get very expensive, very quickly, especially if you are not careful with your usage. Cost Monitoring Construct helps you to keep an eye on your cloud infrastructure costs so that you can stay within budget. By setting budgets and defining alert strategies, you can take proactive steps to reduce costs before they become a problem. -# How does Cost Monitoring Construct work? +## How does Cost Monitoring Construct work? Cost Monitoring Construct uses AWS Tagging practice to track resources related to an specific application, creates proper alert with respect to the defined budget limit and provide overview dashbords. The tool is highly customizable and allows you to customize it to your budgeting strategy based on your specific needs. @@ -24,7 +24,10 @@ Cost Monitoring Construct provides the following features: - **Budgets:** Allows you to set budgets for each applications. It will automatically set up alerts to notify you when your actual costs exceed your budgeted costs. It also continues to track the cost and sending alert if an application continues to cost drastically. - **Integration:** Integrates with various tools and monitoring services, such as AWS Cost Explorer and Datadog. -# What is it useful for? +> [!WARNING] +> Tags used to create and monitor budgets must first be [activated as cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html). Ensure your chosen one is activated, otherwise the budgets won't work! + +## What is it useful for? Cost Monitoring Construct is useful for anyone who uses AWS and wants to keep their costs under control. It is particularly useful for: @@ -32,11 +35,11 @@ Cost Monitoring Construct is useful for anyone who uses AWS and wants to keep th - **Large enterprises:** Cost Monitoring Construct can help large enterprises to optimize their cloud usage and reduce costs across multiple teams and departments. - **Developers:** Cost Monitoring Construct can help developers to track their usage and costs across multiple projects and services. -# What is this _not_ useful for? +## What is this _not_ useful for? The Cost Monitoring Construct is not a magical tool that can solve all of your cloud cost problems. In spite of the fact that it can bring clarity and help you to identify areas where you can reduce costs, you must make the necessary decisions about your infrastructure on your own. -# Which programming languages Cost Monitoring Construct supports? +## Which programming languages Cost Monitoring Construct supports? Cost Monitoring Construct has been developed using JSII technolgy to provide interfaces for different modern programming languages. Currently, it supports the following languages: @@ -46,8 +49,7 @@ Cost Monitoring Construct has been developed using JSII technolgy to provide int - [.NET](https://www.nuget.org/packages/DataChef.CostMonitoringConstruct) - [Java](https://central.sonatype.com/artifact/co.datachef/costmonitoringconstruct/1.1.0/versions) -> **✏️ Note** -> +> [!NOTE] > Go will be supported soon but for now you can build it from the source. If you have any questions or need help with Cost Monitoring Construct, you can reach out to our support team at [support@datachef.co](mailto:support@datachef.co). diff --git a/docs/python.md b/docs/python.md new file mode 100644 index 0000000..fbfe739 --- /dev/null +++ b/docs/python.md @@ -0,0 +1,39 @@ +# Introduction + +The Python version of Cost Monitoring Construct derives from the Typescript version, hence refer to [its docs](./typescript.md) for extra details. + +To install the Cost Monitoring Construct package, run the following command to download it from PyPI: + +```bash +pip install cost-monitoring-construct +``` + +## Usage + +Getting started is very simple: just add the following snippet to your code and adapt it to the situation. + +Remember to enable the [cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html), otherwise the budgets won't work! + +```python +import aws_cdk as cdk +from cost_monitoring_construct import ( + ApplicationCostMonitoring, + ApplicationCostMonitoringProps, +) + +app = cdk.App() +monitoring_stack = MonitoringStack(app, "MyMonitoringStack") +first_stack = FirstStack(app, "FirstStack") + +cost_monitoring = ApplicationCostMonitoring( + applications_stack, + props=ApplicationCostMonitoringProps( + application_name="my-application", + monthly_limit_in_dollars=200, + other_stacks_included_in_budget=[first_stack], + subscribers=["alert@example.com"], + cost_allocation_tag="MyTag" + ) +) +cost_monitoring.monitor() +``` diff --git a/docs/typescript.md b/docs/typescript.md index cd62780..2519d9a 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -8,17 +8,17 @@ To install the Cost Monitoring Construct package, run the following command to d npm i cost-monitoring-construct ``` -# Usage +## Usage The easiest way to apply cost monitoring is by using predefined default budget strategies. The `ApplicationCostMonitoring` has default strategy implementation for monitoring budgets per CDK applications, while the `AccountCostMonitoring` has default strategy implementation for monitoring budgets per account. You can also create your own strategy by creating a class that applies to the `IBudgetStrategy` or directly inherits from the `ApplicationCostMonitoring` or `AccountCostMonitoring` class to customize them to your needs. -## `ApplicationCostMonitoring` Class +### `ApplicationCostMonitoring` Class This is the default strategy for monitoring CDK applications. You have to provide at least one stack by the first parameter of the initializer. If you wish to monitor more stacks, you can pass them as a list to the `otherStacksIncludedInBudget` prop. The `ApplicationCostMonitoring` will always use the first stack (the first parameter of the initializer) to inject its resources into it. You can create a separate stack and pass it as the first stack if you wish to keep cost monitoring separate from your stacks. The cost monitoring class will monitor both the first stack and stacks from `otherStacksIncludedInBudget`. -⚠️ **Important Note**: ApplicationCostMonitoring uses AWS Tags to track resources' usages. You must activate the `cm:application` tag key under Cost Allocation Tags. The tag key will appear in the AWS console up to 24 hours after at least one AWS resource has been created with that tag. +> [!WARNING] ApplicationCostMonitoring uses AWS Tags to track resources' usages. You must [activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) your chosen tag key (`cm:application` by default) under Cost Allocation Tags. The tag key will appear in the AWS console up to 24 hours after at least one AWS resource has been created with that tag. The example below shows how to use `ApplicationCostMonitoring` to track your application in CDK code: @@ -29,17 +29,18 @@ const monitoringStack = new MonitoringStack(app, "MyAppMonitoringStack", {}); const firstStack = new FirstStack(app, "FirstStack", {}); const secondStack = new SecondStack(app, "SecondStack", {}); const costMonitoring = new ApplicationCostMonitoring(monitoringStack, { - // the fitst stack ~~~~~~~^~~~~~~ + // the first stack ~~~~~~~👆~~~~~~ applicationName: "my-application", - monthlyBudget: 200, // Optional (you can add as many stack as you want) - otherStacksIncludedInBudget: [secondStack, firstStack], - subscribers: ["alert@example.com"], + monthlyLimitInDollars: 200, + otherStacksIncludedInBudget: [secondStack, firstStack], // Optional (you can add as many stacks as you want) + subscribers: ["alert@example.com"], // Optional + costAllocationTag: "MyTag" // Optional, defaults to `cm:application` }); costMonitoring.monitor(); ``` -## `IBudgetStrategy` Abstract Class +### `IBudgetStrategy` Abstract Class This is the abstract base class that all budget strategies must apply to. This Abstract class enforces the implementation for `createDailyBudgets` and `createMonthlyBudgets`. Plus, it provides the `createQuarterlyBudgets` and `createYearlyBudgets` optional to implement. diff --git a/src/application-cost-monitoring.ts b/src/application-cost-monitoring.ts index 307ad5e..2fbc0a5 100644 --- a/src/application-cost-monitoring.ts +++ b/src/application-cost-monitoring.ts @@ -10,6 +10,14 @@ export interface IApplicationCostMonitoringProps extends IBudgetStrategyProps { } export class ApplicationCostMonitoringProps implements IApplicationCostMonitoringProps { + /** + * @param applicationName - the name of application to label resources with it. + * @param monthlyLimitInDollars - montly limit in US Dollors. + * @param otherStacksIncludedInBudget - optional other stack to track their resources alog with the default stack. + * @param defaultTopic - default SNS topic name. Only if provided, the BudgetStratgy creates an SNS topic and send notifications to it. + * @param subscribers - list of email address that the CostMonitoring will use to send alerts to. + * @param costAllocationTag - Tag key used to track resources' expenditure. Only if provided, it will be used to tag the application resources. Defaults to `cm:application` + */ constructor( public applicationName: string, public monthlyLimitInDollars: number, @@ -34,26 +42,24 @@ export class ApplicationCostMonitoring extends IBudgetStrategy { * @param props.monthlyLimitInDollars - montly limit in US Dollors. * @param props.defaultTopic - default SNS topic name. Only if provided, the BudgetStratgy creates an SNS topic and send notifications to it. * @param props.subscribers - list of email address that the CostMonitoring will use to send alerts to. - * @param props.costAllocationTag - Tag key used to track resources' expenditure. Only if provided, it will be used to tag the application resources. + * @param props.costAllocationTag - Tag key used to track resources' expenditure. Only if provided, it will be used to tag the application resources. Defaults to `cm:application` * - * @example tracking budget for an application called `my-application`: + * @example + * Tracking budget for an application called `my-application` + * + * ```ts * const app = new cdk.App(); * const firstStack = new FirstStack(app, 'FirstStack', {}); * const secondStack = new SecondStack(app, 'SecondStack', {}); * const costMonitoring = new ApplicationCostMonitoring(firstStack, { * applicationName: 'my-application', * monthlyLimitInDollars : 200, - *  // Optional (you can add as many stack as you want) - * otherStacksToMonitor: [ - * secondStack - * ], - * subscribers: [ - * 'alert@example.com' - * ] + * otherStacksToMonitor: [secondStack], // Optional (you can add as many stacks as you want) + * subscribers: ['alert@example.com'] * }); * * budgetStratgy.monitor(); - * + * ``` */ constructor(stack: Stack, props: ApplicationCostMonitoringProps) { super(stack, props); From f5152aad49c69ff7bfd45e0d7f32c1ee6d21bba5 Mon Sep 17 00:00:00 2001 From: Federico Zambelli Date: Thu, 2 May 2024 17:38:32 +0200 Subject: [PATCH 2/6] chore: fix docstring --- src/application-cost-monitoring.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/application-cost-monitoring.ts b/src/application-cost-monitoring.ts index 2fbc0a5..4a5f7eb 100644 --- a/src/application-cost-monitoring.ts +++ b/src/application-cost-monitoring.ts @@ -47,7 +47,6 @@ export class ApplicationCostMonitoring extends IBudgetStrategy { * @example * Tracking budget for an application called `my-application` * - * ```ts * const app = new cdk.App(); * const firstStack = new FirstStack(app, 'FirstStack', {}); * const secondStack = new SecondStack(app, 'SecondStack', {}); @@ -59,7 +58,6 @@ export class ApplicationCostMonitoring extends IBudgetStrategy { * }); * * budgetStratgy.monitor(); - * ``` */ constructor(stack: Stack, props: ApplicationCostMonitoringProps) { super(stack, props); From 6c2c6b8f456c469e67b2aad3349bb1d844cd2373 Mon Sep 17 00:00:00 2001 From: Federico Zambelli Date: Thu, 2 May 2024 17:42:46 +0200 Subject: [PATCH 3/6] chore: update API docs --- API.md | 74 ++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/API.md b/API.md index 1de6c79..fd50b6b 100644 --- a/API.md +++ b/API.md @@ -4,17 +4,17 @@ Cost Monitoring Construct is a CDK library that helps monitor costs for AWS clou With the Cost Monitoring Construct, you can share the responsibility of cost management between developers and business holders. This is achieved through the creation of meaningful reports that enable the business team to make informed decisions. Additionally, the Construct generates boilerplate code that can be used to apply these decisions in practice, making it easier to stay on top of your budget. -# How to use Cost Monitoring Construct? +## How to use Cost Monitoring Construct? To use Cost Monitoring Construct, all you need is to have the AWS CDK installed and set up. Once you have that, you can install the package from the repository of your choice. For more information on using this Construct in TypeScript checkout the [TypeScript documentation](docs/typescript.md). You can also check the typescript example from [sample folder](https://github.com/DataChefHQ/cost-monitoring-construct/tree/main/sample) on the GitHub repository. -# Why do you need it? +## Why do you need it? Cloud services can get very expensive, very quickly, especially if you are not careful with your usage. Cost Monitoring Construct helps you to keep an eye on your cloud infrastructure costs so that you can stay within budget. By setting budgets and defining alert strategies, you can take proactive steps to reduce costs before they become a problem. -# How does Cost Monitoring Construct work? +## How does Cost Monitoring Construct work? Cost Monitoring Construct uses AWS Tagging practice to track resources related to an specific application, creates proper alert with respect to the defined budget limit and provide overview dashbords. The tool is highly customizable and allows you to customize it to your budgeting strategy based on your specific needs. @@ -24,7 +24,10 @@ Cost Monitoring Construct provides the following features: - **Budgets:** Allows you to set budgets for each applications. It will automatically set up alerts to notify you when your actual costs exceed your budgeted costs. It also continues to track the cost and sending alert if an application continues to cost drastically. - **Integration:** Integrates with various tools and monitoring services, such as AWS Cost Explorer and Datadog. -# What is it useful for? +> [!WARNING] +> Tags used to create and monitor budgets must first be [activated as cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html). Ensure your chosen one is activated, otherwise the budgets won't work! + +## What is it useful for? Cost Monitoring Construct is useful for anyone who uses AWS and wants to keep their costs under control. It is particularly useful for: @@ -32,11 +35,11 @@ Cost Monitoring Construct is useful for anyone who uses AWS and wants to keep th - **Large enterprises:** Cost Monitoring Construct can help large enterprises to optimize their cloud usage and reduce costs across multiple teams and departments. - **Developers:** Cost Monitoring Construct can help developers to track their usage and costs across multiple projects and services. -# What is this _not_ useful for? +## What is this _not_ useful for? The Cost Monitoring Construct is not a magical tool that can solve all of your cloud cost problems. In spite of the fact that it can bring clarity and help you to identify areas where you can reduce costs, you must make the necessary decisions about your infrastructure on your own. -# Which programming languages Cost Monitoring Construct supports? +## Which programming languages Cost Monitoring Construct supports? Cost Monitoring Construct has been developed using JSII technolgy to provide interfaces for different modern programming languages. Currently, it supports the following languages: @@ -46,8 +49,7 @@ Cost Monitoring Construct has been developed using JSII technolgy to provide int - [.NET](https://www.nuget.org/packages/DataChef.CostMonitoringConstruct) - [Java](https://central.sonatype.com/artifact/co.datachef/costmonitoringconstruct/1.1.0/versions) -> **✏️ Note** -> +> [!NOTE] > Go will be supported soon but for now you can build it from the source. If you have any questions or need help with Cost Monitoring Construct, you can reach out to our support team at [support@datachef.co](mailto:support@datachef.co). @@ -459,12 +461,12 @@ new ApplicationCostMonitoringProps(applicationName: string, monthlyLimitInDollar | **Name** | **Type** | **Description** | | --- | --- | --- | -| applicationName | string | *No description.* | -| monthlyLimitInDollars | number | *No description.* | -| otherStacksIncludedInBudget | aws-cdk-lib.Stack[] | *No description.* | -| defaultTopic | string | *No description.* | -| subscribers | string[] | *No description.* | -| costAllocationTag | string | *No description.* | +| applicationName | string | - the name of application to label resources with it. | +| monthlyLimitInDollars | number | - montly limit in US Dollors. | +| otherStacksIncludedInBudget | aws-cdk-lib.Stack[] | - optional other stack to track their resources alog with the default stack. | +| defaultTopic | string | - default SNS topic name. | +| subscribers | string[] | - list of email address that the CostMonitoring will use to send alerts to. | +| costAllocationTag | string | - Tag key used to track resources' expenditure. | --- @@ -472,36 +474,52 @@ new ApplicationCostMonitoringProps(applicationName: string, monthlyLimitInDollar - *Type:* string +the name of application to label resources with it. + --- ##### `monthlyLimitInDollars`Required - *Type:* number +montly limit in US Dollors. + --- ##### `otherStacksIncludedInBudget`Optional - *Type:* aws-cdk-lib.Stack[] +optional other stack to track their resources alog with the default stack. + --- ##### `defaultTopic`Optional - *Type:* string +default SNS topic name. + +Only if provided, the BudgetStratgy creates an SNS topic and send notifications to it. + --- ##### `subscribers`Optional - *Type:* string[] +list of email address that the CostMonitoring will use to send alerts to. + --- ##### `costAllocationTag`Optional - *Type:* string +Tag key used to track resources' expenditure. + +Only if provided, it will be used to tag the application resources. Defaults to `cm:application` + --- @@ -510,12 +528,12 @@ new ApplicationCostMonitoringProps(applicationName: string, monthlyLimitInDollar | **Name** | **Type** | **Description** | | --- | --- | --- | -| applicationName | string | *No description.* | -| monthlyLimitInDollars | number | *No description.* | -| costAllocationTag | string | *No description.* | -| defaultTopic | string | *No description.* | -| otherStacksIncludedInBudget | aws-cdk-lib.Stack[] | *No description.* | -| subscribers | string[] | *No description.* | +| applicationName | string | - the name of application to label resources with it. | +| monthlyLimitInDollars | number | - montly limit in US Dollors. | +| costAllocationTag | string | - Tag key used to track resources' expenditure. | +| defaultTopic | string | - default SNS topic name. | +| otherStacksIncludedInBudget | aws-cdk-lib.Stack[] | - optional other stack to track their resources alog with the default stack. | +| subscribers | string[] | - list of email address that the CostMonitoring will use to send alerts to. | --- @@ -527,6 +545,8 @@ public readonly applicationName: string; - *Type:* string +the name of application to label resources with it. + --- ##### `monthlyLimitInDollars`Required @@ -537,6 +557,8 @@ public readonly monthlyLimitInDollars: number; - *Type:* number +montly limit in US Dollors. + --- ##### `costAllocationTag`Optional @@ -547,6 +569,10 @@ public readonly costAllocationTag: string; - *Type:* string +Tag key used to track resources' expenditure. + +Only if provided, it will be used to tag the application resources. Defaults to `cm:application` + --- ##### `defaultTopic`Optional @@ -557,6 +583,10 @@ public readonly defaultTopic: string; - *Type:* string +default SNS topic name. + +Only if provided, the BudgetStratgy creates an SNS topic and send notifications to it. + --- ##### `otherStacksIncludedInBudget`Optional @@ -567,6 +597,8 @@ public readonly otherStacksIncludedInBudget: Stack[]; - *Type:* aws-cdk-lib.Stack[] +optional other stack to track their resources alog with the default stack. + --- ##### `subscribers`Optional @@ -577,6 +609,8 @@ public readonly subscribers: string[]; - *Type:* string[] +list of email address that the CostMonitoring will use to send alerts to. + --- From ef25142414eb1de5c583d945778e60f14e68063c Mon Sep 17 00:00:00 2001 From: Zambo <47462792+wtfzambo@users.noreply.github.com> Date: Fri, 3 May 2024 09:14:37 +0200 Subject: [PATCH 4/6] Update docs/python.md Co-authored-by: Kiarash Kiani --- docs/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python.md b/docs/python.md index fbfe739..4aca8e4 100644 --- a/docs/python.md +++ b/docs/python.md @@ -12,7 +12,7 @@ pip install cost-monitoring-construct Getting started is very simple: just add the following snippet to your code and adapt it to the situation. -Remember to enable the [cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html), otherwise the budgets won't work! +> [!WARNING] ApplicationCostMonitoring uses AWS Tags to track resources' usages. You must [activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) your chosen tag key (`cm:application` by default) under Cost Allocation Tags. The tag key will appear in the AWS console up to 24 hours after at least one AWS resource has been created with that tag. ```python import aws_cdk as cdk From 300ce6d65b4434dd6583dc2f1f72438b7fe158ed Mon Sep 17 00:00:00 2001 From: Zambo <47462792+wtfzambo@users.noreply.github.com> Date: Fri, 3 May 2024 09:14:48 +0200 Subject: [PATCH 5/6] Update README.md Co-authored-by: Kiarash Kiani --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f0748d2..700010b 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Cost Monitoring Construct provides the following features: - **Integration:** Integrates with various tools and monitoring services, such as AWS Cost Explorer and Datadog. > [!WARNING] -> Tags used to create and monitor budgets must first be [activated as cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html). Ensure your chosen one is activated, otherwise the budgets won't work! +> ApplicationCostMonitoring uses AWS Tags to track resources' usages. You must [activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) your chosen tag key (`cm:application` by default) under Cost Allocation Tags. The tag key will appear in the AWS console up to 24 hours after at least one AWS resource has been created with that tag. ## What is it useful for? From 3e27bcf85ec444238c45382ae458c41b2ab4ad2e Mon Sep 17 00:00:00 2001 From: Federico Zambelli Date: Fri, 3 May 2024 09:17:46 +0200 Subject: [PATCH 6/6] docs: update API.md --- API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API.md b/API.md index fd50b6b..375ce3e 100644 --- a/API.md +++ b/API.md @@ -25,7 +25,7 @@ Cost Monitoring Construct provides the following features: - **Integration:** Integrates with various tools and monitoring services, such as AWS Cost Explorer and Datadog. > [!WARNING] -> Tags used to create and monitor budgets must first be [activated as cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html). Ensure your chosen one is activated, otherwise the budgets won't work! +> ApplicationCostMonitoring uses AWS Tags to track resources' usages. You must [activate](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) your chosen tag key (`cm:application` by default) under Cost Allocation Tags. The tag key will appear in the AWS console up to 24 hours after at least one AWS resource has been created with that tag. ## What is it useful for?