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

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	Admin API authentication key

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)

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

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

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

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 = :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):

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 setting value 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)

Developer Setup