BSV blockchainBSV blockchain

Global Settings

Related Topics: System Architecture, Prometheus Metrics

Global settings control system-wide behavior across all Teranode services. These settings affect tracing, logging, security, health checks, and profiling for the entire node.

Configuration Settings

Service Identification

SettingTypeDefaultEnvironment VariableUsage
ServiceNamestring“teranode”SERVICE_NAMEService identification for monitoring
ClientNamestring“defaultClientName”clientNameClient/node identification
DataFolderstring“data”dataFolderData storage directory
Contextstring(from SETTINGS_CONTEXT)SETTINGS_CONTEXTCRITICAL - Settings context selector

Tracing Settings

SettingTypeDefaultEnvironment VariableUsage
TracingEnabledboolfalsetracing_enabledCRITICAL - Enable distributed tracing
TracingSampleRatefloat640.01tracing_SampleRateTracing sample rate (1% default)
TracingCollectorURL*url.URLhttp://localhost:4318tracing_collector_urlJaeger/OTLP collector endpoint

Logging Settings

SettingTypeDefaultEnvironment VariableUsage
Loggerstring""loggerLogger implementation selection
LogLevelstring“INFO”logLevelCRITICAL - Logging verbosity level
PrettyLogsbooltrueprettyLogsHuman-readable log formatting
JSONLoggingboolfalsejsonLoggingJSON-structured log output

Debug Toggles

SettingTypeDefaultEnvironment VariableUsage
Debug.Allboolfalsedebug_allEnable every subsystem debug log
Debug.Fileboolfalsedebug_fileLow-level filesystem operation logs
Debug.Blobstoreboolfalsedebug_blobstoreHigh-level blob store API call logs with stack traces
Debug.UTXOStoreboolfalsedebug_utxostoreUTXO store file operation logs

Debug Toggle Details

Prerequisites: All debug toggles require logLevel = DEBUG to emit logs. Setting a debug flag without DEBUG log level has no effect.

debug_file - Low-level filesystem operations:

  • Detailed logs of file system I/O operations
  • File paths, byte counts, checksums, DAH cleanup operations
  • Use when debugging: disk space issues, file I/O problems, filesystem-level errors
  • Example logs: "[File] SetFromReader start key=... type=... size=...", "[File] removing expired file: ..."

debug_blobstore - High-level blob store API tracing:

  • Logs all blob store API calls (Get, Set, Exists, Del, etc.) with 5-level deep call stacks
  • Shows which code is calling blob store operations and why
  • Use when debugging: application-level blob access patterns, API usage tracking
  • Example logs: "[BlobStore][logger][Get] key ... fileType ... : called from ..."
  • Note: Only active when ?logger=true is set in blob store URL configuration

debug_utxostore - UTXO store file operations:

  • Similar to debug_file but specific to UTXO store file operations
  • Use when debugging UTXO-specific storage issues

debug_all - Enable all subsystems:

  • Shortcut to enable all debug flags at once
  • Equivalent to setting all individual flags to true
  • Use for comprehensive debugging or when you’re unsure which subsystem is involved

Hierarchical Relationships

Debug flags have hierarchical dependencies:

  • debug_file = true → enables both File logs AND Blobstore logs (when ?logger=true is set)
  • debug_blobstore = true → enables only Blobstore logs
  • debug_all = true → enables ALL debug logs across all subsystems

This hierarchy exists because file-level operations are the foundation of blob store operations. When debugging filesystem issues, you typically want to see both layers.

HTTP Security Settings

SettingTypeDefaultEnvironment VariableUsage
SecurityLevelHTTPint0securityLevelHTTPCRITICAL - HTTP (0) vs HTTPS (non-zero)
ServerCertFilestring""server_certFileRequired for HTTPS - TLS certificate file
ServerKeyFilestring""server_keyFileRequired for HTTPS - TLS private key file

gRPC Global Settings

