CodeGreen Configuration Guide¶

Complete guide to configuring CodeGreen for optimal performance and accuracy.

Table of Contents¶

Configuration File Locations
Configuration Structure
NEMB Measurement Settings
Instrumentation Options
Language-Specific Settings
Validation and Testing
Migration from Old Configs
Troubleshooting

Configuration File Locations¶

CodeGreen searches for configuration files in this priority order:

<install_dir>/config/codegreen.json (project root)
<install_dir>/build/bin/config/codegreen.json
~/.codegreen/codegreen.json (user home)

The first file found is used. The default config ships at config/codegreen.json in the project root.

Custom Config¶

# User-level override
mkdir -p ~/.codegreen
cp config/codegreen.json ~/.codegreen/codegreen.json
# Edit as needed

Configuration Structure¶

Minimal Working Configuration¶

{
  "version": "0.1.0",
  "measurement": {
    "nemb": {
      "enabled": true,
      "coordinator": {
        "measurement_interval_ms": 1
      },
      "timing": {
        "precision": "high"
      },
      "providers": {
        "intel_rapl": { "enabled": true }
      }
    }
  }
}

Complete Configuration Reference¶

{
  "version": "0.1.0",

  "measurement": {
    "nemb": {
      "enabled": true,

      "coordinator": {
        "measurement_interval_ms": 1,
        "measurement_buffer_size": 100000,
        "auto_restart_failed_providers": true,
        "provider_restart_interval": 5000,
        "cross_validation": true,
        "cross_validation_threshold": 0.05
      },

      "timing": {
        "precision": "high",
        "clock_source": "auto"
      },

      "providers": {
        "intel_rapl": {
          "enabled": true,
          "domains": ["package", "pp0", "dram"],
          "validation_enabled": true
        },
        "nvidia_nvml": {
          "enabled": true,
          "device_indices": [0],
          "validation_enabled": true
        },
        "amd_rocm": {
          "enabled": false
        }
      },

      "accuracy": {
        "target_uncertainty_percent": 1.0,
        "measurement_validation": true,
        "outlier_detection": true,
        "noise_filtering": "adaptive",
        "statistical_validation": true,
        "confidence_threshold": 0.95
      }
    }
  },

  "instrumentation": {
    "checkpoint_strategy": "functions",
    "track_invocations": true,
    "track_threads": true,
    "language_specific": {
      "python": {
        "instrument_loops": false,
        "max_recursion_depth": 100
      },
      "cpp": {
        "instrument_loops": false,
        "track_templates": true
      },
      "java": {
        "instrument_loops": false,
        "track_lambdas": true
      }
    }
  },

  "paths": {
    "temp_directory": {
      "base": "${SYSTEM_TEMP}",
      "prefix": "codegreen_",
      "cleanup_on_exit": true
    },
    "database": {
      "default_path": "${USER_HOME}/.codegreen/energy_data.db"
    },
    "logs": {
      "directory": "${USER_HOME}/.codegreen/logs",
      "level": "INFO",
      "max_files": 10,
      "max_size_mb": 50
    }
  },

  "languages": {
    "python": {
      "executable": "python3",
      "runtime_module": "codegreen_runtime.py",
      "extensions": [".py", ".pyw", ".pyi"]
    },
    "c": {
      "executable": "gcc",
      "compiler_flags": ["-O0", "-g"],
      "extensions": [".c", ".h"]
    },
    "cpp": {
      "executable": "g++",
      "compiler_flags": ["-O0", "-g", "-std=c++17"],
      "extensions": [".cpp", ".cxx", ".cc", ".hpp", ".h"]
    },
    "java": {
      "executable": "java",
      "compiler": "javac",
      "extensions": [".java"]
    }
  },

  "output": {
    "format": "json",
    "verbose": false
  },

  "developer": {
    "debug_mode": false,
    "preserve_temp_files": false
  }
}

NEMB Measurement Settings¶

Coordinator Settings¶

Setting	Default	Options	Description
`measurement_interval_ms`	1	1-100	Background polling interval (lower = more accurate)
`measurement_buffer_size`	100000	1000-1000000	Circular buffer size for energy readings
`auto_restart_failed_providers`	true	true/false	Automatically restart crashed providers
`provider_restart_interval`	5000	1000-60000	Wait time (ms) before restart

Performance vs Accuracy:

// High Accuracy (recommended for profiling)
"coordinator": {
  "measurement_interval_ms": 1,
  "measurement_buffer_size": 100000
}

// Balanced (default)
"coordinator": {
  "measurement_interval_ms": 10,
  "measurement_buffer_size": 10000
}

// Low Overhead (production monitoring)
"coordinator": {
  "measurement_interval_ms": 100,
  "measurement_buffer_size": 1000
}

Timing Settings¶

Setting	Default	Options	Description
`precision`	high	low/medium/high	Measurement precision level
`clock_source`	auto	auto/tsc/monotonic	High-resolution timer source

Precision Levels: - high: 1ms sampling, ~1% overhead, ±2% accuracy - medium: 10ms sampling, ~0.1% overhead, ±5% accuracy - low: 100ms sampling, ~0.01% overhead, ±10% accuracy

Clock Sources: - auto: Automatically select best (TSC → MONOTONIC_RAW → MONOTONIC) - tsc: Time Stamp Counter (x86/x64 only, nanosecond precision) - monotonic: CLOCK_MONOTONIC (all platforms, nanosecond precision)

Provider Settings¶

Intel RAPL:

"intel_rapl": {
  "enabled": true,
  "domains": ["package", "pp0", "dram"],
  "validation_enabled": true
}

Available domains: - package: Total CPU package energy - pp0: Core energy (all cores) - pp1: Uncore/GPU energy (integrated GPU) - dram: Memory subsystem energy - psys: Platform energy (Skylake+)

NVIDIA NVML:

"nvidia_nvml": {
  "enabled": true,
  "device_indices": [0],
  "validation_enabled": true
}

AMD ROCm:

"amd_rocm": {
  "enabled": false
}

Instrumentation Options¶

Checkpoint Strategy¶

"instrumentation": {
  "checkpoint_strategy": "functions",
  "track_invocations": true,
  "track_threads": true
}

Strategies: - minimal: Only entry/exit of main function - functions: All function boundaries (default, recommended) - blocks: Function boundaries + loop blocks - all: Maximum instrumentation (high overhead)

Invocation Tracking: - track_invocations: true: Adds #inv_N to checkpoint names for recursive functions - track_threads: true: Adds _tTHREADID for multi-threaded programs

Language-Specific Settings¶

Python:

"python": {
  "instrument_loops": false,
  "max_recursion_depth": 100
}

C/C++:

"cpp": {
  "instrument_loops": false,
  "track_templates": true
}

Java:

"java": {
  "instrument_loops": false,
  "track_lambdas": true
}

Language-Specific Settings¶

Compiler Configuration¶

C Programs:

"c": {
  "executable": "gcc",
  "compiler_flags": ["-O0", "-g"],
  "extensions": [".c", ".h"]
}

C++ Programs:

"cpp": {
  "executable": "g++",
  "compiler_flags": ["-O0", "-g", "-std=c++17"],
  "extensions": [".cpp", ".cxx", ".cc", ".hpp", ".h"]
}

Note: CodeGreen defaults to -O2 for realistic energy measurement. Use -O0 only if you need to measure unoptimized code.

Validation and Testing¶

Validate Configuration¶

# Check JSON syntax
python3 -m json.tool config/codegreen.json

# Show current active configuration
codegreen config --show

# Test with minimal workload
codegreen measure-workload --duration 3

Common Validation Errors¶

Error: Invalid precision value

// WRONG
"precision": "maximum"

// CORRECT
"precision": "high"

Error: Provider name mismatch

// WRONG
"nvidia_gpu": { "enabled": true }

// CORRECT
"nvidia_nvml": { "enabled": true }

