WinCC Unified HMIRuntime.Trace Severity Levels V19+ Configuration

WinCC Unified HMIRuntime.Trace Severity Configuration (TIA V19 Update 2 and Later)

The WinCC Unified scripting API exposes HMIRuntime.Trace(message, traceSeverity) as the primary diagnostic channel for runtime scripts executing on Unified Panels, Unified Comfort Panels, and WinCC Unified PC Runtime. Prior to TIA Portal V19 Update 2, the call accepted only a string argument. Starting with V19 Update 2, a second traceSeverity parameter is supported, allowing engineers to tag each trace entry with a numeric severity that drives filtering, color coding in the RTIL Trace Viewer, and selective persistence to the on-device log files.

This reference documents the full severity model, the LOG-file retention rules, the JavaScript / VB call signatures, the JobScheduler Verbose flag that gates Verbose-level entries, and a field-tested troubleshooting matrix for the most common display issues encountered when commissioning trace logging on MTP, TP, and Unified PC targets.

Severity Levels and Numeric Mapping

Five discrete severity values are defined for the runtime trace pipeline. The numeric ordinals are stable across all V19+ Unified runtime versions and are accepted by both the JavaScript and VBScript bindings of the HMIRuntime object.

HMIRuntime.Trace Signature and Backward Compatibility

The extended signature is:

// JavaScript (RT Unified)
HMIRuntime.Trace(string message [, number traceSeverity]);

// VBScript (legacy, V17/V18 compatibility shim)
HMIRuntime.Trace string[, long]

If traceSeverity is omitted, the runtime assumes Info (0). This implicit fallback is what preserves source compatibility with every project authored against V17, V18, and the initial V19 release — no recompilation or migration step is required for existing scripts to continue working unchanged.

// Pre-V19 syntax — still valid in V19 Update 2+
HMIRuntime.Trace("Hello World");

// V19 Update 2+ extended syntax
HMIRuntime.Trace("Hello World", 0);   // Info
HMIRuntime.Trace("Tag value drift", 2); // Warning
HMIRuntime.Trace("Connection lost", 3); // Error
HMIRuntime.Trace("PLC heartbeat lost", 4); // Fatal

RTIL Trace Viewer and the TraceCatalog

The RTIL Trace Viewer is the primary inspection tool for live trace output during commissioning and runtime diagnostics. It reads the in-memory trace buffer that every script call writes to and renders entries grouped by severity, source module, and timestamp. The viewer is documented at RTIL Trace Viewer (RT Unified).

Two configuration surfaces govern which entries actually surface in the viewer:

1. TraceCatalog — a runtime-side XML/INI catalog that declares which sources (script modules, scheduler tasks, internal subsystems) are eligible to emit trace entries. Entries originating from non-cataloged sources are silently dropped.
2. Per-source Verbose flag — a runtime flag on each cataloged source that must be enabled before Verbose (1) entries from that source are admitted to the viewer buffer.

For WinCC Unified PC Runtime, the TraceCatalog lives under the runtime installation directory and is read once at startup; for Unified Panels it is part of the project image loaded at boot. Modifying the catalog requires a runtime restart.

JavaScript Usage Pattern (Recommended for V19+ Projects)

// Standard severity-graded trace idiom
function LogProductionState(lineId, state) {
  let severity = 0;
  if (state === "FAULT")      severity = 3;
  else if (state === "STARVE") severity = 2;
  else if (state === "OK")     severity = 0;

  HMIRuntime.Trace("Line " + lineId + " state=" + state, severity);
}

// Triggered from a button "OnClick" event
export function Button_TraceDiagnostic_OnClick(item) {
  HMIRuntime.Trace("Diagnostic button pressed by " + HMIRuntime.User, 0);
  let tags = Tags("RecipeNumber");
  HMIRuntime.Trace("RecipeNumber=" + tags.Read().value, 0);
}

// Triggered by a scheduled job (every 250 ms)
export function Scheduler_TraceTags_OnTrigger(item) {
  let t = Tags("ConveyorSpeed;TankLevel").Read();
  HMIRuntime.Trace("ConveyorSpeed=" + t[0] + " TankLevel=" + t[1], 1); // Verbose
}

JobScheduler Verbose Flag — Mandatory for Verbose-Level Display

Entries emitted with severity Verbose (1) are the only severity class that requires an additional runtime flag to be observable. Without this flag the viewer buffer suppresses them even though the script executed HMIRuntime.Trace() successfully. This is the single most common commissioning issue reported on V19 Update 2 projects.

Enabling the Verbose Flag

