Skip to content

Examples

Fourteen end-to-end examples that ship with CodeGreen. Every script lives under examples/ in the repository and is exercised by pytest tests/test_examples.py. Each page on this site links back to the canonical source rather than duplicating it.

Run an example directly:

git clone https://github.com/SMART-Dal/codegreen.git
cd codegreen
python examples/01_quickstart_measure/main.py

Run them all through the harness:

pytest tests/test_examples.py -q

Each script prints exactly one OK: <feature>; <metrics> line on success or SKIP: <reason> when a dependency is missing.

Index

# Example What it shows Prereqs
01 Quickstart measure 30-second codegreen run intro none
02 Run with repeats Stable mean across --repeat, CV reporting none
03 Session API codegreen.Session ctx manager + @codegreen.task none
04 Project hotspots (Java) codegreen project java end-to-end JDK
05 GPT-2 staged inference Multi-task Session with time-series export torch, transformers
06 Monitor host Host-wide cumulative sampling, JSONL output none
07 Monitor PID Per-PID attribution: cgroup_v2 vs cpu_percent psutil
08 Monitor socket — single-process Per-request energy via UDS annotation, Monitor inside the webapp stdlib only
09 Project hotspots (Python) codegreen project python per-function none
10 CodeGreen vs perf Cross-validate against perf stat power/energy-pkg/ perf
11 Monitor socket — standalone Same UDS flow, but codegreen monitor runs as a separate sidecar process (production deployment shape: systemd / tmux / nohup) stdlib only
12 Monitor systemd sidecar Same sidecar pattern, supervised by user-mode systemd. Survives terminal close, SSH drop, and reboot (with linger). No root required. systemctl --user, stdlib
13 Monitor OTLP export codegreen monitor --exporter otlp streams energy metrics over OTLP/gRPC to any OpenTelemetry-compatible collector (Datadog, Honeycomb, Grafana Cloud, vendor OTel Collector). Production observability path. pip install codegreen[otlp]
14 Monitor Prometheus scrape codegreen monitor --exporter prometheus --prometheus-port PORT exposes a Prometheus-compatible /metrics endpoint. Loopback default, optional bearer-token auth, label cardinality bounded, two-Monitor isolation via per-Sink CollectorRegistry. pip install codegreen[prometheus]

"I want to..."

  • Measure a one-liner Python script -> 01
  • Get a tight mean over many runs -> 02
  • Instrument a specific function inside a long Python program -> 03
  • Find energy hotspots in a Java project -> 04
  • Profile staged ML inference (preprocess / load / generate) -> 05
  • Watch a daemon's energy in the background -> 06
  • Attribute system energy to a single PID -> 07
  • Attribute energy to individual HTTP requests (single-process) -> 08
  • Attach codegreen monitor to an already-running webapp from a separate process -> 11
  • Keep the sidecar alive across terminal close / SSH drop / reboot -> 12
  • Ship energy metrics to Datadog/Honeycomb/Grafana via OpenTelemetry -> 13
  • Expose a Prometheus-scrapeable /metrics endpoint -> 14
  • Find energy hotspots in a Python project -> 09
  • Sanity-check CodeGreen against the kernel -> 10

Attribution backends

Examples 07 and 08 surface CodeGreen's per-PID attribution. The Monitor selects a backend at start():

  • cgroup_v2 (preferred on Linux): reads cpu.stat:usage_usec from the PID's unified cgroup; share = cgroup_cpu_delta / system_cpu_busy_delta. Highly accurate even under heavy multi-tenant contention.
  • cgroup_v1 (fallback): same idea using cpuacct.usage (nanoseconds).
  • cpu_percent (last resort): psutil proc.cpu_percent / (100 * ncores); underestimates single-threaded workloads on many-core hosts because it normalizes against full system capacity.

cgroup_v2 vs cpu_percent divergence

On heavily-loaded multi-core hosts the two backends can disagree by two orders of magnitude on the same workload. Always check attribution_backend in the Monitor header before trusting per-PID energy.

The chosen backend appears as attribution_backend on every header and summary record. Override with Monitor(attribution_mode=...) or codegreen monitor --attribution-mode ....

Deep dives

Beyond the 14 canonical examples, the language-organized pages cover patterns that don't fit a single script:

  • Python (manual + auto) -- every Session form, plot export, per-domain attribution
  • C/C++ -- compilation chain, NEMB linkage
  • Java -- javac integration, JNI bridge