Simulator on Joulie

Workload and Power Simulator

Mon, 01 Jan 0001 00:00:00 +0000

This document defines the Joulie simulator design and how it integrates with Joulie.

Architecture at a glance

The simulator extends the same control path used on real nodes:

Operator writes desired node profile (NodePowerProfile).
Agent reads desired state and sends control intents.
Simulator emulates telemetry/control behavior per node and exposes HTTP endpoints.
Next reconcile loop reacts to updated simulated state.

The diagram shows the end-to-end loop:

Workload Simulator

Mon, 01 Jan 0001 00:00:00 +0000

This page documents the workload-side simulation model.

Scope

The workload simulator handles:

trace/job ingestion,
pod creation and placement via real scheduler,
per-job progress updates,
completion and pod deletion,
class inference from scheduling constraints.

Power/control dynamics are documented separately in:

Power Simulator

Trace-driven workload model

Enable with:

SIM_WORKLOAD_TRACE_PATH=/path/to/trace.jsonl

The simulator loads type=job records and schedules pods over time according to submit offsets.

Helper tools:

simulator/cmd/workloadgen (synthetic traces)
simulator/cmd/traceextract (normalize/extract traces)

Per-job execution model

Each job tracks:

Power Simulator

Mon, 01 Jan 0001 00:00:00 +0000

This page documents the power/control-side simulation model.

Scope

The power simulator handles:

node power-state variables,
RAPL/DVFS control ingestion,
frequency ramp dynamics,
power computation and capping,
energy integration.

Workload execution model is documented separately in:

Workload Simulator

Per-node state

Each simulated node tracks:

CapWatts
TargetThrottlePct
ThrottlePct
FreqScale in [f_min/f_max, 1]
CPUUtil in [0,1]
CapSaturated

Power model

At update time:

P = P_idle + (P_max - P_idle) * util^alpha * freqScale^beta

Where:

Simulator Metrics

Mon, 01 Jan 0001 00:00:00 +0000

This page documents Prometheus metrics exposed by the simulator (simulator/cmd/simulator/main.go).

Endpoint:

path: /metrics
address: simulator HTTP listen address (SIM_ADDR, default :18080)

Related debug endpoints (non-Prometheus):

/debug/nodes
/debug/events
/debug/energy

HTTP/request metrics

joulie_sim_requests_total{route,method,status} (counter)
- total HTTP requests by route/method/status
joulie_sim_request_duration_seconds{route,method} (histogram)
- request latency

Control-path metrics

joulie_sim_controls_total{node,action} (counter)
- received control actions by node/action
joulie_sim_control_actions_total{node,action,result} (counter)
- control action outcomes
- result: applied|blocked|error

Per-node simulated state metrics

joulie_sim_node_cap_watts{node} (gauge)
- current simulated effective cap
joulie_sim_node_rapl_cap_watts{node} (gauge)
- simulated RAPL cap value
joulie_sim_node_throttle_pct{node} (gauge)
- simulated DVFS throttle percent
joulie_sim_node_power_watts{node} (gauge)
- simulated node power
joulie_sim_node_cpu_util{node} (gauge)
- simulated CPU utilization
joulie_sim_node_freq_scale{node} (gauge)
- simulated frequency scale
joulie_sim_node_running_pods{node} (gauge)
- running pods observed on the node
joulie_sim_node_class_info{node,class} (gauge)
- class assignment marker (1 on active class)

Workload/job metrics

joulie_sim_job_submitted_total{class} (counter)
- jobs submitted by class
joulie_sim_job_completed_total{class,node} (counter)
- jobs completed by class and node
joulie_sim_job_completion_seconds (histogram)
- job completion latency distribution

Notes

Prometheus metrics capture online simulator state and request/control behavior.
Integrated node/cluster energy totals are exposed through /debug/energy (JSON), not as Prometheus time series in the current implementation.