Input Telemetry and Actuation Interfaces

This page describes runtime IO contracts:

  • how Joulie reads telemetry inputs,
  • how Joulie sends control intents.

It is not the /metrics exposition contract. For exported metrics, see Metrics Reference.

Why this abstraction exists

Joulie must run in two worlds with the same control logic:

  • real hardware clusters,
  • simulator/KWOK clusters.

So agent/operator logic depends on provider interfaces, not directly on sysfs or simulator HTTP shape.

Telemetry provider model

Telemetry input can come from:

  • host (real node interfaces),
  • http (simulator endpoint),
  • prometheus (cluster-level inputs, future expansion),
  • none.

Quality handling should distinguish fresh, stale, and missing samples so policy can degrade safely.

Control provider model

Control outputs are routed by backend:

  • host: write real interfaces (RAPL/cpufreq),
  • http: send intents to simulator,
  • none.

Result semantics:

  • applied
  • blocked
  • error

This allows desired vs applied behavior auditing.

Current CPU control intents

Supported intent actions:

  • rapl.set_power_cap_watts
  • dvfs.set_throttle_pct

DVFS intent is normalized as throttlePct (0..100) to stay portable across heterogeneous CPUs. Backend-specific frequency writes remain implementation details.

Current HTTP contracts

Telemetry endpoint:

  • GET /telemetry/{node}

Accepted minimal payloads include:

{ "packagePowerWatts": 245.3 }

or

{ "cpu": { "packagePowerWatts": 245.3 } }

Control endpoint:

  • POST /control/{node}

Example request:

{
  "node": "worker-01",
  "action": "dvfs.set_throttle_pct",
  "throttlePct": 20,
  "ts": "2026-02-27T00:00:00Z"
}

Expected response includes:

  • result (applied|blocked|error)
  • message
  • state (best-effort post-state)

Current host contracts

Agent host mode uses Linux interfaces:

  • RAPL energy/power cap files
  • cpufreq files for observed and enforced frequency bounds

Current deployment convention mounts host /sys into container /host-sys.

CRD integration

Current runtime responsibilities:

  • operator writes NodePowerProfile targets,
  • agent reads NodePowerProfile for desired state,
  • agent reads node-scoped TelemetryProfile for source/control routing,
  • agent writes control status under TelemetryProfile.status.control.

Next step

To see simulator-side algorithm details using these interfaces, read: