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
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| ServiceName | string | “teranode” | SERVICE_NAME | Service identification for monitoring |
| ClientName | string | “defaultClientName” | clientName | Client/node identification |
| DataFolder | string | “data” | dataFolder | Data storage directory |
| Context | string | (from SETTINGS_CONTEXT) | SETTINGS_CONTEXT | CRITICAL - Settings context selector |
Tracing Settings
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| TracingEnabled | bool | false | tracing_enabled | CRITICAL - Enable distributed tracing |
| TracingSampleRate | float64 | 0.01 | tracing_SampleRate | Tracing sample rate (1% default) |
| TracingCollectorURL | *url.URL | http://localhost:4318 | tracing_collector_url | Jaeger/OTLP collector endpoint |
Logging Settings
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| Logger | string | "" | logger | Logger implementation selection |
| LogLevel | string | “INFO” | logLevel | CRITICAL - Logging verbosity level |
| PrettyLogs | bool | true | prettyLogs | Human-readable log formatting |
| JSONLogging | bool | false | jsonLogging | JSON-structured log output |
Debug Toggles
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| Debug.All | bool | false | debug_all | Enable every subsystem debug log |
| Debug.File | bool | false | debug_file | Low-level filesystem operation logs |
| Debug.Blobstore | bool | false | debug_blobstore | High-level blob store API call logs with stack traces |
| Debug.UTXOStore | bool | false | debug_utxostore | UTXO 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=trueis set in blob store URL configuration
debug_utxostore - UTXO store file operations:
- Similar to
debug_filebut 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=trueis set)debug_blobstore = true→ enables only Blobstore logsdebug_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
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| SecurityLevelHTTP | int | 0 | securityLevelHTTP | CRITICAL - HTTP (0) vs HTTPS (non-zero) |
| ServerCertFile | string | "" | server_certFile | Required for HTTPS - TLS certificate file |
| ServerKeyFile | string | "" | server_keyFile | Required for HTTPS - TLS private key file |
gRPC Global Settings
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| GRPCResolver | string | "" | grpc_resolver | gRPC name resolver configuration |
| GRPCMaxRetries | int | 40 | grpc_max_retries | CRITICAL - Maximum gRPC retry attempts |
| GRPCRetryBackoff | time.Duration | 250ms | grpc_retry_backoff | Retry backoff duration |
| SecurityLevelGRPC | int | 0 | security_level_grpc | gRPC security level |
| UsePrometheusGRPCMetrics | bool | true | use_prometheus_grpc_metrics | Enable gRPC Prometheus metrics |
| GRPCAdminAPIKey | string | "" | grpc_admin_api_key | Required shared credential for Blockchain and its clients; empty or invalid keys prevent Blockchain startup |
| GRPCEnableReflection | bool | false | grpc_enable_reflection | Opt in to gRPC reflection for development diagnostics; Blockchain reflection requires authentication |
Monitoring and Profiling
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| StatsPrefix | string | “gocore” | stats_prefix | Statistics metric prefix |
| PrometheusEndpoint | string | "" | prometheusEndpoint | Prometheus metrics endpoint |
| HealthCheckHTTPListenAddress | string | “:8000” | health_check_httpListenAddress | CRITICAL - Health check server binding |
| ProfilerAddr | string | "" | profilerAddr | Go pprof profiler address |
| UseDatadogProfiler | bool | false | use_datadog_profiler | Enable Datadog profiler integration |
Database and Storage
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| PostgresCheckAddress | string | “localhost:5432” | postgres_check_address | PostgreSQL connection check address |
| GlobalBlockHeightRetention | uint32 | 288 | global_blockHeightRetention | CRITICAL - 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.
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| MaxOpenConns | int | 50 | postgres_maxOpenConns | Maximum number of open database connections |
| MaxIdleConns | int | 10 | postgres_maxIdleConns | Maximum number of idle connections in pool |
| ConnMaxLifetime | time.Duration | 5m | postgres_connMaxLifetime | Maximum time a connection can be reused |
| ConnMaxIdleTime | time.Duration | 1m | postgres_connMaxIdleTime | Maximum time a connection can remain idle |
| RetryMaxAttempts | int | 3 | postgres_retryMaxAttempts | Maximum retry attempts for transient errors |
| RetryBaseDelay | time.Duration | 100ms | postgres_retryBaseDelay | Base delay for retry backoff |
| RetryEnabled | bool | false | postgres_retryEnabled | Enable retries for transient errors |
| CircuitBreakerEnabled | bool | false | postgres_circuitBreakerEnabled | Enable circuit breaker for database operations |
| CircuitBreakerFailureThreshold | int | 5 | postgres_circuitBreakerFailureThreshold | Consecutive failures before opening circuit |
| CircuitBreakerHalfOpenMax | int | 3 | postgres_circuitBreakerHalfOpenMax | Successful probes required to close circuit |
| CircuitBreakerCooldown | time.Duration | 30s | postgres_circuitBreakerCooldown | Duration circuit stays open before testing |
| CircuitBreakerFailureWindow | time.Duration | 10s | postgres_circuitBreakerFailureWindow | Time 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
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| UseCgoVerifier | bool | true | use_cgo_verifier | CRITICAL - Use CGO-based signature verification |
| LocalTestStartFromState | string | "" | local_test_start_from_state | TESTING ONLY - Initial test state |
Configuration Dependencies
Settings Context System
Contextis set viaSETTINGS_CONTEXTenvironment variable- Controls which settings overrides are applied from settings.conf
- Common contexts:
dev,test,docker,operator,mainnet,teratestnet - Example:
SETTINGS_CONTEXT=devapplies settings with.devsuffix
Tracing Configuration
-
When
TracingEnabled = true:- Requires valid
TracingCollectorURL(Jaeger/OTLP endpoint) TracingSampleRatecontrols sampling (0.01 = 1% of traces)- Integrates with OpenTelemetry for distributed tracing
- Requires valid
Logging Configuration
LogLevelvalues: “DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL”PrettyLogs = true: Human-readable colored output (development)JSONLogging = true: Structured JSON logs (production)- Cannot enable both
PrettyLogsandJSONLoggingsimultaneously - Subsystem debug toggles (
debug_*) still requirelogLevel = DEBUG
HTTPS Configuration
-
When
SecurityLevelHTTP != 0:- Requires valid
ServerCertFile(PEM format) - Requires valid
ServerKeyFile(PEM format) - Applies to HTTP servers across all services
- Requires valid
gRPC Configuration
GRPCMaxRetriescontrols retry behavior for all gRPC clientsGRPCRetryBackoffdetermines delay between retriesUsePrometheusGRPCMetricsenables gRPC method-level metricsGRPCAdminAPIKeyused for administrative gRPC endpoints
Health Check System
HealthCheckHTTPListenAddressstarts 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
| Setting | Validation | Impact |
|---|---|---|
| SecurityLevelHTTP | 0 = HTTP, non-zero = HTTPS | Service startup |
| ServerCertFile | Required when HTTPS enabled | TLS configuration |
| ServerKeyFile | Required when HTTPS enabled | TLS configuration |
| TracingCollectorURL | Must be valid URL when tracing enabled | Tracing functionality |
| LogLevel | Must be valid level | Logging behavior |
| HealthCheckHTTPListenAddress | Must be valid address | Health check availability |
Configuration Examples
Development Configuration
SETTINGS_CONTEXT = dev
logLevel = DEBUG
prettyLogs = true
jsonLogging = false
tracing_enabled = false
health_check_httpListenAddress = :8000Production 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 = :9090HTTPS-Enabled Configuration
securityLevelHTTP = 1
server_certFile = /path/to/cert.pem
server_keyFile = /path/to/key.pemHigh-Performance Configuration
use_cgo_verifier = true
grpc_max_retries = 60
grpc_retry_backoff = 100ms
use_prometheus_grpc_metrics = trueTesting Configuration
SETTINGS_CONTEXT = test
logLevel = DEBUG
local_test_start_from_state = IDLE
postgres_check_address = localhost:15432Settings Context Hierarchy
Settings are loaded in the following priority order (highest to lowest):
- Environment Variables: Direct OS environment variables
- Context-Specific Settings:
setting.{context}from settings.conf - Multi-Level Contexts:
setting.{context1}.{context2}for nested contexts - Default Settings: Base
settingvalue from settings.conf - 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)