3.3 Running the runtime
The runtime is one program that listens for HTTP requests and WebSocket connections on one port, by default http://127.0.0.1:8080 and ws://127.0.0.1:8080/ws. It runs on your machine with Java or in a Docker container. The IDE builds and starts the container itself, as 4.5 Running describes.
3.3.1 Requirements#
| Way to run | Needs |
|---|---|
| On your machine | Java 21. Python 3 on the path as python3, python or py for state machines with Python code, with the packages that this code imports |
| In Docker | Docker. The image brings Java 21 and Python 3 with the packages numpy, scipy, sympy, pandas, regex, python-dateutil and chardet |
State machines whose EVAL blocks and macros the runtime computes itself need no Python, as 3.1.6 EVAL and macros describes.
The runtime is built with the KStates, KMeta and KModel readers of karpfen-dsl-tools, which is a git submodule in the folder karpfen-dsl-tools. Clone the repository with its submodule:
git clone --recurse-submodules https://github.com/karpfenproject/karpfen-runtime.git
cd karpfen-runtime
3.3.2 Running on your machine#
The script run_local.sh builds the runtime and starts it from the folder of the repository:
./run_local.sh
The build runs without tests and ends in build/install/karpfen-runtime/bin/karpfen-runtime. The runtime reads application.conf from the folder it starts in. To start it without the script, from the folder of the repository:
./gradlew installDist -x test
./build/install/karpfen-runtime/bin/karpfen-runtime
./gradlew run builds and starts the runtime in one step, also with application.conf from the folder of the repository.
At the start the runtime prints the configuration it uses:
[Main] Configuration loaded:
[Main] Server: 127.0.0.1:8080
[Main] WebSocket enabled: true
[Main] Log level: INFO
[Main] Engine tracing: false
[Main] Default tick delay: 50ms
[Main] Default event TTL: 3000ms
[Main] Event consumption on fire: true
3.3.3 Running in Docker#
The script run_docker.sh builds the image karpfen-runtime from the Dockerfile of the repository and runs it:
./run_docker.sh
./run_docker.sh /var/log/karpfen
The script hands the container a copy of application.conf in which server.host is 0.0.0.0, so the runtime can be reached from outside the container. It maps port 8080 of the container to port 8080 of your machine. When you change server.port, change the port in the script too. The folder in the first argument, by default logs in the folder of the repository, is mounted as /app/logs in the container. For trace logs on your machine, set engineTracing.tracingLogDirectory to /app/logs. The container is removed when it ends.
The image has no application.conf of its own. A container started without one runs with the defaults of the table below, and with server.host at 127.0.0.1 it cannot be reached from outside the container. To run the image without the script, mount a configuration file at /app/application.conf:
docker build -t karpfen-runtime .
docker run --rm -p 8080:8080 -v "$PWD/docker.conf:/app/application.conf:ro" karpfen-runtime
3.3.4 Configuration#
The runtime reads application.conf from the folder it starts in. Without the file it uses the defaults. The file has one option per line in the form name = value, grouped in blocks:
server {
host = "127.0.0.1"
port = 8080
}
engine {
defaultTickDelayMs = 50
defaultEventTtlMs = 3000
}
The runtime finds an option by its name inside the block and does not look at the name of the block. A line that starts with # is a comment, and so is text after # when two blanks or a tab stand before it. A value may stand in quotes. A number that cannot be read gives the default. A boolean is true for true in any case and false for anything else.
| Option | Default | In the shipped file | Meaning |
|---|---|---|---|
server.host | 127.0.0.1 | 127.0.0.1 | The address the runtime listens on. 0.0.0.0 listens on all addresses |
server.port | 8080 | 8080 | The port for HTTP and the WebSocket |
websocket.enabled | true | true | With false, the runtime pushes no messages to WebSocket clients |
websocket.queueTimeoutMs | 1000 | 1000 | Read and not used |
logging.level | INFO | INFO | Printed at the start and not used |
logging.consoleOutput | true | false | Read and not used |
engine.defaultTickDelayMs | 1000 | 50 | The tick delay of an environment without setTickDelay, in milliseconds |
engine.defaultEventTtlMs | 1000 | 3000 | The time to live of events in an environment without setEventTtl, in milliseconds. 0 means events never expire |
engine.eventConsumptionOnFire | true | true | With false, an event that fires a transition is not consumed by it, as 3.1.7.3 Consumption describes |
engineTracing.tracingEnabled | false | false | With true, the runtime writes a trace log per environment |
engineTracing.tracingLogDirectory | none | logs | The folder of the trace logs, relative to the folder the runtime starts in or absolute. Without it no trace file is written |
engineTracing.tracingConsoleOutput | false | false | With true and tracing on, the runtime also prints every trace line |
engineTracing.simpleTrace | true | true | Read and not used |
A tick delay of 0 lets an environment tick without any pause and keeps one processor core busy.
3.3.5 Trace log#
With engineTracing.tracingEnabled set to true, the runtime writes one trace log per environment to <tracingLogDirectory>/engine-trace-<envKey>.log. The file is opened when the environment is run and closed when the runtime ends. A stop and a start of the environment go on writing to it.
Every line has the time, the key of the environment, the key of the object of the state machine or * for the whole environment, the type of the entry, a message and details:
[HH:mm:ss.SSS] [<envKey>] [<object>] <TYPE>: <message> | <name>=<value>, <name>=<value>
The beginning of the trace of the lamp:
# Engine Trace Log — Engine: env-1763035112345 — Started: 2026-11-13T09:12:01.120Z
[10:12:01.124] [env-1763035112345] [lamp] STATE_MACHINE_ATTACHED: State machine of the run configuration attached | stateMachine=, path=0
[10:12:01.125] [env-1763035112345] [lamp] INITIAL_STATE: Initial state stack: off | path=0, stack=off
[10:12:01.126] [env-1763035112345] [wallSwitch] STATE_MACHINE_ATTACHED: State machine of the run configuration attached | stateMachine=, path=0
[10:12:01.126] [env-1763035112345] [wallSwitch] INITIAL_STATE: Initial state stack: down | path=0, stack=down
[10:12:01.127] [env-1763035112345] [*] ENGINE_START: Engine started with 2 state machine(s), tickDelay=500ms
[10:12:01.128] [env-1763035112345] [lamp] TICK_START: Tick #1 | path=0, stack=off, currentStates=off, parallel=false
[10:12:01.129] [env-1763035112345] [lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'off' | path=0, state=off, stack=off
[10:12:01.131] [env-1763035112345] [lamp] STATE_DO_SKIP: onDo for state 'off' is empty — skipped | path=0, state=off, stack=off
[10:12:01.131] [env-1763035112345] [lamp] TICK_END: Tick #1 completed | path=0, stack=off, currentStates=off, parallel=false
The types of entries:
| Type | Written when | Message |
|---|---|---|
INITIAL_STATE | A state machine gets its start stack, right after it is attached or exchanged, or a client forces a state | Initial state stack: on > full or Forced state: on > full |
ENGINE_START | The environment starts, or continues after a stop | Engine started with 2 state machine(s), tickDelay=500ms or Engine continued after tick 42 with 2 state machine(s) |
ENGINE_STOP | The environment stops | Engine stopped after 42 ticks |
STATE_MACHINE_ATTACHED | A state machine instance joins on an object without one | State machine 'glowing' attached, or State machine of the run configuration attached for an attached state machine |
STATE_MACHINE_DETACHED | A state machine instance leaves and no other takes its place | State machine 'glowing' detached |
STATE_MACHINE_EXCHANGED | EXCHANGE ended the instance on an object and started another one in its place | State machine 'glowing' exchanged for 'blinking', or State machine of the run configuration exchanged for 'blinking' |
TICK_START | A state machine begins its step | Tick #3 |
TICK_END | A state machine ends its step | Tick #3 completed |
STATE_ENTRY_EXEC | An ENTRY block runs | Executing onEntry for state 'on' |
STATE_ENTRY_SKIP | A state with an empty ENTRY block is entered | onEntry for state 'on' is empty — skipped |
STATE_DO_EXEC | A DO block runs | Executing onDo for state 'on' |
STATE_DO_SKIP | The innermost state has an empty DO block | onDo for state 'on' is empty — skipped |
TRANSITION_START | A transition begins | off -> full |
TRANSITION_FIRED | A transition changed the active states | off -> full |
TRANSITION_SKIPPED_LOOP | A NOT LOOPING transition was skipped | Skipped NOT LOOPING transition |
SPLIT_START, SPLIT_FIRED | A split begins and is done | off -> test bulb,test switch |
JOIN_START, JOIN_FIRED | A join begins and is done | bulb ok,switch ok -> on |
ACTION_ERROR | An action failed | Error in onEntry for state 'off': <error> |
Every entry of a state machine names a path. A path is one stretch of the state machine on an object that a single branch runs from its beginning to its end. The numbers count per object from 0 and are never given twice while the environment lives, so the object and the path number together name one stretch, and grouping the lines by object and path separates everything, also the lines of branches that interleave while the feature TrueParallel is on. The first state machine on an object runs on path 0. Each target of a split starts a new path, a join ends the paths of the split and starts one more, a forced state ends the current paths and starts one more, and a state machine that EXCHANGE or a later attachment brings to the same object starts with the next number. A stop and a start keep the paths.
The details, in the order in which they appear:
| Type | Details |
|---|---|
STATE_MACHINE_ATTACHED | stateMachine (the name, empty for a state machine of the run configuration), path |
STATE_MACHINE_DETACHED | stateMachine, then path, or paths while the state machine is split |
STATE_MACHINE_EXCHANGED | ended (the name of the state machine that ended, empty for one of the run configuration), started, ends (the paths that ended), path (the path of the new state machine) |
INITIAL_STATE | path, stack; after a forced state first ends, the paths the force ended |
TICK_START, TICK_END | path, or paths while the state machine is split; stack (the active states of all branches), currentStates (the innermost state of each branch, in the order of paths), parallel |
| entries of states | path, state, stack (the stack of the branch) |
TRANSITION_START, TRANSITION_FIRED | path, from, to, stack |
TRANSITION_SKIPPED_LOOP | path, stack |
SPLIT_START | path, from, to |
SPLIT_FIRED | path (the path that splits), starts (the new paths, in the order of the targets), from, to |
JOIN_START | paths (the paths about to be joined), from, to |
JOIN_FIRED | ends (the joined paths), path (the new path), from, to |
ACTION_ERROR | path, state, stack |
A detail that lists several paths separates them with commas. The entries of the whole environment, under *, name no path. A line about a state machine as it stands names path, or paths while it is split; a line that changes the paths names those it ends in ends and those it starts in starts or path.
Some lines of a lamp that tests its bulb and its switch in two branches and joins them in on, shortened to object, type, message and details:
[lamp] TRANSITION_FIRED: idle -> off | path=0, from=idle, to=off, stack=off
[lamp] SPLIT_FIRED: off -> test bulb,test switch | path=0, starts=1,2, from=off, to=test bulb,test switch
[lamp] TICK_END: Tick #2 completed | paths=1,2, stack=test bulb,test switch, currentStates=test bulb,test switch, parallel=true
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'test bulb' | path=1, state=test bulb, stack=test bulb
[lamp] TRANSITION_FIRED: test switch -> check position | path=2, from=test switch, to=check position, stack=check position
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'bulb ok' | path=1, state=bulb ok, stack=bulb ok
[lamp] JOIN_FIRED: bulb ok,switch ok -> on | ends=1,2, path=3, from=bulb ok,switch ok, to=on
[lamp] STATE_ENTRY_EXEC: Executing onEntry for state 'on' | path=3, state=on, stack=on
An exchange of the state machine of the bulb, which ran on path 0, for blinking writes one line, followed by the start stack of the new state machine:
[bulb] STATE_MACHINE_EXCHANGED: State machine 'glowing' exchanged for 'blinking' | ended=glowing, started=blinking, ends=0, path=1
[bulb] INITIAL_STATE: Initial state stack: off | path=1, stack=off
Two exchanges of one object in the same tick write one line that names the state machine that ran before the tick and the one named last. EXCHANGE on an object without a state machine writes STATE_MACHINE_ATTACHED. A client that observes the state machines still gets stateMachineDetached and then stateMachineAttached for an exchange (see 3.5.3.6).
3.3.6 Stopping the runtime#
Ctrl+C in the terminal of the runtime, or the end of the Docker container, stops it. The runtime closes the WebSocket connections of all environments with code 1001 and the reason Runtime stopped, ends their engines with their Python processes and trace logs, closes its server and ends. It keeps nothing: all environments, models and recordings are gone.
A single environment ends for good with POST /dropEnvironment of 3.4.2 Environments while the runtime goes on. Its connections close with code 1000 and the reason Environment dropped, and its trace file stays in the trace directory. A runtime that runs for a long time and serves many runs should have its clients drop the environments they no longer need, since a stopped environment keeps its model, its engine and its Python processes in memory until it is dropped.
The runtime prints what it does on its console, also when tracing is off: environments that start and stop, clients that register, payloads it cannot read, failed actions and failed EVAL clauses.