diff --git a/docs/docs/experimentation/connect-a-warehouse/_category_.json b/docs/docs/experimentation/connect-a-warehouse/_category_.json new file mode 100644 index 000000000000..18f3a1a978bb --- /dev/null +++ b/docs/docs/experimentation/connect-a-warehouse/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Connect a Warehouse", + "position": 2 +} diff --git a/docs/docs/experimentation/connect-a-warehouse/clickhouse.md b/docs/docs/experimentation/connect-a-warehouse/clickhouse.md new file mode 100644 index 000000000000..5f60add0437d --- /dev/null +++ b/docs/docs/experimentation/connect-a-warehouse/clickhouse.md @@ -0,0 +1,96 @@ +--- +title: Connect ClickHouse +sidebar_label: ClickHouse +sidebar_position: 1 +slug: /experimentation/connect-clickhouse +description: Store and query experiment events in your own ClickHouse instance. +--- + +import CodeBlock from '@theme/CodeBlock'; import eventsSql from '../../../../experimentation/clickhouse/events.sql?raw'; + +:::info Beta + +Experimentation is in beta. + +::: + +Flagsmith writes experiment events to a table in your ClickHouse instance and computes experiment results by querying it +there. Each environment has one [warehouse connection](/experimentation/connect-a-warehouse). + +## Before you start + +- On Flagsmith Cloud, a [Scale-Up or Enterprise subscription](https://www.flagsmith.com/pricing). +- An instance reachable from Flagsmith: on Flagsmith Cloud, over the internet; when self-hosting, from your Flagsmith + API and warehouse delivery. +- An administrative user with `CREATE USER`, `GRANT`, `CREATE DATABASE` and `CREATE TABLE` privileges, to run the setup + SQL. +- When self-hosting, the event ingestion service, Kafka and warehouse delivery. See + [Self-Hosting and Open Source](/experimentation/self-hosting). + +## 1. Create the events table and user + +Run this once against your instance. Replace `` and `` with your own values. The same SQL is +available to copy from the Flagsmith dashboard. + +{eventsSql} + +```sql +-- Create a dedicated user for Flagsmith +CREATE USER IF NOT EXISTS + IDENTIFIED WITH sha256_password BY ''; + +-- Allow it to write and read experiment events +GRANT SELECT, INSERT ON flagsmith_exp.events TO ; + +-- Allow it to check the events table exists +GRANT SHOW TABLES, SHOW COLUMNS ON flagsmith_exp.* TO ; +``` + +If you use a database other than `flagsmith_exp`, use the same name in the script and in Flagsmith. + +Flagsmith doesn't create or alter the table, so keep exactly these columns and types. + +## 2. Connect in Flagsmith + +1. Go to **Environment Settings › Warehouse** and select **ClickHouse**. +2. Fill in the connection details: + - **Host**: the hostname of your ClickHouse instance, without protocol or port. + - **Name this warehouse**: any name, e.g. `Production ClickHouse`. + - **HTTPS port**: the port of the ClickHouse HTTP(S) interface, `8443` by default. + - **Database Name**: `flagsmith_exp`, unless you changed it. + - **Username** and **Password**: the user you created in step 1. + - **Secure connection (TLS)**: always on; it can't be turned off. +3. Click **Test connection**. Once it succeeds, click **Save and continue**. The test checks that Flagsmith can connect + and that the events table exists. If the test can't connect, you can save anyway and test again later, but events + won't be delivered until it succeeds. If Flagsmith rejects a field, such as the host, fix it before saving. +4. On Flagsmith Cloud, to verify events reach your table, click **Send your first event** on the connection card; the + button disappears once the first event arrives. + +![The ClickHouse connection form with host, name, HTTPS port, database, username, password and TLS fields](/img/experimentation/warehouse-clickhouse-form.png) + +## Manage the connection + +### Change the password + +Change the user's password on your server first. Then edit the connection, enter the new password, click **Test +connection**, then click **Save changes**. Leaving the password blank keeps the current one. + +### Change server + +The host can't be changed. To use a different ClickHouse instance, disconnect and create a new connection. + +## Troubleshooting + +Errors show under a form field, below **Test connection**, or on the connection card with status **Errored** when event +delivery fails. + +| Message | Where | What to do | +| ---------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | +| Port must be a number between 1 and 65535. | Form | Fix **HTTPS port**. | +| Host must not target internal or private network addresses. | Test, card | On Flagsmith Cloud, use a host with a public address. | +| Authentication failed. | Test, card | Check **Username** and **Password**. | +| Database does not exist. | Test, card | Check **Database Name**, and that it matches the database in the setup SQL. | +| Events table not found in the configured database. Run the setup SQL to create it. | Test, card | Run the script in [step 1](#1-create-the-events-table-and-user) with the same database as the connection. | +| Could not connect to the host. | Test, card | Check **Host** and **HTTPS port**, and that the instance accepts HTTPS connections from Flagsmith. | +| The ClickHouse server rejected the request. | Test, card | Check the instance's logs for the rejected query, and that the user has the grants in step 1. | +| Connection failed. | Test, card | [Contact support](/support/). | diff --git a/docs/docs/experimentation/connect-databricks.md b/docs/docs/experimentation/connect-a-warehouse/databricks.md similarity index 99% rename from docs/docs/experimentation/connect-databricks.md rename to docs/docs/experimentation/connect-a-warehouse/databricks.md index 0bb59becc62c..20c2deab7499 100644 --- a/docs/docs/experimentation/connect-databricks.md +++ b/docs/docs/experimentation/connect-a-warehouse/databricks.md @@ -1,7 +1,8 @@ --- title: Connect Databricks -sidebar_label: Connect Databricks -sidebar_position: 2.5 +sidebar_label: Databricks +sidebar_position: 2 +slug: /experimentation/connect-databricks description: Store and query experiment events in your own Databricks workspace. --- diff --git a/docs/docs/experimentation/connect-a-warehouse.md b/docs/docs/experimentation/connect-a-warehouse/index.md similarity index 52% rename from docs/docs/experimentation/connect-a-warehouse.md rename to docs/docs/experimentation/connect-a-warehouse/index.md index 4fb6e7b53cd6..c07e079b5e5f 100644 --- a/docs/docs/experimentation/connect-a-warehouse.md +++ b/docs/docs/experimentation/connect-a-warehouse/index.md @@ -5,8 +5,6 @@ sidebar_position: 2 description: Choose where experiment events are stored, from the managed Flagsmith warehouse to your own database. --- -import CodeBlock from '@theme/CodeBlock'; import eventsSql from '../../../experimentation/clickhouse/events.sql?raw'; - :::info Beta Experimentation is in beta. @@ -54,7 +52,7 @@ Warehouse tab open. Once connected, the warehouse card shows the total number of events received and the number of unique event names, which is useful to verify that instrumentation data is arriving. -### Connection statuses +## Connection statuses The current status is shown on the warehouse card in **Environment Settings › Warehouse**. @@ -62,53 +60,17 @@ The current status is shown on the warehouse card in **Environment Settings › - **Pending Connection**: waiting for the first event to arrive. - **Connected**: events have been received; you are ready to run experiments. - **Errored**: the card shows the reason. See Troubleshooting for + [ClickHouse](/experimentation/connect-clickhouse#troubleshooting), [Databricks](/experimentation/connect-databricks#troubleshooting) or [PostgreSQL](/experimentation/connect-postgresql#troubleshooting); otherwise [contact support](/support/). -## Bring your own ClickHouse - -Instead of the managed Flagsmith warehouse, you can store experiment events in your own **ClickHouse** instance. It must -be reachable from Flagsmith: on Flagsmith Cloud, over the internet; when self-hosting, from your Flagsmith API and -warehouse delivery. - -1. Configure your instance by running the following against it, using an administrative user (the statements require - `CREATE USER`, `GRANT`, `CREATE DATABASE` and `CREATE TABLE` privileges). Replace `` and `` with - your own values. This is a one-off setup step; the same SQL is available to copy from the Flagsmith dashboard. - - {eventsSql} - - ```sql - -- Create a dedicated user for Flagsmith - CREATE USER IF NOT EXISTS - IDENTIFIED WITH sha256_password BY ''; - - -- Allow it to write and read experiment events - GRANT SELECT, INSERT ON flagsmith_exp.events TO ; - - -- Allow it to check the events table exists - GRANT SHOW TABLES, SHOW COLUMNS ON flagsmith_exp.* TO ; - ``` - -2. Go to **Environment Settings › Warehouse**, select **ClickHouse** and enter your connection details: host, HTTPS port - (8443 by default), database (`flagsmith_exp` by default), and the username and password of the user you created in - step 1. -3. Click **Test connection**. Once the test succeeds, save the connection. -4. On Flagsmith Cloud, click **Send your first event** on the connection card to verify events are arriving in your - warehouse; the button disappears once the first event is received. - -Connections use the ClickHouse HTTP(S) interface, with TLS enabled by default. - -Experiment results and exposures are computed from your ClickHouse instance. - -## Bring your own Databricks - -You can also store experiment events in your own **Databricks** workspace, and Flagsmith computes results there. See -[Connect Databricks](/experimentation/connect-databricks) for setup and troubleshooting. +## Bring your own warehouse -## Bring your own PostgreSQL +To store experiment events in your own warehouse, and have Flagsmith compute results there, connect one of: -You can store experiment events in your own **PostgreSQL** database, or a PostgreSQL-compatible service, and Flagsmith -computes results there. See [Connect PostgreSQL](/experimentation/connect-postgresql) for setup and troubleshooting. +- [ClickHouse](/experimentation/connect-clickhouse) +- [Databricks](/experimentation/connect-databricks) +- [PostgreSQL](/experimentation/connect-postgresql), or a PostgreSQL-compatible service ## Coming soon diff --git a/docs/docs/experimentation/connect-postgresql.md b/docs/docs/experimentation/connect-a-warehouse/postgresql.md similarity index 97% rename from docs/docs/experimentation/connect-postgresql.md rename to docs/docs/experimentation/connect-a-warehouse/postgresql.md index 78a34bc8e853..4f2c1f369196 100644 --- a/docs/docs/experimentation/connect-postgresql.md +++ b/docs/docs/experimentation/connect-a-warehouse/postgresql.md @@ -1,7 +1,8 @@ --- title: Connect PostgreSQL -sidebar_label: Connect PostgreSQL -sidebar_position: 2.7 +sidebar_label: PostgreSQL +sidebar_position: 3 +slug: /experimentation/connect-postgresql description: Store and query experiment events in your own PostgreSQL database. --- @@ -102,8 +103,8 @@ The host can't be changed. To use a different PostgreSQL database, disconnect an ## Performance and table growth Results queries scan the events table, so they slow down as it grows. If results become too slow, use -[ClickHouse](/experimentation/connect-a-warehouse#bring-your-own-clickhouse) or -[Databricks](/experimentation/connect-databricks), which are built for this kind of query. +[ClickHouse](/experimentation/connect-clickhouse) or [Databricks](/experimentation/connect-databricks), which are built +for this kind of query. Flagsmith doesn't delete old events or partition the table. Monitor its size and manage retention yourself. diff --git a/docs/docs/experimentation/self-hosting.md b/docs/docs/experimentation/self-hosting.md index 4324536d3e8c..a4bb96b90e93 100644 --- a/docs/docs/experimentation/self-hosting.md +++ b/docs/docs/experimentation/self-hosting.md @@ -21,6 +21,15 @@ can store experiment events in two ways: in the [Flagsmith database](#flagsmith- Set `EXPERIMENTATION_ENABLED=true` on the Flagsmith API. The **Warehouse** tab doesn't appear without it. See [environment variables](/deployment-self-hosting/core-configuration/environment-variables). +With the [Helm chart](/deployment-self-hosting/hosting-guides/kubernetes-openshift), and only the Flagsmith database, +set it on the API without enabling the chart's experimentation services: + +```yaml +api: + extraEnv: + EXPERIMENTATION_ENABLED: 'true' +``` + ## Flagsmith database :::warning @@ -51,7 +60,7 @@ table. ## Your own warehouse -Events are delivered to your own [ClickHouse](/experimentation/connect-a-warehouse#bring-your-own-clickhouse), +Events are delivered to your own [ClickHouse](/experimentation/connect-clickhouse), [Databricks](/experimentation/connect-databricks) or [PostgreSQL](/experimentation/connect-postgresql). - Also run the event ingestion service, Kafka and warehouse delivery. See [Deploying](#deploying). diff --git a/docs/static/img/experimentation/warehouse-clickhouse-form.png b/docs/static/img/experimentation/warehouse-clickhouse-form.png new file mode 100644 index 000000000000..8878e89fafb5 Binary files /dev/null and b/docs/static/img/experimentation/warehouse-clickhouse-form.png differ diff --git a/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/databricksSetupSqlDocs.test.ts b/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/databricksSetupSqlDocs.test.ts index 2b97389e5ffc..47935b498b7d 100644 --- a/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/databricksSetupSqlDocs.test.ts +++ b/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/databricksSetupSqlDocs.test.ts @@ -9,7 +9,7 @@ describe('getDatabricksSetupSql', () => { const doc = fs.readFileSync( path.join( __dirname, - '../../../../../../../../docs/docs/experimentation/connect-databricks.md', + '../../../../../../../../docs/docs/experimentation/connect-a-warehouse/databricks.md', ), 'utf8', ) diff --git a/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/postgresSetupSqlDocs.test.ts b/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/postgresSetupSqlDocs.test.ts index d47bb40e484d..3cc656ae4823 100644 --- a/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/postgresSetupSqlDocs.test.ts +++ b/frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/postgresSetupSqlDocs.test.ts @@ -9,7 +9,7 @@ describe('getPostgresOnboardingSql', () => { const doc = fs.readFileSync( path.join( __dirname, - '../../../../../../../../docs/docs/experimentation/connect-postgresql.md', + '../../../../../../../../docs/docs/experimentation/connect-a-warehouse/postgresql.md', ), 'utf8', )