Error: Missing required fields

// INCOMPLETE
"nemb": {
  "enabled": true
}

// COMPLETE
"nemb": {
  "enabled": true,
  "coordinator": {
    "measurement_interval_ms": 1
  }
}

Migration from Old Configs¶

From PMT-based Config (v0.0.x)¶

Old Structure:

{
  "pmt": {
    "preferred_sensors": ["rapl", "nvml"],
    "measurement_interval_ms": 1
  }
}

New Structure:

{
  "measurement": {
    "nemb": {
      "coordinator": {
        "measurement_interval_ms": 1
      },
      "providers": {
        "intel_rapl": { "enabled": true },
        "nvidia_nvml": { "enabled": true }
      }
    }
  }
}

Migration Script¶

# Backup old config
cp config/codegreen.json config/codegreen.json.backup

# Copy new template
cp config/codegreen.json.template config/codegreen.json

# Edit with your settings
codegreen config --edit

Troubleshooting¶

Config Not Loading¶

# Check which config file is being used
codegreen info --verbose

# Output will show:
# Configuration loaded from: /path/to/codegreen.json

Syntax Errors¶

# Validate JSON syntax
python3 -m json.tool config/codegreen.json

# Use a JSON validator
python3 -m json.tool config/codegreen.json

Permission Issues¶

# Set up RAPL access (creates codegreen group + udev rule)
sudo codegreen init-sensors
# Then log out/in for group changes

Performance Issues¶

# Check measurement overhead
codegreen doctor --verbose

# Reduce precision if needed
{
  "timing": { "precision": "low" },
  "coordinator": { "measurement_interval_ms": 100 }
}

Environment Variable Substitution¶

CodeGreen supports environment variables in config values:

{
  "paths": {
    "temp_directory": {
      "base": "${SYSTEM_TEMP}"
    },
    "database": {
      "default_path": "${USER_HOME}/.codegreen/energy_data.db"
    }
  }
}

Available Variables: - ${USER_HOME}: User's home directory - ${SYSTEM_TEMP}: System temp directory (/tmp) - ${EXECUTABLE_DIR}: CodeGreen installation directory - Any custom environment variable: ${MY_VAR}

Runtime Environment Variables¶

Variable	Description
`CODEGREEN_CONFIG`	Path to configuration file
`CODEGREEN_DEBUG`	Enable debug output
`CODEGREEN_LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)
`CODEGREEN_CHECKPOINT_THROTTLE_MS`	Minimum interval (ms) between checkpoint recordings; reduces overhead for high-frequency checkpoints

Best Practices¶

Start with Defaults: Use the provided config/codegreen.json template
Validate Early: Run python3 -m json.tool config/codegreen.json after changes
Test Incrementally: Change one setting at a time
Monitor Overhead: Use codegreen doctor to check measurement impact
Version Control: Commit project-specific configs to git
Document Changes: Add comments (strip before using JSON parsers)

Command Reference¶

# Show current configuration
codegreen config --show

# Edit configuration
codegreen config --edit

# Reset to defaults
codegreen config --reset

# Validate JSON syntax
python3 -m json.tool config/codegreen.json

CodeGreen Configuration Guide¶

Table of Contents¶

Configuration File Locations¶

Custom Config¶

Configuration Structure¶

Minimal Working Configuration¶

Complete Configuration Reference¶

NEMB Measurement Settings¶

Coordinator Settings¶

Timing Settings¶

Provider Settings¶

Instrumentation Options¶

Checkpoint Strategy¶

Language-Specific Settings¶

Language-Specific Settings¶

Compiler Configuration¶

Validation and Testing¶

Validate Configuration¶

Common Validation Errors¶

Migration from Old Configs¶

From PMT-based Config (v0.0.x)¶

Migration Script¶

Troubleshooting¶

Config Not Loading¶

Syntax Errors¶

Permission Issues¶

Performance Issues¶

Environment Variable Substitution¶

Runtime Environment Variables¶

Best Practices¶

Command Reference¶

See Also¶