(causeway) 05/08: CAUSEWAY-4068: proposes configurable execution mode key

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch CAUSEWAY-4068
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 501163ceeee84fb29626b0ed5d33df870ccc34a8
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Sep 25 11:06:46 2026 +0100

    CAUSEWAY-4068: proposes configurable execution mode key
---
 .../.openspec.yaml                                 |  2 +
 .../expose-execution-mode-key-property/design.md   | 45 ++++++++++++++++++++++
 .../expose-execution-mode-key-property/proposal.md | 26 +++++++++++++
 .../configurable-execution-mode-attribute/spec.md  | 36 +++++++++++++++++
 .../expose-execution-mode-key-property/tasks.md    | 15 ++++++++
 5 files changed, 124 insertions(+)

diff --git a/openspec/changes/expose-execution-mode-key-property/.openspec.yaml b/openspec/changes/expose-execution-mode-key-property/.openspec.yaml
new file mode 100644
index 00000000000..abd7c5ae1ca
--- /dev/null
+++ b/openspec/changes/expose-execution-mode-key-property/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-25
diff --git a/openspec/changes/expose-execution-mode-key-property/design.md b/openspec/changes/expose-execution-mode-key-property/design.md
new file mode 100644
index 00000000000..f87e91e4901
--- /dev/null
+++ b/openspec/changes/expose-execution-mode-key-property/design.md
@@ -0,0 +1,45 @@
+## Context
+
+Causeway currently writes foreground and background classifications under the constant OpenTelemetry span attribute key `causeway.execution.mode`.
+The servlet filter and command-log Quartz job reach the static classifier through lightweight test seams, while `CausewayConfiguration` is already the public, typed configuration surface available to framework code and consuming applications.
+The change crosses the config, webapp, command-log, tests, and documentation modules but must remain backward compatible on this decommissioning branch.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose `causeway.execution.mode.key` through the typed `CausewayConfiguration` hierarchy.
+- Preserve `causeway.execution.mode` as the default key.
+- Ensure framework foreground and background classification use the same configured key that applications can read.
+- Retain no-agent and non-recording-span behavior.
+
+**Non-Goals:**
+
+- Change the bounded `foreground` and `background` attribute values.
+- Change trace names, parentage, sampling, or exporter behavior.
+- Introduce a new telemetry dependency or configuration subsystem.
+
+## Decisions
+
+### Model the key in `CausewayConfiguration`
+
+Add an `execution.mode.key` hierarchy under the existing `causeway` root, initialized to `causeway.execution.mode`.
+This gives application code a stable typed accessor and lets Spring Boot bind an override through its normal relaxed configuration rules.
+A standalone `@Value` injection was considered, but it would not expose the setting through the framework's established configuration API.
+
+### Pass the configured key to the classifier
+
+Extend the trace-classification helper so callers provide the attribute key when classifying the current span, and update both the foreground web filter and background command job to obtain that key from `CausewayConfiguration`.
+This keeps one classification implementation while ensuring every framework-owned execution-mode classification honors the same setting.
+Leaving the classifier hard-coded while merely publishing a configuration value was rejected because an override would then make framework and application spans inconsistent.
+
+### Preserve lightweight test seams
+
+Keep constructor-level seams around span classification and add the configured key to those seams rather than requiring an OpenTelemetry SDK in unit tests.
+Tests will verify default binding, override binding, and propagation of the selected key from each entry point.
+
+## Risks / Trade-offs
+
+- [Risk] Renaming the attribute through configuration can break existing backend searches and dashboards. → Preserve the old key as the default and document that overrides require corresponding observability-query updates.
+- [Risk] One entry point could continue using the old constant. → Add focused tests for both foreground and background classification paths.
+- [Trade-off] Adding a nested configuration hierarchy introduces API surface for one setting. → Use the existing `CausewayConfiguration` convention so consuming applications do not need a separate configuration bean.
diff --git a/openspec/changes/expose-execution-mode-key-property/proposal.md b/openspec/changes/expose-execution-mode-key-property/proposal.md
new file mode 100644
index 00000000000..7c96390ab9b
--- /dev/null
+++ b/openspec/changes/expose-execution-mode-key-property/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+The execution-mode trace attribute key is hard-coded, so consuming applications cannot reliably reuse the framework's configured key in their own filters or instrumentation.
+Exposing the key as configuration provides one shared source of truth while preserving the existing attribute name by default.
+
+## What Changes
+
+- Add the `causeway.execution.mode.key` configuration property with the default value `causeway.execution.mode`.
+- Make Causeway's foreground and background trace classification use the configured execution-mode attribute key.
+- Allow consuming applications to obtain the same key through `CausewayConfiguration` for custom filters and instrumentation.
+- Cover the default and overridden key behavior with focused tests and update tracing configuration guidance.
+
+## Capabilities
+
+### New Capabilities
+
+- `configurable-execution-mode-attribute`: Defines the shared configurable attribute key used to classify foreground and background execution spans.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change affects `CausewayConfiguration`, execution-mode trace classification in core web and command-log paths, related tests, configuration metadata, and tracing documentation.
+The default preserves the existing `causeway.execution.mode` telemetry contract, so no consuming application configuration change is required.
diff --git a/openspec/changes/expose-execution-mode-key-property/specs/configurable-execution-mode-attribute/spec.md b/openspec/changes/expose-execution-mode-key-property/specs/configurable-execution-mode-attribute/spec.md
new file mode 100644
index 00000000000..1b4657ae3f6
--- /dev/null
+++ b/openspec/changes/expose-execution-mode-key-property/specs/configurable-execution-mode-attribute/spec.md
@@ -0,0 +1,36 @@
+## ADDED Requirements
+
+### Requirement: Execution-mode attribute key is configurable
+The system SHALL expose the execution-mode span attribute key as `causeway.execution.mode.key` through the typed Causeway configuration API.
+The property's default value MUST be `causeway.execution.mode`.
+
+#### Scenario: Application uses the default configuration
+- **WHEN** an application does not configure `causeway.execution.mode.key`
+- **THEN** the typed configuration reports `causeway.execution.mode` as the execution-mode attribute key
+
+#### Scenario: Application overrides the key
+- **WHEN** an application configures `causeway.execution.mode.key` with a non-default value
+- **THEN** the typed configuration reports that configured value for use by framework and application instrumentation
+
+### Requirement: Framework classification uses the configured key
+The system SHALL write foreground and background execution-mode span attributes using the key reported by `causeway.execution.mode.key`.
+The system MUST retain `foreground` and `background` as the corresponding bounded attribute values.
+
+#### Scenario: Foreground request uses an overridden key
+- **WHEN** the foreground web filter classifies an HTTP entry span and the application has overridden `causeway.execution.mode.key`
+- **THEN** the span receives the value `foreground` under the overridden key
+
+#### Scenario: Background command uses an overridden key
+- **WHEN** the command-log Quartz job classifies its entry span and the application has overridden `causeway.execution.mode.key`
+- **THEN** the span receives the value `background` under the overridden key
+
+#### Scenario: Existing application keeps the default key
+- **WHEN** Causeway classifies a foreground or background span without an execution-mode key override
+- **THEN** the span retains the existing `causeway.execution.mode` attribute contract
+
+### Requirement: Consuming applications can share the framework key
+A consuming application SHALL be able to read the configured execution-mode key from `CausewayConfiguration` and use it in custom filters or instrumentation without duplicating the default literal.
+
+#### Scenario: Custom application instrumentation reads the key
+- **WHEN** consuming application code obtains the execution-mode key from the injected typed configuration
+- **THEN** it receives the same key used by Causeway's foreground and background classifiers
diff --git a/openspec/changes/expose-execution-mode-key-property/tasks.md b/openspec/changes/expose-execution-mode-key-property/tasks.md
new file mode 100644
index 00000000000..0cc36030d6f
--- /dev/null
+++ b/openspec/changes/expose-execution-mode-key-property/tasks.md
@@ -0,0 +1,15 @@
+## 1. Typed Configuration
+
+- [ ] 1.1 Add the `CausewayConfiguration.Execution.Mode` hierarchy with `causeway.execution.mode` as the default key.
+- [ ] 1.2 Add configuration binding tests that verify the default and an application-provided `causeway.execution.mode.key` override.
+
+## 2. Trace Classification
+
+- [ ] 2.1 Update `CausewayTraceClassifier` and its unit tests to write execution mode under a caller-provided attribute key while preserving bounded mode values and no-agent behavior.
+- [ ] 2.2 Inject the typed configuration into `CausewayForegroundTraceFilter`, use its execution-mode key, and update filter tests to verify key propagation.
+- [ ] 2.3 Update `RunBackgroundCommandsJob` to classify with the typed configuration key and extend its focused tests to verify key propagation.
+
+## 3. Documentation and Verification
+
+- [ ] 3.1 Document `causeway.execution.mode.key`, its default, application reuse, and the operational effect of overriding it in the tracing guidance.
+- [ ] 3.2 Run the focused config, webapp, command-log, and tracing compatibility tests and resolve any regressions.