Skip to content

EMS logging

Root log directory

All active EMS logs are stored in the repository-root directory:

ES100CX12S/logs/

Inside the standard container this is:

/app/logs/

No active logger writes to EnergySyc_EMS_ES100Cx12S/logs/ or /var/log/ems.

Always-on process error logs

start_ems_client_in_docker.sh creates one normal output log and one error log for every managed process. Error files are created regardless of device.debug_enabled.

Process Normal output Always-on stderr/error file
EMS HTTP API ems_http_api.log ems_http_api_error.log
Settings poller ems_settings_poll.log ems_settings_poll_error.log
Last-value sync sync_lastvalues.log sync_lastvalues_error.log
Folder cleaner folder_cleaner.log folder_cleaner_error.log
PCS client pcs_client.log pcs_client_error.log
Grid-meter client grid_meter_client.log grid_meter_client_error.log
Solar-meter client solar_meter_client.log solar_meter_client_error.log
EMS main loop ems_main.log ems_main_error.log

ems_main.py also creates error files for internally managed controllers:

frequency_regulation_error.log
external_control_bridge_error.log

The optional standalone frequency-meter process uses:

frequency_meter_client_error.log

Python tracebacks and all stderr go to the process error file. The launcher also copies stdout lines containing error indicators such as [ERROR], [FATAL], [CRITICAL], [!], exception, failed, or failure into the error file. All stdout remains available in the normal process log. Check both files when diagnosing full execution context.

Always-on Modbus error logs

Structured failed/error Modbus events bypass the debug flag and are always written to:

pcs_modbus_error.log
grid_meter_modbus_error.log
solar_meter_modbus_error.log
frequency_regulation_modbus_error.log
frequency_meter_modbus_error.log

These JSON Lines records include device identity, endpoint, unit ID, operation, register, values when available, status, and error text.

Example:

{"time":"2026-09-15T10:15:30.120+00:00","direction":"receive","device_type":"grid_meter","device_id":"grid_meter1","ip":"192.168.1.20","port":502,"unit_id":1,"part":"polling","operation":"read_holding_registers","status":"error","register":1000,"register_hex":"0x03E8","count":2,"error":"timed out"}

Debug transaction logs

Successful and failed transaction traces are written to the debug send/receive files only when this setting is true:

{
  "device": {
    "debug_enabled": true
  }
}

The files are still created at process startup when debugging is false; they remain empty except that failures are copied to the separate always-on Modbus error files.

Debug transaction files include:

debug_modbus_command_send.log
debug_modbus_command_receive.log
debug_grid_meter_modbus_command_send.log
debug_grid_meter_modbus_command_receive.log
debug_solar_meter_modbus_command_send.log
debug_solar_meter_modbus_command_receive.log
debug_frequency_regulation_modbus_command_send.log
debug_frequency_regulation_modbus_command_receive.log
debug_frequency_meter_modbus_command_send.log
debug_frequency_meter_modbus_command_receive.log

Viewing errors

Follow all process error files:

tail -F ../logs/*_error.log

Show only nonempty error files:

find ../logs -maxdepth 1 -name '*_error.log' -type f -size +0 -print

Read structured Modbus errors:

jq -c . ../logs/pcs_modbus_error.log
jq -c . ../logs/frequency_regulation_modbus_error.log

Inside Docker:

docker exec -it ems-backend tail -F /app/logs/ems_main_error.log
docker exec -it ems-backend tail -F /app/logs/pcs_modbus_error.log

Rotation

Structured Modbus transaction and error files use rotating handlers. The default maximum size is 20 MiB with five backups. Configure retention with:

export DEBUG_MODBUS_COMMAND_LOG_MAX_BYTES=20971520
export DEBUG_MODBUS_COMMAND_LOG_BACKUP_COUNT=5

Process error files are pre-created whenever the startup script runs. They are truncated when their process is launched and then receive stderr plus classified error-like stdout lines.