Add --core-log-level and docs demonstrating how to control core logs (#877)

### What
Add a `--core-log-level` command-line option and `CORE_LOG_LEVEL`
environment variable to configure Stellar Core's log level at startup.
Update README with usage examples for the new option as well as document
the HTTP command interface for per-partition log control. Add
corresponding `core_log_level` input to the GitHub Action.

### Why
Enable users to troubleshoot issues by easily adjusting core log
verbosity. There have been cases where trace-level logs would have aided
debugging. While it's possible to use core's http command to alter, it
is not well know and relatively complicated and doesn't ensure that the
additional logs are being recorded from start.

Close #850

---------

Co-authored-by: Copilot <[email protected]>

Author: leighmcculloch

README.md

@@ -165,6 +165,45 @@ To enable [Stellar Lab](https://github.com/stellar/laboratory) which will use th
 
 **Note: In `--local` mode the `core` service always runs no matter what options are passed, the `friendbot` faucet service runs whenever `horizon` is running, and `horizon` is run when `rpc` is requested so that friendbot is available.**
 
+### Core Options
+
+#### `--core-log-level`
+
+Set Stellar Core's log level at startup. Valid values are (case-sensitive):
+
+| Level | Description |
+| ----- | ----------- |
+| FATAL | Only log fatal errors |
+| ERROR | Log errors and above |
+| WARNING | Log warnings and above |
+| INFO | Log info and above |
+| DEBUG | Log debug and above (default for `--local`) |
+| TRACE | Log everything (very verbose) |
+
+Example:
+
+```shell
+docker run -p "8000:8000" stellar/quickstart --local --core-log-level DEBUG
+```
+
+For more granular control over specific subsystems, you can use Stellar Core's HTTP command interface on port 11626. First, expose the port:
+
+```shell
+docker run -p "8000:8000" -p "11626:11626" stellar/quickstart --local
+```
+
+Then adjust log levels per partition:
+
+```shell
+# Set History partition to TRACE level
+curl "http://localhost:11626/ll?level=TRACE&partition=History"
+
+# Set SCP partition to DEBUG level
+curl "http://localhost:11626/ll?level=DEBUG&partition=SCP"
+```
+
+Available partitions: `Fs`, `SCP`, `Bucket`, `Database`, `History`, `Process`, `Ledger`, `Overlay`, `Herder`, `Tx`, `LoadGen`, `Work`, `Invariant`, `Perf`
+
 ### Stellar Lab
 
 Stellar Lab is an interactive toolkit for exploring and interacting with the Stellar network. It allows developers to build, sign, simulate, and submit transactions, and to make requests to both the Friendbot, RPC, and Horizon APIs. Lab is also built-in to Quickstart.
@@ -229,6 +268,7 @@ The action supports several configuration options. None are required and default
     network: "local"                      # Network: local, testnet, futurenet (default: "local")
     enable: "core,horizon,rpc"            # Services to enable (default: "core,horizon,rpc")
     protocol_version: ""                  # Protocol version to run for 'local' network only (leave blank for default for image)"
+    core_log_level: ""                    # Core log level: FATAL, ERROR, WARNING, INFO, DEBUG, TRACE (default: "")
     enable_logs: "true"                   # Enable container logs (default: "true")
     health_interval: "10"                 # Time between health checks in seconds (default: "10")
     health_timeout: "5"                   # Maximum time for each health check in seconds (default: "5")

action.yml

@@ -20,6 +20,9 @@ inputs:
   protocol_version:
     description: "Protocol version to run for 'local' network only (leave blank for default for image)"
     default: ""
+  core_log_level:
+    description: "Stellar Core log level (FATAL, ERROR, WARNING, INFO, DEBUG, TRACE)"
+    default: ""
   enable_logs:
     description: "Boolean flag enabling the logs"
     default: "true"
@@ -87,8 +90,9 @@ runs:
         -p 11826:11826 
         -e ENABLE_LOGS="${{ inputs.enable_logs }}"
         -e ENABLE="${{ inputs.enable }}"
-        -e NETWORK="${{ inputs.network }}" 
-        -e PROTOCOL_VERSION="${{ inputs.protocol_version }}" 
+        -e NETWORK="${{ inputs.network }}"
+        -e PROTOCOL_VERSION="${{ inputs.protocol_version }}"
+        -e CORE_LOG_LEVEL="${{ inputs.core_log_level }}"
         --health-cmd "curl --no-progress-meter -X POST -H 'Content-Type: application/json' -d 
         '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"getHealth\"}' 'http://localhost:8000/rpc' 
         | grep 'healthy'

common/core/bin/start

@@ -5,6 +5,11 @@ while ! psql -U stellar -c 'select 1' core &> /dev/null ; do
   sleep 1
 done
 
+# Source environment file if it exists
+if [ -f /opt/stellar/core/etc/env ]; then
+  source /opt/stellar/core/etc/env
+fi
+
 echo "starting core..."
 set -e
-exec /usr/bin/stellar-core --conf "/opt/stellar/core/etc/stellar-core.cfg" run
+exec /usr/bin/stellar-core --conf "/opt/stellar/core/etc/stellar-core.cfg" run ${CORE_LOG_LEVEL:+--ll "$CORE_LOG_LEVEL"}

local/core/etc/stellar-core.cfg

@@ -15,8 +15,6 @@ NODE_IS_VALIDATOR=true
 #DATABASE="sqlite3://stellar.db"
 DATABASE="postgresql://dbname=core host=localhost user=stellar password=__PGPASS__"
 
-COMMANDS=["ll?level=debug"]
-
 FAILURE_SAFETY=0
 UNSAFE_QUORUM=true
 #The public keys of the Stellar testnet servers

start

@@ -41,6 +41,7 @@ export PROTOCOL_VERSION_DEFAULT="$(< /image.json jq -r '.config.protocol_version
 : "${ENABLE_SOROBAN_RPC_ADMIN_ENDPOINT:=false}"
 : "${ENABLE_RPC_ADMIN_ENDPOINT:=$ENABLE_SOROBAN_RPC_ADMIN_ENDPOINT}"
 : "${ENABLE_CORE_MANUAL_CLOSE:=false}"
+: "${CORE_LOG_LEVEL:=}"
 : "${LIMITS:=testnet}"
 
 QUICKSTART_INITIALIZED=false
@@ -192,6 +193,10 @@ function process_args() {
     --randomize-network-passphrase)
       RANDOMIZE_NETWORK_PASSPHRASE=true
       ;;
+    --core-log-level)
+      CORE_LOG_LEVEL="$1"
+      shift
+      ;;
     *)
       echo "Unknown container arg $ARG" >&2
       exit 1
@@ -457,6 +462,18 @@ function init_stellar_core() {
 
   pushd $COREHOME
   run_silent "chown-core" chown -R stellar:stellar .
+
+  # Write core environment file for runtime configuration.
+  # This runs on every startup to support changing settings on restart.
+  # Default to "debug" for local network to maintain backward compatibility.
+  local core_log_level="$CORE_LOG_LEVEL"
+  if [ -z "$core_log_level" ] && [ "$NETWORK" = "local" ]; then
+    core_log_level="debug"
+  fi
+  cat > $COREHOME/etc/env <<EOF
+CORE_LOG_LEVEL="$core_log_level"
+EOF
+
   if [ -f $COREHOME/.quickstart-initialized ]; then
     echo "core: already initialized"