SettingTypeDefaultEnvironment VariableUsage
GRPCResolverstring""grpc_resolvergRPC name resolver configuration
GRPCMaxRetriesint40grpc_max_retriesCRITICAL - Maximum gRPC retry attempts
GRPCRetryBackofftime.Duration250msgrpc_retry_backoffRetry backoff duration
SecurityLevelGRPCint0security_level_grpcgRPC security level
UsePrometheusGRPCMetricsbooltrueuse_prometheus_grpc_metricsEnable gRPC Prometheus metrics
GRPCAdminAPIKeystring""grpc_admin_api_keyRequired shared credential for Blockchain and its clients; empty or invalid keys prevent Blockchain startup
GRPCEnableReflectionboolfalsegrpc_enable_reflectionOpt in to gRPC reflection for development diagnostics; Blockchain reflection requires authentication

Monitoring and Profiling

SettingTypeDefaultEnvironment VariableUsage
StatsPrefixstring“gocore”stats_prefixStatistics metric prefix
PrometheusEndpointstring""prometheusEndpointPrometheus metrics endpoint
HealthCheckHTTPListenAddressstring“:8000”health_check_httpListenAddressCRITICAL - Health check server binding
ProfilerAddrstring""profilerAddrGo pprof profiler address
UseDatadogProfilerboolfalseuse_datadog_profilerEnable Datadog profiler integration

Database and Storage

SettingTypeDefaultEnvironment VariableUsage
PostgresCheckAddressstring“localhost:5432”postgres_check_addressPostgreSQL connection check address
GlobalBlockHeightRetentionuint32288global_blockHeightRetentionCRITICAL - Block height retention (2 days default)

PostgreSQL Connection Pool

Default connection pool and resilience settings for every service’s PostgreSQL store. A service can override every one of these with its own <service>_postgres_* setting (the twelve keys in the table below, e.g. blockchain_postgres_retryEnabled, utxostore_postgres_circuitBreakerCooldown). A per-service pool is only created when at least one of its twelve keys is explicitly configured - including RetryEnabled=true or an explicit CircuitBreakerEnabled (true or false) on its own. Once it exists, each numeric/duration value left at zero falls back to the global value above, and an unset CircuitBreakerEnabled inherits the global one while an explicit false is preserved (so a service can opt out of a globally-enabled breaker). RetryEnabled is the exception: it has no global fallback, so once a per-service pool exists its value (false included) replaces the global RetryEnabled outright. See e.g. Blockchain Settings and UTXO Store Settings.

SettingTypeDefaultEnvironment VariableUsage
MaxOpenConnsint50postgres_maxOpenConnsMaximum number of open database connections
MaxIdleConnsint10postgres_maxIdleConnsMaximum number of idle connections in pool
ConnMaxLifetimetime.Duration5mpostgres_connMaxLifetimeMaximum time a connection can be reused
ConnMaxIdleTimetime.Duration1mpostgres_connMaxIdleTimeMaximum time a connection can remain idle
RetryMaxAttemptsint3postgres_retryMaxAttemptsMaximum retry attempts for transient errors
RetryBaseDelaytime.Duration100mspostgres_retryBaseDelayBase delay for retry backoff
RetryEnabledboolfalsepostgres_retryEnabledEnable retries for transient errors
CircuitBreakerEnabledboolfalsepostgres_circuitBreakerEnabledEnable circuit breaker for database operations
CircuitBreakerFailureThresholdint5postgres_circuitBreakerFailureThresholdConsecutive failures before opening circuit
CircuitBreakerHalfOpenMaxint3postgres_circuitBreakerHalfOpenMaxSuccessful probes required to close circuit
CircuitBreakerCooldowntime.Duration30spostgres_circuitBreakerCooldownDuration circuit stays open before testing
CircuitBreakerFailureWindowtime.Duration10spostgres_circuitBreakerFailureWindowTime window for counting consecutive failures

Note: all five circuit breaker settings are loaded by settings.go and applied in util/sql.go, but the breaker only runs when CircuitBreakerEnabled resolves to true - and it requires the threshold, half-open, cooldown and window values to be set (the defaults above satisfy this).

Performance and Optimization

SettingTypeDefaultEnvironment VariableUsage
UseCgoVerifierbooltrueuse_cgo_verifierCRITICAL - Use CGO-based signature verification
LocalTestStartFromStatestring""local_test_start_from_stateTESTING ONLY - Initial test state

