Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Repository with Improved Useability with SAM Template #27

Merged
merged 1 commit into from
Oct 4, 2023
Merged

Update Repository with Improved Useability with SAM Template #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ To send us a pull request, please:

1. Fork the repository.
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
3. Ensure local tests pass.
3. Ensure local tests pass. See [Testing Locally](#testing-locally) for more verification steps.
4. Commit to your fork using clear commit messages.
5. Send us a pull request, answering any default questions in the pull request interface.
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
Expand All @@ -40,6 +40,13 @@ GitHub provides additional document on [forking a repository](https://help.githu
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).


## Testing Locally
1. Execute and ensure all unit tests pass by executing: `go test -tags=unit -cover -v ./timestream ./`
2. Ensure IT Tests Pass(Requires AWS credentials) by executing: `go test -v ./integration`
<br>NOTE - Clear the test cache if running multiple times: `go clean -testcache`
3. If your change is related to TLS encryption between the connector and prometheus, see [README](./integration/tls/README.md) for how to test.


## Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.

Expand Down
54 changes: 49 additions & 5 deletions GETTING_STARTED.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,14 +199,21 @@ It is recommended to enable TLS encryption between Prometheus and the Prometheus
regex: .*
replacement: exampleTable
target_label: PrometheusTableLabel

remote_read:
- url: "http://localhost:9201/read"

# Replace the values for username and password with valid IAM user access key and IAM user secret access key.
basic_auth:
username: accessKey
password: secretAccessKey
```

> **NOTE**: Each Prometheus request must be authorized. Since the Prometheus Connector does not support temporary security credentials, it is recommended to use regularly [rotate IAM user access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey).

This configuration serves the following functions:

1. Configures Prometheus' remote storage destinations by setting the `url` options to the remote write endpoints, e.g. `"http://localhost:9201/write"`.
1. Configures Prometheus' remote storage destinations by setting the `url` options to the remote read and remote write endpoints, e.g. `"http://localhost:9201/write"`.
2. Configures the Amazon Timestream ingestion destination for Prometheus time series by attaching a label indicating the destination database and another label indicating the destination table for all time series. **These labels are required to be present on all Prometheus time series sent to the Prometheus Connector.** If one of the labels cannot be found on any of the time series, the Prometheus Connector will log the error and halt the program.
For an example of a complete Prometheus YAML file, see [getting_started.yml](./documentation/example/getting_started.yml).
Expand All @@ -222,7 +229,7 @@ It is recommended to enable TLS encryption between Prometheus and the Prometheus
It is recommended to secure the Prometheus requests with TLS encryption. This can be achieved by specifying the certificate authority file the `tls_config` section for Prometheus' remote read and remote write configuration. To generate self-signed certificates during development see the [Creating Self-signed TLS Certificates](#creating-self-signed-tls-certificates) section.

Here is an example of `remote_write` configuration with TLS, where `RootCA.pem` is within the same directory as the Prometheus configuration file:
Here is an example of `remote_write` and `remote_read` configuration with TLS, where `RootCA.pem` is within the same directory as the Prometheus configuration file:

```yaml
remote_write:
Expand All @@ -247,6 +254,18 @@ remote_write:
regex: .*
replacement: exampleTable
target_label: PrometheusTableLabel
remote_read:
- url: "https://localhost:9201/read"
basic_auth:
# Replace the values for username and password with valid IAM user access key and IAM user secret access key.
username: accessKey
password: secretAccessKey
tls_config:
# Ensure ca_file is a valid file path pointing to the CA certificate.
ca_file: RootCA.pem
```

## Verification
Expand Down Expand Up @@ -291,22 +310,47 @@ remote_write:
```
This sample output indicates that 340 rows has been ingested.
4. To verify the Prometheus Connector can query date from Amazon Timestream, query with Prometheus Query Language (PromQL) in the `http://localhost:9090/` in a browser, which opens Prometheus' [expression browser](https://prometheus.io/docs/visualization/browser/#expression-browser).
The PromQL must contain `database-label` and `table-label` as part of the label matchers to indicate which database and table contain the data. Here is a simple example:

```
prometheus_http_requests_total{PrometheusDatabaseLabel="exampleDatabase", PrometheusTableLabel="exampleTable"}
```
`prometheus_http_requests_total` is a metric name. `PrometheusDatabaseLabel` and `PrometheusTableLabel` are the corresponding `database-label` and `table-label` in the Prometheus configuration.
This PromQL will return all the time series from the past hour with the metric name `prometheus_http_requests_total` in `exampleTable` of `exampleDatabase`.
Here is a query result example:
![](documentation/example/query_example.PNG)

PromQL also supports regex, here is an example:
```
prometheus_http_requests_total{handler!="/api/v1/query", job=~"p*", code!~"2..", PrometheusDatabaseLabel="exampleDatabase", PrometheusTableLabel="exampleTable"}
```
This example is querying for all rows from `exampleTable` of `exampleDatabase` where:

- column `metric name` equals to `prometheus_http_requests_total`;
- column `handler` does not equal to `/api/v1/query`;
- column `job` matches the regex pattern `p*`;
- column `code` does not match the regex pattern `2..`.

For more examples, see [Prometheus Query Examples](https://prometheus.io/docs/prometheus/latest/querying/examples/).
There are other ways to execute PromQLs, such as through Prometheus' [HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/), or through [Grafana](https://grafana.com/).
## Troubleshooting
1. No Credential Providers Error
Error occurred when running the Linux binary with the following message:
```log
level=error ts=2020-11-21T00:22:06.203Z caller=utils.go:23 message="Unable to create a write client." error="NoCredentialProviders: no valid providers in chain. Deprecated.\n\tFor verbose messaging see aws.Config.CredentialsChainVerboseErrors"
level=error ts=2020-11-21T00:22:06.203Z caller=utils.go:23 message="Unable to create a query client." error="NoCredentialProviders: no valid providers in chain. Deprecated.\n\tFor verbose messaging see aws.Config.CredentialsChainVerboseErrors"
```
This error may occur when no AWS credentials can be found. Follow the steps in [Configure AWS Credentials](#configure-aws-credentials) to set up the credentials.
2. Access Denied Exception
Error occurred when running the Linux binary with the following message:
```log
level=error ts=2020-11-23T19:58:49.998Z caller=utils.go:23 message="Unable to create a write client." error="AccessDeniedException: User: arn:aws:iam::0000000000:user/username is not authorized to perform: timestream:DescribeEndpoints with an explicit deny"
level=error ts=2020-11-23T19:58:49.998Z caller=utils.go:23 message="Unable to create a query client." error="AccessDeniedException: User: arn:aws:iam::0000000000:user/username is not authorized to perform: timestream:DescribeEndpoints with an explicit deny"
```
1. Ensure the account running the Prometheus Connector has sufficient permissions to access Timestream. See all the IAM Policies for Timestream on [How Amazon Timestream Works with IAM](https://docs.aws.amazon.com/timestream/latest/developerguide/security_iam_service-with-iam.html).
Expand Down
Loading