Skip to content

Commit

Permalink
Fixed a few typos in Timestream user guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@mohannashahrad
mohannashahrad authored Aug 25, 2022
1 parent 3b1bade commit 7ee7a1d
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions cloud_templates/user_guides/timestream_guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Getting started with Timestream template guide
# Getting started with the Timestream template guide

## Setting up and prerequisites

Expand All @@ -14,7 +14,7 @@ Before you start using AWS CloudFormation, you might need to know what IAM permi

**Note**: If you are just going to use the sample demo template you can skip this section.

The AWS Cloud Development Kit (CDK) is an open source software development framework that lets you define your cloud infrastructure as code in one of its supported programming languages. It is intended for moderately to highly experienced AWS users. Refer to this [guide](https://aws.amazon.com/getting-started/guides/setup-cdk/?pg=gs&sec=gtkaws) to get started with AWS CDK.
The AWS Cloud Development Kit (CDK) is an open-source software development framework that lets you define your cloud infrastructure as code in one of its supported programming languages. It is intended for moderately to highly experienced AWS users. Refer to this [guide](https://aws.amazon.com/getting-started/guides/setup-cdk/?pg=gs&sec=gtkaws) to get started with AWS CDK.

## Template deployment and CloudFormation stack creation

Expand All @@ -24,48 +24,48 @@ You can either use the provided demo template and deploy it directly to the cons

### Sample demo template

By using the sample json template that is provided under the `demo_templates` directory, you do not need to take any further actions except creating the stack by uploading it. You only need to make sure that your IoT device sends a similar payload as below one connected to the cloud:
By using the sample JSON template that is provided under the `demo_templates` directory, you do not need to take any further actions except creating the stack by uploading it. You only need to make sure that your IoT device sends a similar payload as below once connected to the cloud:

`{`
`"Location = <string>",`
`your other key-value pairs `
`}`

For simplicity’s sake, a sample code is provided that you can run on your device to send data to IoT Core. It is an example of multiple devices sending their weather measurements. You can follow the guide under `demo_templates` to learn about how to get the sample code working. However, if you already have your own set up, you can simply work with your own program but make sure to send a json payload similar to what is mentioned above and you should be good to continue with the demo.
For simplicity’s sake, a sample code is provided that you can run on your device to send data to IoT Core. It is an example of multiple devices sending their weather measurements. You can follow the guide under `demo_templates` to learn about how to get the sample code working. However, if you already have your own setup, you can simply work with your own program but make sure to send a JSON payload similar to what is mentioned above and you should be good to continue with the demo.

Follow the steps below to create the CloudFormation stack using the sample template file.

1. Sign in to the AWS Management Console and open the [AWS CloudFormation console.](https://console.aws.amazon.com/cloudformation)
2. If this is a new CloudFormation account, choose **Create New Stack**. Otherwise, choose **Create Stack** and then select **with new resources**.
3. In the **Template** section, select **Upload a template file** and upload the json template file. Choose **Next**.
2. If this is a new CloudFormation account, select **Create New Stack**. Otherwise, choose **Create Stack** and then select **with new resources**.
3. In the **Template** section, select **Upload a template file** and upload the JSON template file. Choose **Next**.
4. In the **Specify Details** section, enter a stack name in the **Name** field.
5. If you want you can add tags to your stack. Otherwise choose **Next**.
6. Review the stack’s settings and then choose **Create.**
7. At this point, you will find the status of your stack to be `CREATE_IN_PROGRESS`. Your stack might take several minutes to get created. See next sections to learn about monitoring your stack creation.
5. If you want you can add tags to your stack. Otherwise, choose **Next**.
6. Review the stack’s settings and then select **Create.**
7. At this point, you will find the status of your stack to be `CREATE_IN_PROGRESS`. Your stack might take several minutes to get created. See the next sections to learn about monitoring your stack creation.

### Custom template

If you are interested in using the CloudFormation templates more than just for demo purposes, you need to customize the stack’s resources based on your specific use-case. Follow the steps below to do so:
If you are interested in using the CloudFormation templates more than just for demo purposes, you need to customize the stack’s resources based on your specific use case. Follow the steps below to do so:

1. Make sure that you already [set up your AWS CDK](https://aws.amazon.com/getting-started/guides/setup-cdk/?pg=gs&sec=gtkaws) environment.
2. Starting in your current directory, change your directory and go to `aws_cdk/TimestreamPattern` directory.
3. Just to verify everything is working correctly, list the stacks in your app by running `cdk ls` command. If you don't see `TimestreamPatternStack`, make sure you are currently in `TimestreamPattern` directory.
3. Just to verify everything is working correctly, list the stacks in your app by running the `cdk ls` command. If you don't see `TimestreamPatternStack`, make sure you are currently in the `TimestreamPattern` directory.
4. The structure of the files inside `TimestreamPattern` is as below:

[Image: Screen Shot 2022-08-24 at 4.40.39 PM.png]
* `timestream_pattern_stack.py` is the main code of the stack. It is here where the required resources are created.
* `tests/unit/test_timestream_pattern_stack.py` is where the unit tests of the stack is written. The unit tests check
* `tests/unit/test_timestream_pattern_stack.py` is where the unit tests of the stack are written. The unit tests check
* Right creation of the resources in addition to their properties
* Dependencies between the resources
* Right error handlings in case of input violations
* `cdk.json` tells the CDK Toolkit how to execute your app. Context values are key-value pairs that can be associated with an app, stack, or construct. You can add the context key-values to this file or in command line before synthesizing the template.
* `README.md` is where you can find the detailed instructions on how to get started with the code including: how to synthesize the template, a set of useful commands, stack’s context parameters, and details about the code.
* `cdk.out` is where the synthesized template (in a json format) will be located in.
* `cdk.json` tells the CDK Toolkit how to execute your app. Context values are key-value pairs that can be associated with an app, stack, or construct. You can add the context key-values to this file or in the command line before synthesizing the template.
* `README.md` is where you can find detailed instructions on how to get started with the code including how to synthesize the template, a set of useful commands, the stack’s context parameters, and details about the code.
* `cdk.out` is where the synthesized template (in a JSON format) will be located in.

1. Run `source .venv/bin/activate` to activate the app's Python virtual environment.
2. Run `python -m pip install -r requirements.txt` and `python -m pip install -r requirements.txt` to install the dependencies.
3. Go through the `README.md` file to learn about the context parameters that need to be set by you prior to deployment.
4. Set the context parameter values either by changing `cdk.json` file or by using the command line.
4. Set the context parameter values either by changing the `cdk.json` file or by using the command line.
1. To create a command line context variable, use the **`--context (-c) option`**, as shown in the following example: `$ cdk cdk synth -c bucket_name=mybucket`
2. To specify the same context variable and value in the `cdk.json` file, use the following code.`
{ "context": { "bucket_name": "mybucket" }`
Expand All @@ -78,7 +78,7 @@ If you are interested in using the CloudFormation templates more than just for d

### Viewing CloudFormation stack data and resources

After deployment, you may need to monitor your created stack and its resources. To do this your starting point should be AWS CloudFormation console.
After deployment, you may need to monitor your created stack and its resources. To do this your starting point should be the AWS CloudFormation console.

1. Sign in to the AWS Management Console and open the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation).
2. Choose **Stacks** tab to view all the available stacks in your account.
Expand All @@ -99,10 +99,10 @@ If you deploy and create the stack successfully, the following resources must ge
|CDKMetadata |[AWS::CDK::Metadata](https://docs.aws.amazon.com/cdk/api/v1/docs/constructs.ConstructMetadata.html) |
|Timestream database |[AWS::Timestream::Database](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-timestream-database.html) |
|Timestream table |[AWS::Timestream::Table](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-timestream-table.html) |
|IAM role and policy that grant IoT access to Timestream |[AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) [AWS::IAM::Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-policy.html) |
|IAM role and policy that grants IoT access to Timestream |[AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) [AWS::IAM::Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-policy.html) |
|IoT Rule |[AWS::IoT::TopicRule](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iot-topicrule.html) |
|CloudWatch log group to capture error logs |[AWS::Logs::LogGroup](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) |
|IAM role and policy that grant IoT access to CloudWatch |[AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) [AWS::IAM::Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-policy.html) |
|IAM role and policy that grants IoT access to CloudWatch |[AWS::IAM::Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) [AWS::IAM::Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-policy.html) |

### Handling stack failures

Expand All @@ -115,7 +115,7 @@ If CloudFormation fails to create, update, or delete your stack, you will be abl

In case of failures in stack creations or updates, CloudFormation automatically performs a rollback. However, you can also [add rollback triggers during stack creation or updating](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-rollback-triggers.html#using-cfn-rollback-triggers-create) to further monitor the state of your application. By setting up the rollback triggers if the application breaches the threshold of the alarms you've specified, it will roll back to that operation.

Finally, this [troubleshooting guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html#basic-ts-guide) is a helpful resource to refer if there is an issue in your stack.
Finally, this [troubleshooting guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html#basic-ts-guide) is a helpful resource to refer to if there is an issue in your stack.

### Estimating the cost of the stack

Expand All @@ -129,7 +129,7 @@ Now that your stack and all the required resources are created and available, yo

* If you are new to AWS IoT Core, this [guide](https://docs.aws.amazon.com/iot/latest/developerguide/connect-to-iot.html) is a great starting point to connect your device to the cloud.
* After connecting your device to IoT Core, you can use the [MQTT test client](https://docs.aws.amazon.com/iot/latest/developerguide/view-mqtt-messages.html) to monitor the MQTT messages being passed in your AWS account.
* Move to the **Rules** tab under **Message Routing** section in the [AWS IoT console](https://console.aws.amazon.com/iot/home). There you can verify the creation of the newly created topic rule and its [timestream rule action](https://docs.aws.amazon.com/iot/latest/developerguide/timestream-rule-action.html) which writes data received from your device to the Timestream database.
* Move to the **Rules** tab under the **Message Routing** section in the [AWS IoT console](https://console.aws.amazon.com/iot/home). There you can verify the creation of the newly created topic rule and its [timestream rule action](https://docs.aws.amazon.com/iot/latest/developerguide/timestream-rule-action.html) which writes data received from your device to the Timestream database.

### Query data in the Timestream service console

Expand All @@ -145,12 +145,12 @@ In the previous section, you verified that your device is connected to the cloud

* Now you can see the result of your query in a table format.
* If you cannot see any data in the query editor, follow these steps:
* First make sure that your device is connected to the cloud and is sending data by using the [MQTT test client](https://docs.aws.amazon.com/iot/latest/developerguide/view-mqtt-messages.html). More details about this are provided in the previous section.
* First, make sure that your device is connected to the cloud and is sending data by using the [MQTT test client](https://docs.aws.amazon.com/iot/latest/developerguide/view-mqtt-messages.html). More details about this are provided in the previous section.
* If your data is getting landed in IoT Core but Timestream is not receiving it, there might be an error happening while the IoT rule attempts to send data from IoT Core to Timestream. To find out about the issue, you can use the CloudWatch log group that was created by the template earlier. To do so, open the [Cloudwatch console](https://console.aws.amazon.com/cloudwatch). From the navigation bar, select **Log > Log Groups**. Find the log group name that was created by the stack earlier and select it. Now you can view the error logs to find out the issue.

### Integrating with dashboards to visualize data

In the previous section, you were able to see your device’s data in a table format under the Timestream’s table query editor. You can take a further step to visualize your data and create dashboards. Here are several possible Timestream integrations with reporting dashboards :
In the previous section, you were able to see your device’s data in a table format under Timestream’s table query editor. You can take a further step to visualize your data and create dashboards. Here are several possible Timestream integrations with reporting dashboards :

#### Amazon QuickSight

Expand All @@ -160,11 +160,11 @@ To connect Amazon Timestream to QuickSight you need to follow these steps:

1. Navigate to the AWS QuickSight console.
2. If you have never used AWS QuickSight before, you will be asked to sign up. In this case, choose **Standard** tier and the correct region as your setup.
3. During the sign up phase, give QuickSight access to your Amazon Timestream.
4. If you already have an account, give Amazon QuickSight access your Timestream by choosing **Admin >** **Manage QuickSight > Security & permissions.** Under QuickSight access to AWS services, choose **Add or remove**, then select the check box next to AWS IoT Analytics and choose **Update**.
3. During the signup phase, give QuickSight access to your Amazon Timestream.
4. If you already have an account, give Amazon QuickSight access to your Timestream by choosing **Admin >** **Manage QuickSight > Security & permissions.** Under QuickSight access to AWS services, choose **Add or remove**, then select the check box next to AWS IoT Analytics and choose **Update**.
5. From the admin Amazon QuickSight console page choose **New Analysis** and **New data set.**
6. Choose Timestream as the source and enter a name for your data source.
7. Choose your Timestream database and table to import, and then choose **Create data source**.
7. Choose your Timestream database and table to import, and then select **Create data source**.
8. After your data source is created, you can start making visualizations in Amazon QuickSight.

You can follow this [guide](https://docs.aws.amazon.com/timestream/latest/developerguide/Quicksight.html) for a more detailed explanation of the above steps. Additionally, you can refer to this [video tutorial](https://youtu.be/TzW4HWl-L8s) to make QuickSight work with Timestream.
Expand All @@ -186,7 +186,7 @@ With Amazon Managed Grafana, you can add Amazon Timestream as a data source by u

## Cleaning up the stack

To clean-up all the resources used in this demo, all you need to do is to delete the initial CloudFormation stack. To delete a stack and its resources, follow these steps:
To clean up all the resources used in this demo, all you need to do is to delete the initial CloudFormation stack. To delete a stack and its resources, follow these steps:

1. Open the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation/).
2. On the Stacks menu in the CloudFormation console, select the stack that you want to delete. (Note that the stack must be currently running.)
Expand Down

0 comments on commit 7ee7a1d

Please sign in to comment.