Promscale section (timescale#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 <ryan@timescale.com> * Adds index * Apply suggestions from code review Co-authored-by: Matvey Arye <mat@timescale.com> * fix page index * Edits per feedback * Edits per feedback Co-authored-by: Ryan Booz <ryan@timescale.com> Co-authored-by: Matvey Arye <mat@timescale.com> Co-authored-by: Jacob <prall.jacob@gmail.com>
saltedpotatos · Aug 30, 2021 · 829d6e4 · 829d6e4
1 parent b8b48bd
commit 829d6e4
Show file tree

Hide file tree

Showing 5 changed files with 132 additions and 3 deletions.
diff --git 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
@@ -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.
+
+<img class="main-content__illustration" src="https://s3.amazonaws.com/assets.timescale.com/docs/images/promscale-arch.png" alt="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
@@ -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=<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:<version-tag> \
+    -db-password=<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://<connector-address>:9201/write"
+remote_read:
+  - url: "http://<connector-address>: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
@@ -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
@@ -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.
 </highlight>
 
-
 ## 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/