PR #28593: fix(core): Trace sub-workflow executions within their parent workflow trace

• Repository: n8n-io/n8n
• Author: BCSHroyer
• State: open | merged: False
• Link: https://github.com/n8n-io/n8n/pull/28593

Description (problem / solution / changelog)

Summary

Sub-workflow executions (workflows invoked via the Execute Workflow node) were not being traced by the OpenTelemetry module. The parent workflow's trace showed only the parent's spans, and the sub-workflow's workflow.execute / node.execute spans never appeared. This affected any backend module that relies on @OnLifecycleEvent to observe the lifecycle of a sub-execution; OpenTelemetry was the most visible symptom.

Root cause. getLifecycleHooksForSubExecutions was the only lifecycle-hooks factory that did not call Container.get(ModulesHooksRegistry).addHooks(hooks). The other three factories (Main, ScalingMain, ScalingWorker) all register module hooks, so sub-executions silently bypassed every module-registered @OnLifecycleEvent handler.

Secondary gap. WorkflowExecuteBeforeContext did not carry parentExecution, so even with module hooks registered, the OTEL handler had no way to link the sub-workflow's workflow.execute span to its parent's trace.

Changes

Commit 1 — fix(core): Register module lifecycle hooks for sub-workflow executions

• Add Container.get(ModulesHooksRegistry).addHooks(hooks) to getLifecycleHooksForSubExecutions, matching the other three factories.
• Plumb parentExecution through ExecutionLifecycleHooks (new optional constructor parameter) and through WorkflowExecuteBeforeContext so modules can observe the parent of a sub-execution.
• Unit test: a module-registered workflowExecuteBefore handler now fires for sub-executions and sees parentExecution in the context.

Commit 2 — fix(core): Link sub-workflow traces to parent workflow execution span

• WorkflowStartHandler uses ctx.parentExecution (when present) to look up the parent's workflow.execute span in SpanRegistry and start the child workflow.execute span with the parent as its OTEL context. Falls back to a root span when no parent is supplied or the parent span is not in the registry.
• Unit tests for WorkflowStartHandler covering attributes, root-span fallback, child-of-parent linking, and missing-parent fallback.

Resulting trace

Before: two disconnected root traces — one for the parent, one for the sub-workflow.

After: one trace with the sub-workflow's workflow.execute span nested under the parent's workflow.execute span, sharing a single traceId:

workflow.execute  (Parent)
├── node.execute  Trigger
├── node.execute  Set
├── node.execute  Execute Workflow
└── workflow.execute  (Child)
    ├── node.execute  Set
    └── node.execute  Code

Known limitation

In scaling mode where parent and child executions run on different worker processes, the parent's workflow.execute span isn't present in the child process's SpanRegistry. In that case the child is still emitted as a root span — no worse than today, but a follow-up could propagate OTEL trace context through the execution queue if cross-process linking is desired. Happy to file a separate issue for that if reviewers agree.

How to test

1. Set N8N_OTEL_ENABLED=true and N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector>:4318 on an n8n instance.
2. Create two workflows: a "Child" with any pair of nodes, and a "Parent" that ends with an Execute Workflow node calling Child.
3. Execute Parent and inspect the trace in your OTLP backend. The Child's workflow.execute span should share the Parent's traceId and its parentSpanId should match the Parent's workflow.execute span id.

Related Linear tickets, Github issues, and Community forum posts

Fixes #28592

https://linear.app/n8n/issue/GHC-7752

Review / Merge checklist

• I have seen this code, I have run this code, and I take responsibility for this code.
• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

Changed files

• packages/@n8n/decorators/src/execution-lifecycle/lifecycle-metadata.ts (modified, +7/-0)
• packages/cli/src/execution-lifecycle/__tests__/execution-lifecycle-hooks.test.ts (modified, +53/-0)
• packages/cli/src/execution-lifecycle/execution-lifecycle-hooks.ts (modified, +9/-1)
• packages/cli/src/modules/otel/__tests__/workflow-start.handler.test.ts (added, +148/-0)
• packages/cli/src/modules/otel/handlers/workflow-start.handler.ts (modified, +21/-8)
• packages/core/src/execution-engine/execution-lifecycle-hooks.ts (modified, +2/-0)