Configuration Dependencies

Settings Context System

  • Context is set via SETTINGS_CONTEXT environment variable
  • Controls which settings overrides are applied from settings.conf
  • Common contexts: dev, test, docker, operator, mainnet, teratestnet
  • Example: SETTINGS_CONTEXT=dev applies settings with .dev suffix

Tracing Configuration

  • When TracingEnabled = true:

    • Requires valid TracingCollectorURL (Jaeger/OTLP endpoint)
    • TracingSampleRate controls sampling (0.01 = 1% of traces)
    • Integrates with OpenTelemetry for distributed tracing

Logging Configuration

  • LogLevel values: “DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL”
  • PrettyLogs = true: Human-readable colored output (development)
  • JSONLogging = true: Structured JSON logs (production)
  • Cannot enable both PrettyLogs and JSONLogging simultaneously
  • Subsystem debug toggles (debug_*) still require logLevel = DEBUG

HTTPS Configuration

  • When SecurityLevelHTTP != 0:

    • Requires valid ServerCertFile (PEM format)
    • Requires valid ServerKeyFile (PEM format)
    • Applies to HTTP servers across all services

gRPC Configuration

  • GRPCMaxRetries controls retry behavior for all gRPC clients
  • GRPCRetryBackoff determines delay between retries
  • UsePrometheusGRPCMetrics enables gRPC method-level metrics
  • GRPCAdminAPIKey used for administrative gRPC endpoints

Health Check System

  • HealthCheckHTTPListenAddress starts global health check server
  • Aggregates health status from all services
  • Returns 200 OK when all services healthy, 503 otherwise
  • Critical for Kubernetes liveness/readiness probes

Performance Optimization

  • UseCgoVerifier = true: Uses secp256k1 C library (faster)
  • UseCgoVerifier = false: Uses pure Go implementation (portable)
  • CGO version provides 10-20x performance improvement for signature verification

Validation Rules

SettingValidationImpact
SecurityLevelHTTP0 = HTTP, non-zero = HTTPSService startup
ServerCertFileRequired when HTTPS enabledTLS configuration
ServerKeyFileRequired when HTTPS enabledTLS configuration
TracingCollectorURLMust be valid URL when tracing enabledTracing functionality
LogLevelMust be valid levelLogging behavior
HealthCheckHTTPListenAddressMust be valid addressHealth check availability

Configuration Examples

Development Configuration

SETTINGS_CONTEXT = dev
logLevel = DEBUG
prettyLogs = true
jsonLogging = false
tracing_enabled = false
health_check_httpListenAddress = :8000

Production Configuration

SETTINGS_CONTEXT = operator
logLevel = INFO
prettyLogs = false
jsonLogging = true
tracing_enabled = true
tracing_SampleRate = 0.05
tracing_collector_url = http://jaeger:4318
securityLevelHTTP = 1
server_certFile = /certs/server.crt
server_keyFile = /certs/server.key
use_datadog_profiler = true
prometheusEndpoint = :9090

HTTPS-Enabled Configuration

securityLevelHTTP = 1
server_certFile = /path/to/cert.pem
server_keyFile = /path/to/key.pem

High-Performance Configuration

use_cgo_verifier = true
grpc_max_retries = 60
grpc_retry_backoff = 100ms
use_prometheus_grpc_metrics = true

Testing Configuration

SETTINGS_CONTEXT = test
logLevel = DEBUG
local_test_start_from_state = IDLE
postgres_check_address = localhost:15432

Settings Context Hierarchy

Settings are loaded in the following priority order (highest to lowest):

  1. Environment Variables: Direct OS environment variables
  2. Context-Specific Settings: setting.{context} from settings.conf
  3. Multi-Level Contexts: setting.{context1}.{context2} for nested contexts
  4. Default Settings: Base setting value from settings.conf
  5. Code Defaults: Default values defined in settings.go

Example with SETTINGS_CONTEXT=docker.host.teranode1:

clientName                       = teranode           # Priority 4
clientName.docker.host.teranode1 = teranode1          # Priority 2 (wins)