[emaarco]

Why

Applications need a trace span (Micrometer, OpenTelemetry, Elastic APM, ...) per execution of an external service task, so that the logs of the handler, of the process-engine-worker and of the adapter delivery's failure handling carry the trace id and MDC, plus an optional place to do something before and after an execution (logging, metrics). This must not interfere with the execution or completion of the task. Today, consumers copy whole adapter deliveries to achieve this.

The PR evolved in four commits, kept for comparison and to be squashed on merge:

1. Around-style interceptors (chain.proceed()) around the handler: could veto, repeat or swallow the execution.
2. Observers with before/after around the subscription action: the delivery's failure handling ran outside their scope, so its logs lost the trace context.
3. Observers invoked by the deliveries with an outcome report: covered the failure handling but needed an outcome model, a thread-local recorder, a decorated completion API and a report type.
4. A task execution decorator around the delivery's whole per-task work. The trace use case needs the scope, not an outcome, so all outcome machinery is gone.

This is Phase 1 only: the Spring-free core. Phase 2 updates the CIB seven adapter, which currently serves as the spike.

What

• Add TaskExecutionDecorator to api, a fun interface in the spirit of Spring's TaskDecorator: decorate(task, payload, execution): Runnable. execution is the delivery's whole per-task work, i.e. the handler call and the delivery's own failure handling and logging, so a span or MDC entry opened around execution.run() covers all of it. Decorators receive read-only views of the task information and payload and are not told the outcome.
• Add the final class TaskExecutionDecoration to api-impl. An adapter builds one instance from the decorators in execution order (e.g. in its starter from the ordered beans), passes it to its deliveries (default TaskExecutionDecoration.NONE) and calls run(task, payload, execution) in every external task delivery. It nests the decorators with the first one outermost and runs the execution exactly once: a decorator that fails in decorate, throws before running the execution, skips it or runs it twice is only logged (PROCESS-ENGINE-API-016/-017/-018), and the execution still runs once. Exceptions of the execution pass through unchanged; errors are not caught. Without decorators it just runs the execution.
• Subscriptions, AbstractTaskSubscriptionApiImpl and the completion APIs stay unchanged.
• Document decorators, their rules and how an adapter supports them in docs/task-subscription-api.md, with a tracing/MDC example in Kotlin and a logging example in Java.

Verification

• ./mvnw clean verify passes.
• New unit tests cover running without decorators, nesting order, read-only task and payload, skipped and repeated executions, a failing decorate, a decorator throwing before and after the execution, and exceptions and errors of the execution passing through unchanged.
• Not verified by running against real adapters.

Out of scope / Follow-ups

• Phase 2, one PR per adapter repository after an api release, starting with CIB seven: build a TaskExecutionDecoration from the ordered TaskExecutionDecorator beans and call its run around the per-task work of every external task delivery, and put the activity instance id into TaskInformation.meta under CommonRestrictions.ACTIVITY_INSTANCE_ID from feat(api): add activity instance id to common restrictions #324.
• An optional failed(...) callback, to mark a span as failed, can be added later as a default method without breaking existing decorators. It depends on Failure handling of task executions is owned by both the worker and the adapter deliveries process-engine-worker#284, because the worker reports failures itself.
• A default decorator based on a Micrometer Observation in the adapter starters.
• Decorators for user tasks.

Refs #278

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.87%. Comparing base (49fdf66) to head (92e5309).

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #313      +/-   ##
=============================================
+ Coverage      50.65%   53.87%   +3.22%     
- Complexity        80       96      +16     
=============================================
  Files             40       42       +2     
  Lines            458      490      +32     
  Branches           9       11       +2     
=============================================
+ Hits             232      264      +32     
  Misses           221      221              
  Partials           5        5              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.