Design Observable Workflows v2

Design logs and contracts so operators can identify what ran, where it failed, what was processed, and which parent or child execution contains the relevant detail.

Use meaningful names and boundaries

Give each Workflow and Step a name that describes its business role. Step names appear in Expressions, diagnostics, log rows, and inferred schemas.

Use a Sub-Workflow for an independently meaningful operation with a clear Parameter and Return contract. Parent and child activity remains traceable as nested execution rather than becoming one indistinguishable sequence.

Return useful outcomes

Define Workflow Returns that confirm the outcome a caller needs, such as a stable record ID, accepted count, status, or structured error result. Do not return every intermediate value.

For HTTP and MCP Workflows, put the external response on the required root response Step. Ordinary Workflow Returns are not a substitute for those interface contracts.

Preserve useful log evidence

  • Keep Step names stable enough for searches and operational comparisons.
  • Inspect input and Return previews, duration, status, counters, and errors.
  • Use small structured error details for expected business failures.
  • Allow unexpected exceptions to propagate so the Workflow is visibly failed.
  • Follow parent and child rows when diagnosing a Sub-Workflow.

Use TryCatch only where the Workflow has a deliberate recovery or compensation path. Catching every error and returning success removes the failure signal operators need.

Protect sensitive content

Set Logging.Redact: true on sensitive Workflow Properties. Redaction preserves lifecycle evidence for deferred values while removing the selected value or nested content from Workflow logs.

Redaction does not sanitize Debug results, exception messages, custom Node log text, diagnostics, or data sent outside Flowgear. Avoid putting secrets in YAML, Samples, names, or free-text errors. Store credentials in Connections.

Validate observability

  1. Debug a successful small input.
  2. Confirm the final Return and external side effect.
  3. Debug a controlled failure.
  4. Confirm the failing Step, error, and parent/child navigation.
  5. Check that redacted Properties display (Not Logged) and reveal no sensitive nested content.
  6. Confirm that the released invocation is visible under the expected Environment and Workflow.

See also

See Workflow Log Redaction, Error Handling, and Workflow State.