You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/10/09 12:58:17 UTC
(causeway) 02/10: CAUSEWAY-4068: archive observation classification and correlation
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-4068-v4
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 3b52d532fe75311cc9982a1a733a102447981d01
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Oct 7 11:11:17 2026 +0100
CAUSEWAY-4068: archive observation classification and correlation
---
.../.openspec.yaml | 0
.../design.md | 0
.../proposal.md | 0
.../specs/interaction-trace-correlation/spec.md | 0
.../observation-execution-classification/spec.md | 0
.../specs/observation-policy/spec.md | 0
.../tasks.md | 0
.../validation.md | 0
.../planned-changes/otel-forward-port-roadmap.md | 8 +--
.../specs/interaction-trace-correlation/spec.md | 6 ++-
.../observation-execution-classification/spec.md | 6 ++-
openspec/specs/observation-policy/spec.md | 59 +++++++++-------------
12 files changed, 40 insertions(+), 39 deletions(-)
diff --git a/openspec/changes/classify-and-correlate-observations/.openspec.yaml b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/.openspec.yaml
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/.openspec.yaml
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/.openspec.yaml
diff --git a/openspec/changes/classify-and-correlate-observations/design.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/design.md
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/design.md
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/design.md
diff --git a/openspec/changes/classify-and-correlate-observations/proposal.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/proposal.md
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/proposal.md
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/proposal.md
diff --git a/openspec/changes/classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md
similarity index 100%
copy from openspec/changes/classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md
copy to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md
diff --git a/openspec/changes/classify-and-correlate-observations/specs/observation-execution-classification/spec.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/observation-execution-classification/spec.md
similarity index 100%
copy from openspec/changes/classify-and-correlate-observations/specs/observation-execution-classification/spec.md
copy to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/observation-execution-classification/spec.md
diff --git a/openspec/changes/classify-and-correlate-observations/specs/observation-policy/spec.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/observation-policy/spec.md
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/specs/observation-policy/spec.md
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/specs/observation-policy/spec.md
diff --git a/openspec/changes/classify-and-correlate-observations/tasks.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/tasks.md
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/tasks.md
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/tasks.md
diff --git a/openspec/changes/classify-and-correlate-observations/validation.md b/openspec/changes/archive/2026-10-07-classify-and-correlate-observations/validation.md
similarity index 100%
rename from openspec/changes/classify-and-correlate-observations/validation.md
rename to openspec/changes/archive/2026-10-07-classify-and-correlate-observations/validation.md
diff --git a/openspec/planned-changes/otel-forward-port-roadmap.md b/openspec/planned-changes/otel-forward-port-roadmap.md
index f1095c252d9..7660f8128e9 100644
--- a/openspec/planned-changes/otel-forward-port-roadmap.md
+++ b/openspec/planned-changes/otel-forward-port-roadmap.md
@@ -12,7 +12,7 @@ Main already contains CAUSEWAY-3975, including instrumentation absent from the s
|---|---|---|---|
| 1 | 3975: foundation reconciliation | **Archived:** [completed change](../changes/archive/2026-09-27-reconcile-main-observation-foundation/proposal.md). Lifecycle cleanup, activation/registry selection, Boot/agent compatibility evidence, threshold behavior, preservation of main instrumentation. | `9b8b66d5b7b`, `e6752f882b5`; compare main's original 3975 implementation |
| 1b | CAUSEWAY-4096: standardize observation names, metadata and duration-filtering policy | **Archived (2026-10-05):** [standardize observation policy](../changes/archive/2026-10-05-standardize-observation-policy/proposal.md) on branch `CAUSEWAY-4096`. Follow-up to 3975: stable operation names vs contextual names; review bookmark/query-description names, identity attributes, hard-coded duration threshold and missing exported parents. Set policy before adding new semantic names. | Main [...]
-| 2 | CAUSEWAY-4068 (3975/4068 provenance): classification and correlation | **Implemented; awaiting archive:** [classify and correlate observations](../changes/classify-and-correlate-observations/proposal.md). Foreground/background classification, root interaction ID, fixed execution-mode attribute key. Depends on foundation; adapt to main's interaction layers. | `024bd33128d`, `0325232a3c7`, `3083a51eabd` |
+| 2 | CAUSEWAY-4068 (3975/4068 provenance): classification and correlation | **Archived (2026-10-07):** [classify and correlate observations](../changes/archive/2026-10-07-classify-and-correlate-observations/proposal.md). Foreground/background classification, root interaction ID, fixed execution-mode attribute key. Depends on foundation; adapt to main's interaction layers. | `024bd33128d`, `0325232a3c7`, `3083a51eabd` |
| 3 | 4058: current action context | Planned. Exact-current-action queries and rule-checking state; nested restoration and physical mixin receiver semantics. Can proceed independently of most telemetry work. | `6d037db6609`; account for `f66b8f17a89` |
| 4 | 4062: semantic member names | Planned. Bounded operation categories with domain-facing contextual names; mixed-in property/collection access distinguished from actions. Depends on foundation and naming policy. | `a2ae5877c99`, `d5ecd49a1f3`, `45e01ff6f42` |
| 5 | 4059 + relevant 4062: Wicket regions/preparation | Planned. Entity-page preparation, region rendering and action prompts; Ajax ancestry, serialization and failure cleanup. The 4062 source touches Wicket as well as core: extract the relevant portions here rather than blindly applying step 4 commits. | `a8264fd1f9b`, relevant parts of `a2ae5877c99` / `45e01ff6f42` |
@@ -99,16 +99,18 @@ Implementation checkpoint: planning committed as `5390171e070`; all 11 implement
## Classification and correlation proposal (2026-10-06)
-Step 2 is captured in [classify-and-correlate-observations](../changes/classify-and-correlate-observations/proposal.md), based on local `6f10ac34cac` after CAUSEWAY-4096. CAUSEWAY-3975/4068 identify maintenance provenance. The user selected `CAUSEWAY-4068-v4` for the main-side implementation under CAUSEWAY-4068.
+Step 2 is captured in [classify-and-correlate-observations](../changes/archive/2026-10-07-classify-and-correlate-observations/proposal.md), based on local `6f10ac34cac` after CAUSEWAY-4096. CAUSEWAY-3975/4068 identify maintenance provenance. The user selected `CAUSEWAY-4068-v4` for the main-side implementation under CAUSEWAY-4068.
The design adapts current-span classification to main's shared Micrometer tracer for both Boot and agent ownership, uses the fixed `causeway.execution.mode` attribute, and correlates only the existing root interaction observation. It explicitly handles main's replay-time replacement of command identity, avoids introducing job spans when instrumentation supplies none, and keeps semantic naming and rendering detail for later steps.
Before creating the proposal, completed `port-domain-object-locking` was validated and [archived](../changes/archive/2026-10-06-port-domain-object-locking/proposal.md), with its requirements synced. The focused reactor verification passed, including all eight pessimistic-locking regressions. The archive checkpoint was committed as `e65505dbe0c` after session permissions allowed Git writes; the new planning artifacts follow in a separate proposal commit.
-Implementation checkpoint (2026-10-06): all 12 tasks completed on `CAUSEWAY-4068-v4`. [Validation evidence](../changes/classify-and-correlate-observations/validation.md) records 31 focused tests, 9 tracing/JPA compatibility tests, Petclinic packaging, generated configuration metadata and documentation checks. The M3 how-to and observability guide now cover foreground/background entry attributes, root interaction UUIDs, separate Jaeger searches and the background fixture. Agent setup shar [...]
+Implementation checkpoint (2026-10-06): all 12 tasks completed on `CAUSEWAY-4068-v4`. [Validation evidence](../changes/archive/2026-10-07-classify-and-correlate-observations/validation.md) records 31 focused tests, 9 tracing/JPA compatibility tests, Petclinic packaging, generated configuration metadata and documentation checks. The M3 how-to and observability guide now cover foreground/background entry attributes, root interaction UUIDs, separate Jaeger searches and the background fixtur [...]
Review follow-up: removed the execution-mode key override at the user’s request. Both entry points always use `causeway.execution.mode`; configuration, tests and operator guidance have been simplified accordingly.
Review follow-up (2026-10-07): username and tenancy are now automatic nonempty interaction attributes alongside the root UUID and fixed entry execution mode. Removed identity opt-in properties and launcher scenarios; duration-filtering policy remains available.
Filtering simplification: `causeway.observation.jpa-duration-threshold` is the only filtering setting, with `0ms` disabling filtering. The launcher no longer takes `--scenario`; set `CAUSEWAY_OBSERVATION_JPA_DURATION_THRESHOLD` for Boot-managed runs.
+
+Classification/correlation archived on 2026-10-07 after fresh focused and tracing validation passed (45 tests), with all delta specs synced. General duration filtering is tracked in [the exploration backlog](general-span-duration-filtering.md); the narrow JPA-only threshold is being removed in a separate change.
diff --git a/openspec/changes/classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md b/openspec/specs/interaction-trace-correlation/spec.md
similarity index 94%
rename from openspec/changes/classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md
rename to openspec/specs/interaction-trace-correlation/spec.md
index 5e692039fb8..531b4bd49af 100644
--- a/openspec/changes/classify-and-correlate-observations/specs/interaction-trace-correlation/spec.md
+++ b/openspec/specs/interaction-trace-correlation/spec.md
@@ -1,5 +1,8 @@
-## ADDED Requirements
+# interaction-trace-correlation Specification
+## Purpose
+TBD - created by archiving change classify-and-correlate-observations. Update Purpose after archive.
+## Requirements
### Requirement: Root interaction UUID correlation
When observation is active, the existing root interaction span SHALL contain high-cardinality string attribute `causeway.interaction.id`, equal to the canonical UUID returned by its own interaction's `getInteractionId()` at completion. The attribute SHALL be independent of username and tenancy attributes and SHALL NOT become a metric label.
@@ -39,3 +42,4 @@ The observability guide SHALL show execution-mode attributes on the applicable e
#### Scenario: Verify default and custom classification
- **WHEN** an operator follows the foreground and background examples with the default or an overridden key
- **THEN** the guide identifies the span to inspect, the exact expected attribute and the requirement for an existing instrumented job span, without implying that every child carries the attribute
+
diff --git a/openspec/changes/classify-and-correlate-observations/specs/observation-execution-classification/spec.md b/openspec/specs/observation-execution-classification/spec.md
similarity index 94%
rename from openspec/changes/classify-and-correlate-observations/specs/observation-execution-classification/spec.md
rename to openspec/specs/observation-execution-classification/spec.md
index 15ba98b5396..2f4e611eddc 100644
--- a/openspec/changes/classify-and-correlate-observations/specs/observation-execution-classification/spec.md
+++ b/openspec/specs/observation-execution-classification/spec.md
@@ -1,5 +1,8 @@
-## ADDED Requirements
+# observation-execution-classification Specification
+## Purpose
+TBD - created by archiving change classify-and-correlate-observations. Update Purpose after archive.
+## Requirements
### Requirement: Foreground HTTP entry classification
With the observation profile active and a supported tracing bridge, Causeway SHALL annotate the existing HTTP entry span with execution mode `foreground`. It SHALL NOT create or rename spans, alter parentage, or tag a nested security/viewer span in place of the entry span. Classification SHALL cover framework servlet routes including static resources and SHALL NOT mean that an authenticated human initiated the request.
@@ -47,3 +50,4 @@ Classification SHALL use the configured single/primary tracing bridge and SHALL
#### Scenario: Missing or ambiguous tracer
- **WHEN** no tracer is available, or multiple active tracers have no primary
- **THEN** absence results in safe no-op classification, while ambiguity produces an actionable configuration error
+
diff --git a/openspec/specs/observation-policy/spec.md b/openspec/specs/observation-policy/spec.md
index 924c10c5651..2ea87e2929b 100644
--- a/openspec/specs/observation-policy/spec.md
+++ b/openspec/specs/observation-policy/spec.md
@@ -1,9 +1,7 @@
## Purpose
-Defines stable observation operation names, safe contextual metadata, opt-in interaction identity, and configurable JPA duration filtering.
-
+Defines stable observation operation names, safe contextual metadata, automatic interaction identity, and configurable JPA duration filtering.
## Requirements
-
### Requirement: Existing dynamic observations separate operation and context
Causeway SHALL use fixed operation names for the existing JPA, action invocation, property update and execution-publishing observations. Contextual names and model metadata SHALL use only static entity type, member identity or declared named-query identity. Instance identifiers, bookmarks, object titles, query descriptions and arguments SHALL NOT be introduced into these names or attributes. Execution subscriber counts SHALL NOT be included in names or low-cardinality dimensions. Existin [...]
@@ -24,46 +22,39 @@ Causeway SHALL use fixed operation names for the existing JPA, action invocation
- **WHEN** a safe static identifier is unavailable
- **THEN** the operation remains observable without falling back to object or query descriptions
-### Requirement: Identity metadata requires independent opt-in
-
-Causeway SHALL omit username and multitenancy-token attributes by default. It SHALL support independent `causeway.observation.include-user-name` and `causeway.observation.include-multi-tenancy-token` options, both defaulting to false. Explicitly enabled nonempty values SHALL retain their existing attribute keys and high-cardinality classification. Disabled values SHALL NOT be copied into other Causeway-generated names or attributes. Non-identity interaction metadata SHALL remain available.
-
-#### Scenario: Defaults
-- **WHEN** an observed interaction has a named user and tenancy token without identity opt-ins
-- **THEN** neither identity value is emitted by Causeway interaction tagging
-
-#### Scenario: Independent options
-- **WHEN** exactly one identity option is enabled
-- **THEN** only its corresponding nonempty value is emitted under the existing key
-
-#### Scenario: Both options and empty values
-- **WHEN** both options are enabled
-- **THEN** both nonempty values are emitted, and missing or empty values are omitted
-
### Requirement: JPA duration policy is explicit and validated
-Causeway SHALL default `causeway.observation.duration-filtering-enabled` to false and SHALL support `causeway.observation.jpa-duration-threshold`, defaulting to 2 ms. The threshold SHALL accept zero and positive durations and reject malformed or negative values at startup, including when filtering is disabled. The threshold SHALL apply only to the existing JPA duration-filtered boundaries and SHALL NOT change domain outcomes or observation activation.
+Causeway SHALL expose only `causeway.observation.jpa-duration-threshold` for JPA duration filtering, defaulting to `0ms`. Zero SHALL disable filtering. A positive threshold SHALL mark successful JPA observations strictly below the threshold for discard; failed observations SHALL remain eligible for export. Negative or malformed thresholds SHALL fail startup. No separate duration-filtering-enabled property SHALL exist. Agent-owned export SHALL require a zero threshold because it does not [...]
-#### Scenario: Default parent retention
-- **WHEN** a short successful JPA observation has an exported JDBC child in the deterministically sampled compatibility fixture with default duration policy
-- **THEN** the framework parent remains exported in both supported telemetry configurations and the child's parent ID resolves to it
+#### Scenario: Default or zero threshold
+- **WHEN** the threshold is zero or unset
+- **THEN** short successful JPA spans are retained
-#### Scenario: Configured and zero thresholds
-- **WHEN** Boot-mode filtering is explicitly enabled with a configured threshold
-- **THEN** successful observations below it are suppressed, observations equal to or above it are retained, and zero suppresses none by duration
+#### Scenario: Positive threshold
+- **WHEN** the threshold is positive
+- **THEN** shorter successful JPA spans are marked for discard while failed spans remain eligible
-#### Scenario: Invalid duration
+#### Scenario: Invalid threshold
- **WHEN** the threshold is negative or malformed
-- **THEN** startup reports an actionable configuration failure regardless of whether duration filtering is enabled
-
-#### Scenario: Observation profile inactive
-- **WHEN** policy options are configured but the observation profile is inactive
-- **THEN** Causeway framework observations remain disabled and application observations remain independent
+- **THEN** startup reports a configuration error
### Requirement: Telemetry migration and limitations are documented
-The observability guide SHALL describe changed operation/contextual names, identity opt-ins, duration defaults and configuration examples. It SHALL distinguish Micrometer operation identity from exported contextual names, state that opt-in duration filtering can leave missing parents, and retain the supported agent requirement to disable filtering. It SHALL NOT imply control over application/agent metadata or externally sampled/exported spans. Migration SHALL NOT introduce duplicate lega [...]
+The observability guide SHALL describe operation/contextual names, automatic identity attributes, duration defaults and configuration examples. It SHALL distinguish Micrometer operation identity from exported contextual names, explain that enabled duration filtering can leave missing parents, and retain the supported agent requirement to disable filtering. Migration SHALL NOT introduce duplicate legacy spans.
#### Scenario: Existing deployment migrates
- **WHEN** an operator follows the migration guide
-- **THEN** they can update affected queries and explicitly choose identity and supported duration filtering without requiring another SDK or duplicate observations
+- **THEN** they can inspect automatically included identity attributes and choose supported duration filtering without another SDK or duplicate observations
+
+### Requirement: Interaction identity metadata is automatic
+
+Causeway SHALL always include nonempty username and multitenancy-token values under the existing high-cardinality keys `causeway.user.name` and `causeway.user.multiTenancyToken` on interaction spans. There SHALL be no configuration properties to enable or disable these attributes. Empty values SHALL be omitted and neither value SHALL become a metric label. Other interaction metadata SHALL remain available.
+
+#### Scenario: Defaults
+- **WHEN** an observed interaction has a named user and tenancy token
+- **THEN** both identity values are emitted without configuration
+
+#### Scenario: Missing values
+- **WHEN** an observed interaction has empty or missing identity values
+- **THEN** those attributes are omitted without inventing values
+