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/09/25 10:34:24 UTC
(causeway) 02/08: CAUSEWAY-4068: proposes interaction trace correlation
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 38c2653b152e7fc304df9f2244e20d87c27e1341
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Sep 25 10:27:38 2026 +0100
CAUSEWAY-4068: proposes interaction trace correlation
---
.../add-interaction-id-to-root-span/.openspec.yaml | 2 +
.../add-interaction-id-to-root-span/design.md | 61 ++++++++++++++++++++++
.../add-interaction-id-to-root-span/proposal.md | 27 ++++++++++
.../specs/interaction-trace-correlation/spec.md | 44 ++++++++++++++++
.../add-interaction-id-to-root-span/tasks.md | 14 +++++
5 files changed, 148 insertions(+)
diff --git a/openspec/changes/add-interaction-id-to-root-span/.openspec.yaml b/openspec/changes/add-interaction-id-to-root-span/.openspec.yaml
new file mode 100644
index 00000000000..abd7c5ae1ca
--- /dev/null
+++ b/openspec/changes/add-interaction-id-to-root-span/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-25
diff --git a/openspec/changes/add-interaction-id-to-root-span/design.md b/openspec/changes/add-interaction-id-to-root-span/design.md
new file mode 100644
index 00000000000..11a71a6d249
--- /dev/null
+++ b/openspec/changes/add-interaction-id-to-root-span/design.md
@@ -0,0 +1,61 @@
+## Context
+
+`InteractionServiceDefault` creates a `CausewayInteraction` with its UUID before starting the `causeway.root.interaction` observation.
+That observation spans the lifetime of the top-level interaction and naturally parents Causeway semantic work, but it currently exposes only generic bean and module attributes.
+Operators consequently cannot move directly from an interaction ID recorded in command, execution-log, or audit data to the corresponding trace.
+
+The Java agent owns the telemetry SDK, HTTP entry spans, propagation, sampling, and export.
+Causeway instrumentation must continue to use the existing Micrometer observation integration and must remain inert when the `observation` profile is inactive.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Correlate one root interaction span with the exact UUID of its `CausewayInteraction`.
+- Export the UUID under the stable attribute name `causeway.interaction.id`.
+- Classify the UUID as high-cardinality telemetry data.
+- Verify the attribute both at observation creation and after Java-agent OTLP export.
+- Explain how to locate a containing trace with Jaeger tag search.
+
+**Non-Goals:**
+
+- Changing the generated interaction ID or its lifecycle.
+- Using an interaction ID as an OpenTelemetry trace ID or span ID.
+- Changing span names, hierarchy, sampling, propagation, or export.
+- Copying the interaction ID to the agent-owned HTTP span or every descendant span.
+- Adding an application telemetry API, SDK, exporter, or dependency.
+
+## Decisions
+
+### Annotate the root interaction observation
+
+`InteractionServiceDefault` will supply the newly created interaction's UUID while constructing the root observation and will add `causeway.interaction.id` before the observation starts.
+This preserves the one-to-one relationship between a Causeway interaction and its root interaction span, including non-HTTP and background interactions.
+
+Annotating the Java-agent-owned HTTP span was rejected because a request can theoretically contain multiple sequential interactions and because background interactions have no HTTP parent.
+Annotating every descendant was rejected because trace ancestry already provides correlation and duplication would increase telemetry volume.
+
+### Use a high-cardinality observation key value
+
+The UUID will be represented as its canonical string and added with Micrometer's high-cardinality observation API.
+The attribute is useful for exact lookup but unsuitable for metric dimensions or low-cardinality aggregation.
+
+Using the UUID in the span display name was rejected because it would destroy useful operation grouping and create unbounded operation-name cardinality.
+
+### Remain within the observation abstraction
+
+Root observation creation will continue through `CausewayObservationIntegration.ObservationProvider` and `ObservationClosure`.
+The runtime service will not manipulate an OpenTelemetry `Span` directly, preserving inactive-registry behavior and the existing Java-agent ownership boundary.
+
+### Verify the exported contract
+
+The root-observation unit test will use a deterministic interaction ID and inspect the observation context for the exact high-cardinality value.
+The Java-agent compatibility fixture will also use a known UUID and assert that the OTLP-exported root interaction span contains `causeway.interaction.id` with that value.
+The operations runbook will document exact Jaeger tag lookup and advise leaving the operation filter unset so the root interaction span can satisfy the attribute query.
+
+## Risks / Trade-offs
+
+- **High-cardinality indexing can increase backend storage and index costs** → Attach the UUID only to one span per interaction and document its intended exact-correlation use.
+- **A backend may not index arbitrary span attributes** → Document the validated Jaeger behavior without claiming universal backend support.
+- **Users may expect the attribute on the HTTP entry span** → Document that Jaeger returns the containing trace when the matching attribute is on the root interaction child span.
+- **Traces held by Jaeger's in-memory store can expire before lookup** → Retain the existing ring-buffer warning and clarify that lookup only works while the trace remains stored.
diff --git a/openspec/changes/add-interaction-id-to-root-span/proposal.md b/openspec/changes/add-interaction-id-to-root-span/proposal.md
new file mode 100644
index 00000000000..3d27ce81de1
--- /dev/null
+++ b/openspec/changes/add-interaction-id-to-root-span/proposal.md
@@ -0,0 +1,27 @@
+## Why
+
+Operators can correlate Causeway command, execution-log, and audit records through the interaction ID, but exported traces do not currently expose that identifier.
+Adding the interaction ID to the root interaction span allows an operator to locate the containing trace directly from a known interaction ID, including when using Jaeger's in-memory storage.
+
+## What Changes
+
+- Add the current Causeway interaction ID to each `causeway.root.interaction` observation as the high-cardinality `causeway.interaction.id` span attribute.
+- Keep the attribute on the root interaction span rather than copying it to the agent-owned HTTP entry span or every descendant span.
+- Preserve current span names, parentage, behavior without active observation, and failure handling.
+- Extend tracing verification and operational documentation to cover interaction-ID correlation and Jaeger tag search.
+
+## Capabilities
+
+### New Capabilities
+
+- `interaction-trace-correlation`: Defines how a top-level Causeway interaction exposes its interaction ID for trace correlation.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change affects root interaction observation creation in `core/runtimeservices`, its unit tests, the OpenTelemetry Java-agent compatibility regression, and the Micrometer tracing operations runbook.
+It adds no dependency, public API, exporter, or telemetry SDK and does not alter the existing opt-in `observation` profile.
+The UUID-valued attribute is intentionally high-cardinality and may increase telemetry storage or indexing costs when traces are retained.
diff --git a/openspec/changes/add-interaction-id-to-root-span/specs/interaction-trace-correlation/spec.md b/openspec/changes/add-interaction-id-to-root-span/specs/interaction-trace-correlation/spec.md
new file mode 100644
index 00000000000..18985a166c7
--- /dev/null
+++ b/openspec/changes/add-interaction-id-to-root-span/specs/interaction-trace-correlation/spec.md
@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: Root interaction span exposes the interaction ID
+When observation is active, the system SHALL add the current Causeway interaction ID to the corresponding `causeway.root.interaction` span as the high-cardinality string attribute `causeway.interaction.id`.
+The attribute value MUST be the canonical string representation of the UUID returned by that interaction's `getInteractionId()` method.
+
+#### Scenario: Top-level interaction starts with active observation
+- **WHEN** the system opens a top-level Causeway interaction while observation is active
+- **THEN** its `causeway.root.interaction` span contains `causeway.interaction.id` with the exact current interaction UUID
+
+#### Scenario: Nested interaction layer opens
+- **WHEN** the system opens a nested interaction layer within an existing top-level interaction
+- **THEN** the system retains one root interaction span and its attribute identifies the shared top-level interaction
+
+### Requirement: Correlation does not alter trace identity or structure
+The system SHALL use the interaction ID only as a span attribute and MUST NOT derive an OpenTelemetry trace ID, span ID, or span display name from it.
+The system MUST NOT directly copy the attribute to the agent-owned HTTP entry span or every descendant span.
+
+#### Scenario: Root interaction is beneath an HTTP entry span
+- **WHEN** an HTTP request has an agent-owned entry span and opens a Causeway interaction
+- **THEN** the Causeway root interaction span is annotated without changing the existing trace and span parentage
+
+#### Scenario: Root interaction has semantic descendants
+- **WHEN** action, rendering, application, or JDBC spans occur beneath the root interaction span
+- **THEN** the interaction-ID annotation does not change their names or hierarchy
+
+### Requirement: Observation remains optional
+The interaction-ID correlation SHALL preserve existing interaction lifecycle, result, and failure behavior when observation is inactive or active.
+
+#### Scenario: Observation is inactive
+- **WHEN** a top-level interaction runs without the `observation` profile
+- **THEN** the interaction completes with its existing behavior and no telemetry SDK or exporter is required
+
+#### Scenario: Interaction work fails
+- **WHEN** work inside an observed top-level interaction throws a failure
+- **THEN** the root observation records and closes with the existing failure behavior while retaining its interaction-ID attribute
+
+### Requirement: Jaeger correlation is documented
+The tracing operations guidance SHALL describe how to search for a stored trace using the exact `causeway.interaction.id` span attribute.
+The guidance MUST state the relevant in-memory retention and operation-filter constraints.
+
+#### Scenario: Operator has an interaction ID
+- **WHEN** an operator searches Jaeger for `causeway.interaction.id=<UUID>` without restricting the search to a different span operation
+- **THEN** the guidance explains that Jaeger can return the trace containing the matching root interaction span while that trace remains retained
diff --git a/openspec/changes/add-interaction-id-to-root-span/tasks.md b/openspec/changes/add-interaction-id-to-root-span/tasks.md
new file mode 100644
index 00000000000..e69777aeefd
--- /dev/null
+++ b/openspec/changes/add-interaction-id-to-root-span/tasks.md
@@ -0,0 +1,14 @@
+## 1. Root Interaction Correlation
+
+- [ ] 1.1 Pass the newly created `CausewayInteraction` identity into root observation construction and add `causeway.interaction.id` as a high-cardinality canonical UUID string before the observation starts.
+- [ ] 1.2 Preserve existing nested-layer reuse, inactive-observation behavior, error recording, cleanup, span naming, and span parentage.
+
+## 2. Automated Verification
+
+- [ ] 2.1 Extend `InteractionServiceDefaultObservationTest` with a deterministic interaction ID and assertions that the root observation context carries the exact high-cardinality attribute across normal and failure lifecycles.
+- [ ] 2.2 Extend the tracing compatibility fixture and OTLP export assertions to prove that `causeway.root.interaction` exports the expected `causeway.interaction.id` attribute without changing HTTP, action, or JDBC ancestry.
+- [ ] 2.3 Run the targeted runtime-services tests and the Java 11 tracing compatibility regression, and resolve any failures.
+
+## 3. Operational Documentation
+
+- [ ] 3.1 Update the Micrometer tracing operations runbook to describe the root-span attribute, exact Jaeger tag lookup, operation-filter constraint, high-cardinality trade-off, and in-memory retention limitation.