From 0100507467cf514add2566bfd4ce793472e1ea33 Mon Sep 17 00:00:00 2001
From: Oleksii Sholik <oleksii@sholik.dev>
Date: Tue, 3 Dec 2024 14:59:29 +0200
Subject: [PATCH] docs: document LOG_LEVEL and LOG_COLORS config options
 (#2067)

---
 packages/sync-service/.env.dev           |  2 +-
 packages/sync-service/.env.test          |  2 +-
 packages/sync-service/config/runtime.exs |  2 +-
 website/docs/api/config.md               | 65 ++++++++++++++++++------
 4 files changed, 52 insertions(+), 19 deletions(-)

diff --git a/packages/sync-service/.env.dev b/packages/sync-service/.env.dev
index fceb8f73c5..9d9ed047fe 100644
--- a/packages/sync-service/.env.dev
+++ b/packages/sync-service/.env.dev
@@ -1,4 +1,4 @@
-ELECTRIC_LOG_LEVEL=debug
+ELECTRIC_LOGGING_LEVEL=debug
 DATABASE_URL=postgresql://postgres:password@localhost:54321/electric?sslmode=disable
 ELECTRIC_ENABLE_INTEGRATION_TESTING=true
 ELECTRIC_CACHE_MAX_AGE=1
diff --git a/packages/sync-service/.env.test b/packages/sync-service/.env.test
index 11cd391a92..9ee7d94cd6 100644
--- a/packages/sync-service/.env.test
+++ b/packages/sync-service/.env.test
@@ -1,2 +1,2 @@
-ELECTRIC_LOG_LEVEL=info
+ELECTRIC_LOGGING_LEVEL=info
 DATABASE_URL=postgresql://postgres:password@localhost:54321/postgres?sslmode=disable
diff --git a/packages/sync-service/config/runtime.exs b/packages/sync-service/config/runtime.exs
index 7c50efd0f5..3dd0c1f8ab 100644
--- a/packages/sync-service/config/runtime.exs
+++ b/packages/sync-service/config/runtime.exs
@@ -8,7 +8,7 @@ if config_env() in [:dev, :test] do
 end
 
 log_level_config =
-  env!("ELECTRIC_LOG_LEVEL", :string, "info")
+  env!("ELECTRIC_LOGGING_LEVEL", :string, "info")
   |> Electric.ConfigParser.parse_log_level()
 
 case log_level_config do
diff --git a/website/docs/api/config.md b/website/docs/api/config.md
index 0b6b2de641..1ab0703b7a 100644
--- a/website/docs/api/config.md
+++ b/website/docs/api/config.md
@@ -133,26 +133,17 @@ By default, Electric binds to IPv4. Enable this to listen on IPv6 addresses as w
 
 </EnvVarConfig>
 
-### ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD
+### ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD
 
 <EnvVarConfig
-    name="ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD"
+    name="ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD"
     defaultValue="10485760"
     example="20971520">
 
 Limit the maximum size of a shape log response, to ensure they are cached by
-upstream caches. Defaults to 10MB (10 * 1024 * 1024). See [#1581](https://github.com/electric-sql/electric/issues/1581) for context.
+upstream caches. Defaults to 10MB (10 * 1024 * 1024).
 
-</EnvVarConfig>
-
-### ELECTRIC_LOG_OTP_REPORTS
-
-<EnvVarConfig
-    name="ELECTRIC_LOG_OTP_REPORTS"
-    defaultValue="false"
-    example="true">
-
-Enable [OTP SASL](https://www.erlang.org/doc/apps/sasl/sasl_app.html) reporting at runtime.
+See [#1581](https://github.com/electric-sql/electric/issues/1581) for context.
 
 </EnvVarConfig>
 
@@ -180,7 +171,7 @@ Default `max-age` for the cache headers of the HTTP API.
 
 </EnvVarConfig>
 
-### ElECTRIC_CACHE_STALE_AGE
+### ELECTRIC_CACHE_STALE_AGE
 
 <EnvVarConfig
     name="ELECTRIC_CACHE_STALE_AGE"
@@ -300,6 +291,50 @@ Enable sending telemetry data to a StatsD reporting endpoint.
 
 </EnvVarConfig>
 
+## Logging
+
+### ELECTRIC_LOGGING_LEVEL
+
+<EnvVarConfig
+    name="ELECTRIC_LOGGING_LEVEL"
+    optional="true"
+    example="debug">
+
+Verbosity of Electric's log output.
+
+Available levels, in the order of increasing verbosity:
+- `error`
+- `warning`
+- `info`
+- `debug`
+
+</EnvVarConfig>
+
+### ELECTRIC_LOGGING_COLORS
+
+<EnvVarConfig
+    name="ELECTRIC_LOGGING_COLORS"
+    optional="true"
+    example="false">
+
+Enable or disable ANSI coloring of Electric's log output.
+
+By default, coloring is enabled when Electric's stdout is connected to a terminal. This may be undesirable in certain runtime environments, such as AWS which displays ANSI color codes using escape sequences and may incorrectly split log entries into multiple lines.
+
+</EnvVarConfig>
+
+### ELECTRIC_LOGGING_OTP_REPORTS
+
+<EnvVarConfig
+    name="ELECTRIC_LOGGING_OTP_REPORTS"
+    defaultValue="false"
+    example="true">
+
+Enable [OTP SASL](https://www.erlang.org/doc/apps/sasl/sasl_app.html) reporting at runtime.
+
+</EnvVarConfig>
+
+
 ## Usage reporting
 
 ### ELECTRIC_USAGE_REPORTING
@@ -312,5 +347,3 @@ These environment variables allow configuration of anonymous usage data reportin
     example="true">
 
 Configure anonymous usage data about the instance being sent to a central checkpoint service. Collected information is anonymised and doesn't contain any information from the replicated data. You can read more about it in our [telemetry docs](../reference/telemetry.md#anonymous-usage-data).
-
-</EnvVarConfig>