Observability hooks (tracing, logging, metrics)

[camcima]

Summary

There is currently no event emitter or hook system for lifecycle events like "workflow transitioned", "command started", "command failed", etc. For production use, teams need to wire these into OpenTelemetry traces, structured logging, or metrics.

Proposal

Add an observer/hook pattern at the runtime level with events such as:

• workflow.created
• workflow.transitioned (with from/to state, event name)
• command.started
• command.succeeded
• command.failed
• workflow.completed
• workflow.errored

The hook system should be lightweight and non-intrusive — observers should not affect workflow execution.

Benefits

• Enables OpenTelemetry integration for distributed tracing
• Structured logging of workflow lifecycle without polluting command handlers
• Metrics collection (transition counts, command durations, error rates)
• Essential for production readiness

Considerations

• Sync vs async observers (async observers shouldn't block transitions)
• Whether observers receive a read-only view of context/metadata
• Integration patterns with popular observability stacks

[camcima]

Quick scoping pass on this — about half of it is already in place, half is the actual ask.

What already exists

A WorkflowObserver interface and ObserverRegistry are wired through the runtime today:

• WorkflowObserver (packages/duraflows-core/src/types/observer.ts) currently has one method, onEnter(event).
• ObserverRegistry (packages/duraflows-core/src/runtime/observer-registry.ts) does async fan-out with per-observer try/catch and a configurable onError, so observers can't break execution — the "non-intrusive" guarantee from this issue.
• Fired from 4 sites in workflow-runtime.ts covering state entry on create/transition/timeout/onEnter chains.
• Exposed on both @duraflows/core and @duraflows/nestjs public APIs (with observers + onObserverError module options on the Nest side).
• Unit + integration tests already exist.

So workflow.transitioned from the proposal is effectively what onEnter does — StateEnterEvent already carries fromState, toState, triggerEvent, transitionUuid, triggerMetadata, occurredAt. Payloads are Readonly<...>, so the "read-only view" consideration is handled.

What's still missing

1. Command lifecycle events — command.started / succeeded / failed. New fire sites inside command-executor.ts plus timing capture for durations (OTel needs this).
2. Workflow lifecycle events — workflow.created, workflow.completed, workflow.errored. One fire site for creation; completed/errored need terminal-state detection.
3. Interface expansion — additional optional methods (or a single on(event, payload) dispatcher). Additive, so no breaking change to today's onEnter consumers.
4. Tests + docs — per-event tests plus a README recipe for OTel/pino wiring.

Design calls worth making up front

• Method-per-event vs. single on(event, payload) callback. Current shape is method-per-event; a single callback is leaner for OTel exporters. Either works.
• Definition of workflow.errored — unhandled exception during transition? any command.failed? both? Only real definitional ambiguity in the proposal.
• De-duplication — if a command failure triggers an error transition, decide whether both command.failed and workflow.errored fire, and how the latter references the former (cause: { kind: 'command-failure', commandUuid }).

Effort

Roughly 1–2 days of focused work. The hard infrastructure (registry, error isolation, async fan-out, plumbing through core + nestjs, test scaffolding) is already done. What remains is mostly mechanical: new payload types, new fire sites, parallel test cases, and the API-shape decision above.

Main risk: terminal-state detection for completed/errored may need a small refactor depending on how cleanly terminal states are modeled in the definition layer. Worth a quick spike before committing to a number.