From 829d6e48a6a7a1f1fef1d8b35c589e6227d5412e Mon Sep 17 00:00:00 2001 From: Lana Brindley Date: Mon, 30 Aug 2021 13:25:38 +1000 Subject: [PATCH] Promscale section (#82) * set up for promscale section * Promscale content * move up one level * Move to top level * Remove promscale from this level * Fix syntax * Add missing directory * Update promscale/page-index/page-index.js Co-authored-by: Ryan Booz * Adds index * Apply suggestions from code review Co-authored-by: Matvey Arye * fix page index * Edits per feedback * Edits per feedback Co-authored-by: Ryan Booz Co-authored-by: Matvey Arye Co-authored-by: Jacob --- page-index/page-index.js | 3 +- promscale/index.md | 35 ++++++++ promscale/install-promscale.md | 80 +++++++++++++++++++ promscale/page-index/page-index.js | 15 ++++ .../getting-started/access-timescaledb.md | 2 - 5 files changed, 132 insertions(+), 3 deletions(-) create mode 100644 promscale/index.md create mode 100644 promscale/install-promscale.md create mode 100644 promscale/page-index/page-index.js diff --git a/page-index/page-index.js b/page-index/page-index.js index 84f99ddb37..1d675f4d11 100644 --- a/page-index/page-index.js +++ b/page-index/page-index.js @@ -2,13 +2,14 @@ const apiReferencePageIndex = require('../api/page-index/page-index') const timescaleDbPageIndex = require('../timescaledb/page-index/page-index') const timescaleForgePageIndex = require('../timescale-forge/page-index/page-index') const timescaleCloudPageIndex = require('../timescale-cloud/page-index/page-index') - +const promscalePageIndex = require('../promscale/page-index/page-index') module.exports = [ ...timescaleDbPageIndex, ...apiReferencePageIndex, ...timescaleForgePageIndex, ...timescaleCloudPageIndex, + ...promscalePageIndex, { Title: "GitHub", type: 'external', diff --git a/promscale/index.md b/promscale/index.md new file mode 100644 index 0000000000..f84a794f01 --- /dev/null +++ b/promscale/index.md @@ -0,0 +1,35 @@ +# Promscale +Promscale allows you to extract more meaningful insights from your metrics data. +It is an open source long-term store for Prometheus data designed for analytics. +Promscale is built on top of TimescaleDB, and is a horizontally scalable and +operationally mature platform for Prometheus data that uses PromQL and SQL to +allow you to ask any question, create any dashboard, and achieve greater +visibility into your systems. + +Promscale has consistently been one of the only long-term stores for Prometheus +data that continues to maintain top performance. It received a 100% compliance +test score each time, with no cross-cutting concerns, from PromLab's [PromQL +Compliance Test Suite][promlabs]. + +For more information about Promscale, see our [blog post][promscale-blog], or +check out the [demo][promscale-demo]. If you have any questions, you can join +the Promscale channel on the [TimescaleDB Community Slack][slack]. + +## Promscale architecture +Prometheus writes data to the Promscale Connector using its `remote_write` +interface. The Connector writes data to TimescaleDB. PromQL queries can be +directed to the Connector, or to the Prometheus instance, which then reads data +from the Connector using the `remote_read` interface. The Connector then fetches +data from TimescaleDB. SQL queries can be directed to TimescaleDB directly. + +Promscale architecture diagram + +For a detailed description of this architecture, see our [design +document][design-doc]. + + +[promscale-blog]: https://blog.timescale.com/blog/promscale-analytical-platform-long-term-store-for-prometheus-combined-sql-promql-postgresql/ +[promscale-demo]: https://youtu.be/FWZju1De5lc +[slack]: https://slack.timescale.com/ +[promlabs]: https://promlabs.com/promql-compliance-test-results/2020-12-01/promscale +[design-doc]: https://docs.google.com/document/d/1e3mAN3eHUpQ2JHDvnmkmn_9rFyqyYisIgdtgd3D1MHA/edit?usp=sharing diff --git a/promscale/install-promscale.md b/promscale/install-promscale.md new file mode 100644 index 0000000000..dbc0e456c6 --- /dev/null +++ b/promscale/install-promscale.md @@ -0,0 +1,80 @@ +# Install Promscale +There are several different methods for installing Promscale. This section +describes installing from a pre-built Docker image. For alternative installation +methods, see the [Promscale GitHub repository][promscale-github]. + +If you have a Kubernetes cluster with Helm installed, you can use the +observability suite for Kubernetes (tobs) to install a full metric collection +and visualization solution including Prometheus, Grafana, Promscale, and a +preview version of PromLens. To learn how to do this, watch our +[demo video][tobs-demo]. For more information about tobs, see the +[tobs GitHub repository][tobs-gh]. + +If you want to migrate data from Prometheus into Promscale, you can use +[Prom-migrator][prom-migrator-blog], an open-source, universal Prometheus data +migration tool that can move data from one remote-storage system to another. + +## Install Promscale from a Docker image +You can install the Promscale Connector with a Docker image from +[Docker Hub][promscale-docker-hub]. To see the latest available images, see +the [Promscale Releases on GitHub][promscale-releases-github]. + +### Procedure: Installing Promscale from a Docker image +1. Create a network specific to Promscale-TimescaleDB: + ```bash + docker network create --driver bridge promscale-timescaledb + ``` +1. Install and run TimescaleDB with the Promscale extension: + ```bash + docker run --name timescaledb -e \ + POSTGRES_PASSWORD= -d -p 5432:5432 \ + --network promscale-timescaledb \ + timescaledev/promscale-extension:latest-pg12 \ + postgres -csynchronous_commit=off + ``` +1. Run Promscale: + ```bash + docker run --name promscale -d -p 9201:9201 \ + --network promscale-timescaledb timescale/promscale: \ + -db-password= -db-port=5432 -db-name=postgres \ + -db-host=timescaledb -db-ssl-mode=allow + ``` + In this example, we use `db-ssl-mode=allow`, which is suitable for testing + purposes. For production environments, use `db-ssl-mode=require` instead. + + +## Configure Prometheus for Promscale +You need to tell Prometheus to use the remote storage connector. By setting +Prometheus to `read_recent` it means that Prometheus queries data from Promscale +for all PromQL queries. You can do that by opening the `prometheus.yml` +configuration file, and adding these lines: +```yaml +remote_write: + - url: "http://:9201/write" +remote_read: + - url: "http://:9201/read" + read_recent: true +``` + +For more information about configuring Prometheus for Promscale, see the [Promscale documentation][promscale-config-github]. + +## Configure the Promscale Connector +You can configure the Promscale Connector using flags at the command prompt, environment variables, or a YAML configuration file. When processing commands, precedence is granted in this order: +1. CLI flag +1. Environment variable +1. Configuration file value +1. Default value + +All environment variables are prefixed with `PROMSCALE`. + +For more information about configuring Promscale, see the [Promscale CLI documentation][promscale-cli-github], or use the `promscale -h` command. + + +[tobs-demo]: https://youtu.be/MSvBsXOI1ks +[tobs-gh]: https://github.com/timescale/tobs +[prom-migrator-blog]: https://blog.timescale.com/blog/introducing-prom-migrator-a-universal-open-source-prometheus-data-migration-tool/ +[promscale-github]: https://github.com/timescale/promscale +[promscale-docker-hub]: https://hub.docker.com/r/timescale/promscale/ +[promscale-releases-github]: https://github.com/timescale/promscale/releases +[promscale-config-github]: https://github.com/timescale/promscale/blob/master/docs/configuring_prometheus.md +[promscale-cli-github]: https://github.com/timescale/promscale/blob/master/docs/cli.md diff --git a/promscale/page-index/page-index.js b/promscale/page-index/page-index.js new file mode 100644 index 0000000000..b9d2e71b7d --- /dev/null +++ b/promscale/page-index/page-index.js @@ -0,0 +1,15 @@ +module.exports = [ + { + title: 'Promscale', + filePath: 'index.md', + href: 'promscale', + name: 'Promscale', + excerpt: + 'Promscale is an open source long-term store for Prometheus data designed for analytics, built on top of TimescaleDB.', + children: [ + { + href: 'install-promscale', + }, + ], + }, +]; diff --git a/timescaledb/getting-started/access-timescaledb.md b/timescaledb/getting-started/access-timescaledb.md index 16419610fb..97d85ad3c1 100644 --- a/timescaledb/getting-started/access-timescaledb.md +++ b/timescaledb/getting-started/access-timescaledb.md @@ -26,7 +26,6 @@ If your client doesn't have `psql` installed, follow the instructions provided in our How-to guides for [Installing `psql`](/timescaledb/latest/how-to-guides/connecting/psql/) and then return here. - ## Connect to your TimescaleDB server Now that we've confirmed that `psql` is installed, it's time to connect to your Timescale Forge instance. @@ -56,6 +55,5 @@ in the placeholder above Now that you've connected to your Timescale Forge service, let's look at how to quickly add data so that you can quickly start to explore the power of TimescaleDB. - [install-psql]: /how-to-guides/connecting/psql/ [launch-timescaledb]: /getting-started/launch-timescaledb/