1. Open the device configuration of the Unified HMI in TIA Portal.
2. Navigate to Runtime settings → Services → JobScheduler (path varies slightly between Panel and PC Runtime; on PC Runtime, locate the JobScheduler under WinCC Unified Runtime → Scheduler).
3. Set the Verbose property of the JobScheduler task that owns the tracing script to true. For project-wide tracing, enable Verbose on every JobScheduler entry that may emit trace calls.
4. Recompile and download the project to the target.
5. Trigger the tag or button that fires the trace script.
6. Open the RTIL Trace Viewer; Verbose entries from the flagged scheduler should now be visible.

LOG File Persistence — Where to Find Trace Logs

For runtime troubleshooting, the LOG files contain the durable record of all Warning, Error, and Fatal traces. Their location depends on the runtime target:

The canonical reference for log file contents, retention behavior, and supported severity filtering is Trace logs for function calls and tag values (RT Unified).

Step-by-Step: Commissioning a Severity-Graded Trace

Prerequisites

• TIA Portal V19 Update 2 or later installed.
• WinCC Unified device of firmware version compatible with the TIA version (MTP1200, TP1500, TP2200, Unified Comfort, or Unified PC).
• RTIL Trace Viewer accessible from the engineering station or from the Panel's service page.

Procedure

1. Author the script. Add a JavaScript or VBScript function that calls HMIRuntime.Trace(message, severity) with an explicit severity ordinal.
2. Wire the trigger. Bind the script to a button OnClick, a tag trigger, or a JobScheduler entry as appropriate.
3. Configure the JobScheduler. If the script will emit Verbose entries, enable the JobScheduler Verbose flag on the owning task.
4. Compile and download. Build the HMI project and transfer the complete image to the target.
5. Open the RTIL Trace Viewer. Connect to the runtime, then trigger the script and verify entries appear with the expected severity icon/color.
6. Export LOG evidence. For Warning/Error/Fatal entries, retrieve the .log file from the target and confirm the trace text was persisted with the correct severity prefix.

Verification

• RTIL Trace Viewer shows entries grouped by severity with correct ordinal.
• LOG file contains Warning, Error, and Fatal entries verbatim.
• Verbose entries appear only after the JobScheduler Verbose flag is set; reverting the flag suppresses them on the next cycle.
• Existing pre-V19 scripts that omit the severity argument continue to log at Info with no behavior change.

Troubleshooting Matrix

Backward Compatibility and Migration Notes

Projects authored against TIA V17, V18, and the initial V19 release do not require modification when opened in V19 Update 2 or later. The single-argument overload HMIRuntime.Trace(message) remains a supported call shape, internally coerced to severity 0. Existing trace entries therefore continue to surface in the RTIL Trace Viewer at Info severity and are excluded from the LOG file by default, matching the pre-V19 Update 2 behavior exactly.

When migrating a project to take advantage of severity grading, the recommended pattern is to introduce a wrapper function (for example, TraceAt(msg, sev)) at project scope and route every call site through it. This isolates the severity ordinal mapping in one location and prevents drift between developer-defined "warnings" and the runtime's numeric severity model.

Performance and Logging Considerations

• Verbose flooding. A scheduler running at 100 ms with a Verbose trace per tick produces ~10 entries per second. While the in-memory ring buffer absorbs this comfortably, the LOG file persistence path is short-circuited by design, so disk I/O is unaffected.
• String concatenation cost. All argument expressions are evaluated before the trace call, regardless of whether the entry is ultimately persisted. For hot loops, gate the trace call behind an if so the string assembly only happens when the entry will be admitted.
• Catalog scope. Adding unnecessary modules to the TraceCatalog inflates the in-memory buffer and slows RTIL Trace Viewer rendering. Limit catalog entries to sources that actively emit traces during normal operation.
• Localization. Trace messages are written verbatim; multi-language deployments should localize the message string at the call site, not rely on runtime translation of the persisted LOG entry.

Field-Proven Caveats

• On MTP1200 panels running firmware V19.0.0.2, the default behavior of the JobScheduler Verbose flag is disabled. Symptom is identical to a misconfigured catalog: trace calls succeed silently. Always verify the flag is set before declaring "trace is broken."
• The two-argument HMIRuntime.Trace overload is a runtime API, not a TIA compile-time construct. Passing a non-integer (for example, a string "2") is silently coerced to 0 on some runtime versions and rejected on others. Use integer literals or parseInt() at the call site.
• Severity grading applies only to HMIRuntime.Trace. It does not propagate to HMIRuntime.Alarm, Tags().Read trace entries, or PLC-side diagnostic buffers. Those subsystems retain their own severity models.
• For Unified Comfort Panels and MTP panels, the RTIL Trace Viewer is reachable through the Panel's service page (https://<panel-ip>/…) only when engineering access is enabled. On locked-down production panels, set up a logging export workflow in advance.