From c5404ea2852c3e21b4940429faa93db4bae3c432 Mon Sep 17 00:00:00 2001
From: Jeff Bruemmer <jeff.bruemmer@gmail.com>
Date: Tue, 4 Jun 2024 10:43:18 -0400
Subject: [PATCH] Docs env var info (#43150)
---
.../backend/src/metabase_enterprise/audit_db.clj | 2 +-
.../src/metabase_enterprise/llm/settings.clj | 9 ++++++---
.../sso/integrations/sso_settings.clj | 7 +++++--
src/metabase/cmd/resources/other-env-vars.md | 7 -------
src/metabase/driver/util.clj | 5 ++++-
src/metabase/models/login_history.clj | 4 +++-
src/metabase/public_settings.clj | 13 ++++++++++---
.../query_processor/middleware/constraints.clj | 10 ++++++++--
src/metabase/server/middleware/auth.clj | 5 ++++-
src/metabase/server/middleware/session.clj | 5 +++--
src/metabase/task/truncate_audit_tables.clj | 10 +++++++++-
test/metabase/cmd/env_var_dox_test.clj | 2 +-
12 files changed, 54 insertions(+), 25 deletions(-)
diff --git a/enterprise/backend/src/metabase_enterprise/audit_db.clj b/enterprise/backend/src/metabase_enterprise/audit_db.clj
index 8d7a8d99409..98d00b5a354 100644
--- a/enterprise/backend/src/metabase_enterprise/audit_db.clj
+++ b/enterprise/backend/src/metabase_enterprise/audit_db.clj
@@ -209,7 +209,7 @@
:visibility :internal
:setter :none
:audit :never
- :doc false)
+ :doc "Setting this environment variable to false can also come in handy when migrating environments, as it can simplify the migration process.")
(def ^:constant SKIP_CHECKSUM_FLAG
"If `last-analytics-checksum` is set to this value, we will skip calculating checksums entirely and *always* reload the
diff --git a/enterprise/backend/src/metabase_enterprise/llm/settings.clj b/enterprise/backend/src/metabase_enterprise/llm/settings.clj
index 0dbbff3cb0e..021e7472f6a 100644
--- a/enterprise/backend/src/metabase_enterprise/llm/settings.clj
+++ b/enterprise/backend/src/metabase_enterprise/llm/settings.clj
@@ -7,12 +7,14 @@
(deferred-tru "The OpenAI Model (e.g. 'gpt-4', 'gpt-3.5-turbo')")
:visibility :settings-manager
:default "gpt-4-turbo-preview"
- :export? false)
+ :export? false
+ :doc "This feature is experimental.")
(defsetting ee-openai-api-key
(deferred-tru "The OpenAI API Key used in Metabase Enterprise.")
:visibility :settings-manager
- :export? false)
+ :export? false
+ :doc "This feature is experimental.")
(defsetting ee-ai-features-enabled
(deferred-tru "Enable AI features.")
@@ -22,4 +24,5 @@
:export? false
:setter (fn [new-value]
(when (some? (ee-openai-api-key))
- (setting/set-value-of-type! :boolean :ee-ai-features-enabled new-value))))
+ (setting/set-value-of-type! :boolean :ee-ai-features-enabled new-value)))
+ :doc "This feature is experimental.")
diff --git a/enterprise/backend/src/metabase_enterprise/sso/integrations/sso_settings.clj b/enterprise/backend/src/metabase_enterprise/sso/integrations/sso_settings.clj
index 00d33ac8a46..6792eb575c3 100644
--- a/enterprise/backend/src/metabase_enterprise/sso/integrations/sso_settings.clj
+++ b/enterprise/backend/src/metabase_enterprise/sso/integrations/sso_settings.clj
@@ -221,7 +221,8 @@ on your IdP, this usually looks something like `http://www.example.com/141xkex60
:feature :sso-jwt
:audit :getter
:setter (comp (partial setting/set-value-of-type! :json :jwt-group-mappings)
- (partial mu/validate-throw validate-group-mappings)))
+ (partial mu/validate-throw validate-group-mappings))
+ :doc "JSON object containing JWT to Metabase group mappings, where keys are JWT groups and values are lists of Metabase groups IDs.")
(defsetting jwt-configured
(deferred-tru "Are the mandatory JWT settings configured?")
@@ -242,7 +243,9 @@ on your IdP, this usually looks something like `http://www.example.com/141xkex60
:getter (fn []
(if (jwt-configured)
(setting/get-value-of-type :boolean :jwt-enabled)
- false)))
+ false))
+ :doc "When set to true, will enable JWT authentication with the options configured in the MB_JWT_* variables.
+ This is for JWT SSO authentication, and has nothing to do with Static embedding, which is MB_EMBEDDING_SECRET_KEY.")
(define-multi-setting-impl integrations.common/send-new-sso-user-admin-email? :ee
:getter (fn [] (setting/get-value-of-type :boolean :send-new-sso-user-admin-email?))
diff --git a/src/metabase/cmd/resources/other-env-vars.md b/src/metabase/cmd/resources/other-env-vars.md
index 8d447773fce..171003df760 100644
--- a/src/metabase/cmd/resources/other-env-vars.md
+++ b/src/metabase/cmd/resources/other-env-vars.md
@@ -257,13 +257,6 @@ Default: `200000`
Maximum idle time for a connection, in milliseconds.
-### `MB_JETTY_MAXQUEUED`
-
-Type: integer<br>
-Default: _"FIX ME"_
-
-Maximum number of requests to be queued when all threads are busy.
-
### `MB_JETTY_MAXTHREADS`
Type: integer<br>
diff --git a/src/metabase/driver/util.clj b/src/metabase/driver/util.clj
index 1b7c32cf9e3..d506dfb1f44 100644
--- a/src/metabase/driver/util.clj
+++ b/src/metabase/driver/util.clj
@@ -124,7 +124,10 @@
;; Don't set the timeout too low -- I've had Circle fail when the timeout was 1000ms on *one* occasion.
:default (if config/is-test?
3000
- 10000))
+ 10000)
+ :doc "Timeout in milliseconds for connecting to databases, both Metabase application database and data connections.
+ In case you're connecting via an SSH tunnel and run into a timeout, you might consider increasing this value
+ as the connections via tunnels have more overhead than connections without.")
(defn- connection-error? [^Throwable throwable]
(and (some? throwable)
diff --git a/src/metabase/models/login_history.clj b/src/metabase/models/login_history.clj
index f0e70872e54..f0fec76204b 100644
--- a/src/metabase/models/login_history.clj
+++ b/src/metabase/models/login_history.clj
@@ -48,7 +48,9 @@
:type :boolean
:visibility :internal
:setter :none
- :default true)
+ :default true
+ :doc "This variable also controls the geocoding service that Metabase uses to know the location of your logged in users.
+ Setting this variable to false also disables this reverse geocoding functionality.")
(def LoginHistory
"Used to be the toucan1 model name defined using [[toucan.models/defmodel]], now it's a reference to the toucan2 model name.
diff --git a/src/metabase/public_settings.clj b/src/metabase/public_settings.clj
index 86f0587e911..bf1b4b1534c 100644
--- a/src/metabase/public_settings.clj
+++ b/src/metabase/public_settings.clj
@@ -322,7 +322,9 @@
:visibility :internal
:type :string
:feature :whitelabel
- :audit :getter)
+ :audit :getter
+ :doc "The base URL where dashboard notitification links will point to instead of the Metabase base URL.
+ Only applicable for users who utilize interactive embedding and subscriptions.")
(defsetting deprecation-notice-version
(deferred-tru "Metabase version for which a notice about usage of deprecated features has been shown.")
@@ -709,7 +711,10 @@ See [fonts](../configuring-metabase/fonts.md).")
:type :boolean
:visibility :public
:default nil
- :audit :getter)
+ :audit :getter
+ :doc "The user login session will always expire after the amount of time defined in MAX_SESSION_AGE (by default 2 weeks).
+ This overrides the “Remember me†checkbox when logging in.
+ Also see the Changing session expiration documentation page.")
(defsetting version
"Metabase's version info"
@@ -893,7 +898,9 @@ See [fonts](../configuring-metabase/fonts.md).")
(let [value (setting/get-value-of-type :positive-integer :attachment-table-row-limit)]
(if-not (pos-int? value)
20
- value))))
+ value)))
+ :doc "Range: 1-100. To limit the total number of rows included in the file attachment
+ for an email dashboard subscription, use MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
;; This is used by the embedding homepage
(defsetting example-dashboard-id
diff --git a/src/metabase/query_processor/middleware/constraints.clj b/src/metabase/query_processor/middleware/constraints.clj
index 329c042980f..7c4f901cf93 100644
--- a/src/metabase/query_processor/middleware/constraints.clj
+++ b/src/metabase/query_processor/middleware/constraints.clj
@@ -33,7 +33,10 @@
:export? true
:type :integer
:database-local :allowed
- :audit :getter)
+ :audit :getter
+ :doc "Must be less than 1048575, and less than the number configured in MB_AGGREGATED_QUERY_ROW_LIMIT.
+ This environment variable also affects how many rows Metabase returns in dashboard subscription attachments.
+ See also MB_AGGREGATED_QUERY_ROW_LIMIT.")
(setting/defsetting aggregated-query-row-limit
(deferred-tru "Maximum number of rows to return for aggregated queries via the API.")
@@ -41,7 +44,10 @@
:export? true
:type :integer
:database-local :allowed
- :audit :getter)
+ :audit :getter
+ :doc "Must be less than 1048575. This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.
+ This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.
+ See also MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
(defn default-query-constraints
"Default map of constraints that we apply on dataset queries executed by the api."
diff --git a/src/metabase/server/middleware/auth.clj b/src/metabase/server/middleware/auth.clj
index 397897590b2..cc04fc517dd 100644
--- a/src/metabase/server/middleware/auth.clj
+++ b/src/metabase/server/middleware/auth.clj
@@ -33,7 +33,10 @@
(defsetting api-key
"When set, this API key is required for all API requests."
- :visibility :internal)
+ :visibility :internal
+ :doc "Middleware that enforces validation of the client via the request header X-Metabase-Apikey.
+ If the header is available, then it’s validated against MB_API_KEY.
+ When it matches, the request continues; otherwise it’s blocked with a 403 Forbidden response.")
(defn static-api-key
"We don't want to change the name of the setting from `MB_API_KEY`, but we want to differentiate this static key from
diff --git a/src/metabase/server/middleware/session.clj b/src/metabase/server/middleware/session.clj
index b5c10da5276..42721643292 100644
--- a/src/metabase/server/middleware/session.clj
+++ b/src/metabase/server/middleware/session.clj
@@ -104,8 +104,9 @@
{:possible-values possible-session-cookie-samesite-values
:session-cookie-samesite normalized-value
:http-status 400})))))
- :doc "See [Embedding Metabase in a different domain](../embedding/interactive-embedding.md#embedding-metabase-in-a-different-domain). Related to [MB_EMBEDDING_APP_ORIGIN](#mb_embedding_app_origin). Read more about [interactive Embedding](../embedding/interactive-embedding.md). Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).
-")
+ :doc "See [Embedding Metabase in a different domain](../embedding/interactive-embedding.md#embedding-metabase-in-a-different-domain).
+ Related to [MB_EMBEDDING_APP_ORIGIN](#mb_embedding_app_origin). Read more about [interactive Embedding](../embedding/interactive-embedding.md).
+ Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).")
(defmulti default-session-cookie-attributes
"The appropriate cookie attributes to persist a newly created Session to `response`."
diff --git a/src/metabase/task/truncate_audit_tables.clj b/src/metabase/task/truncate_audit_tables.clj
index 2ee25aa9f92..3193f298592 100644
--- a/src/metabase/task/truncate_audit_tables.clj
+++ b/src/metabase/task/truncate_audit_tables.clj
@@ -60,7 +60,15 @@
min-retention-days)
:else
- env-var-value))))
+ env-var-value)))
+ :doc "Sets the maximum number of days Metabase preserves rows for the following application database tables:
+
+- `query_execution`
+- `audit_log`
+- `view_log`
+
+Twice a day, Metabase will delete rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).
+If set to 0, Metabase will keep all rows.")
(defn- truncate-table!
"Given a model, deletes all rows older than the configured threshold"
diff --git a/test/metabase/cmd/env_var_dox_test.clj b/test/metabase/cmd/env_var_dox_test.clj
index 8d6a6ea886e..46a2f4dcf69 100644
--- a/test/metabase/cmd/env_var_dox_test.clj
+++ b/test/metabase/cmd/env_var_dox_test.clj
@@ -13,7 +13,7 @@
ns-set))
(def admin-email-docs "### `MB_ADMIN_EMAIL`\n\n- Type: string\n- Default: `null`\n- [Configuration file name](./config-file.md): `admin-email`\n\nThe email address users should be referred to if they encounter a problem.")
-(def aggregated-query-row-limit-docs "### `MB_AGGREGATED_QUERY_ROW_LIMIT`\n\n- Type: integer\n- Default: `10000`\n- [Exported as](../installation-and-operation/serialization.md): `aggregated-query-row-limit`.\n- [Configuration file name](./config-file.md): `aggregated-query-row-limit`\n\nMaximum number of rows to return for aggregated queries via the API.")
+(def aggregated-query-row-limit-docs "### `MB_AGGREGATED_QUERY_ROW_LIMIT`\n\n- Type: integer\n- Default: `10000`\n- [Exported as](../installation-and-operation/serialization.md): `aggregated-query-row-limit`.\n- [Configuration file name](./config-file.md): `aggregated-query-row-limit`\n\nMaximum number of rows to return for aggregated queries via the API.\n\nMust be less than 1048575. This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.\n This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.\n See also MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
(def expected-docs (str/join "\n\n"
[admin-email-docs
--
GitLab