(causeway) 06/41: CAUSEWAY-4062: proposes meaningful semantic span names

[da...@apache.org]

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

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

commit ff212f38d71082aed6dccb04c882fca60f57cd5d
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Sep 23 15:17:47 2026 +0100

    CAUSEWAY-4062: proposes meaningful semantic span names
---
 .../improve-semantic-span-names/.openspec.yaml     |   2 +
 .../changes/improve-semantic-span-names/design.md  | 102 +++++++++++++++++++++
 .../improve-semantic-span-names/proposal.md        |  28 ++++++
 .../specs/semantic-span-display-naming/spec.md     |  43 +++++++++
 .../specs/wicket-region-render-observation/spec.md |  67 ++++++++++++++
 .../changes/improve-semantic-span-names/tasks.md   |  22 +++++
 6 files changed, 264 insertions(+)

diff --git a/openspec/changes/improve-semantic-span-names/.openspec.yaml b/openspec/changes/improve-semantic-span-names/.openspec.yaml
new file mode 100644
index 00000000000..265da3d94ed
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-23
diff --git a/openspec/changes/improve-semantic-span-names/design.md b/openspec/changes/improve-semantic-span-names/design.md
new file mode 100644
index 00000000000..60f0c1a818e
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/design.md
@@ -0,0 +1,102 @@
+## Context
+
+Causeway creates Micrometer observations with stable names such as `causeway.action.invocation` and `causeway.wicket.page.render`.
+It currently assigns the same value as the contextual name, so tracing backends display generic operation names even though the observations carry canonical logical identifiers as attributes.
+
+Micrometer Observation distinguishes the stable observation name from the contextual name used by its tracing handler.
+In the pinned Micrometer Tracing 1.0.12 implementation, the tracing handler reads the contextual name when the observation stops, converts uppercase characters to lower-hyphen form, and truncates the result to 50 characters.
+
+Action invocation instrumentation already resolves the owning action's `FeatureIdentifier` before opening the observation.
+Wicket entity pages already resolve the logical object type, and action prompt components retain an `ActionModel` that resolves the prompted action's `FeatureIdentifier`.
+These are bounded metamodel identifiers, unlike object titles, bookmarks, arguments, or other instance data.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make coarse Causeway semantic spans understandable while scanning a trace tree.
+- Preserve stable observation names for conventions and any metric handling.
+- Keep full canonical logical identifiers in existing span attributes.
+- Add one enclosing render span for a Wicket action prompt without observing individual parameters.
+- Preserve no-op behavior, Java-agent-owned trace context, and existing render lifecycle safety.
+
+**Non-Goals:**
+
+- Rename `causeway.root.interaction` according to request outcome.
+- Dynamically name fieldset, property, collection, or action-button render spans.
+- Observe prompt preparation, default calculation, choices calculation, validation, authorization, or action invocation as part of prompt rendering.
+- Add instance identifiers, values, user data, or localized labels to telemetry.
+- Change the OpenTelemetry SDK, exporter, collector, sampling policy, or dependencies.
+
+## Decisions
+
+### Keep observation names stable and specialize contextual names
+
+The stable observation names remain `causeway.action.invocation`, `causeway.wicket.page.render`, and `causeway.wicket.action.prompt.render`.
+Only the Micrometer contextual name will include a compact domain identifier.
+
+This preserves machine-oriented classification while improving the span name rendered by tracing backends.
+Replacing the observation name itself was rejected because it would unnecessarily increase metric and convention cardinality.
+
+### Use compact operation-first display names
+
+Contextual names will use these conceptual forms:
+
+- `invoke <action-member> on <simple-logical-type>` for action invocation;
+- `render <simple-logical-type>` for an entity page;
+- `prompt <action-member> on <simple-logical-type>` for action-prompt rendering.
+
+The implementation will derive the simple type from the final segment of the logical type name and will use the action's logical member name rather than a friendly or localized label.
+Display tokens will be normalized to lower-hyphen form before assignment so that the resulting name is predictable under Micrometer's normalization.
+The operation and action member appear before the type so that the most diagnostic information survives Micrometer's 50-character limit.
+
+The full logical type and action identity remain available in `causeway.object.type` and `causeway.action.id` and are authoritative when a compact display name is ambiguous or truncated.
+Using full logical identities directly in contextual names was rejected because namespace prefixes can consume the complete display-name limit before the member name appears.
+
+### Name the action invocation where its identity is already known
+
+`MemberExecutorServiceDefault` will assign the contextual name before starting the existing action observation.
+No late mutation of the root interaction or inference from descendants is required.
+
+Renaming the root interaction was rejected because a single request can render an object, open a prompt, invoke an action, and render an Ajax response.
+A generic root with meaningful semantic children represents that request more accurately.
+
+### Treat an action prompt as one Wicket render region
+
+The Wicket observation descriptor taxonomy will gain an action-prompt region with stable name `causeway.wicket.action.prompt.render`.
+It will carry `causeway.object.type` and `causeway.action.id`, and its contextual name will identify the prompted action.
+
+The reusable `WicketRenderObservationBehavior` will be attached to the enclosing `ActionParametersPanel`, whose `ActionModel` identifies the prompted action.
+The existing request-local tracker will therefore provide nesting, failure cleanup, Ajax parentage, serialization safety, and no-op handling without a second lifecycle mechanism.
+
+The observation covers the panel's actual render callback and descendant rendering only.
+Individual action parameter fields remain excluded from property observations, preventing span amplification.
+Instrumenting modal, sidebar, and inline prompt shells separately was rejected because presentation style should not create different semantic boundaries or duplicate prompt spans.
+
+### Preserve canonical attributes and privacy rules
+
+Dynamic contextual names will use only static metamodel structure.
+They MUST NOT use object titles, primary keys, bookmarks, property values, action arguments, user names, tenancy tokens, generated Wicket component paths, or localized friendly names.
+
+Canonical attributes remain unchanged for existing spans.
+The new prompt span follows the same `causeway.object.type` and `causeway.action.id` conventions as existing Wicket action render observations.
+
+## Risks / Trade-offs
+
+- [Compact type names can collide across namespaces] → Keep the full logical type and action identity as authoritative attributes and document that display names are navigational aids.
+- [Micrometer truncates contextual names to 50 characters] → Put the operation and action member first, keep names compact, and test long identifiers without relying on the display name for exact filtering.
+- [Prompt work can occur before actual rendering] → Name the span explicitly as prompt rendering and document that preparation, choices, defaults, validation, and authorization may remain outside it.
+- [A prompt component can be rendered more than once in an Ajax request] → Follow the existing component-render semantics and create one observation per actual enclosing prompt render callback.
+- [Changing display names can affect saved backend queries based on operation name] → Preserve stable attributes and document the display-name change so queries can use canonical attributes.
+
+## Migration Plan
+
+Applications receive the new contextual display names and prompt span only when the existing `observation` profile is active.
+No application configuration or persisted domain-data migration is required.
+Operators should update searches that match the old generic span display names to use canonical attributes or stable observation metadata where their backend exposes it.
+Rollback consists of reverting the instrumentation change; SDK ownership, sampling, and export configuration remain unchanged.
+
+## Open Questions
+
+- Confirm during implementation whether the final logical-type segment should recognize separators other than `.` for all supported logical naming conventions.
+- Confirm with a representative modal, sidebar, and inline prompt that `ActionParametersPanel` is the single common render boundary and does not produce duplicate observations.
diff --git a/openspec/changes/improve-semantic-span-names/proposal.md b/openspec/changes/improve-semantic-span-names/proposal.md
new file mode 100644
index 00000000000..52034526309
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+Causeway's semantic spans currently use generic display names, forcing operators to open span attributes to discover which domain type or action a span represents.
+The framework already has stable logical type and member identifiers at the relevant boundaries, so it can make traces easier to scan without exposing object-instance data or destabilizing observation names.
+
+## What Changes
+
+- Give action-invocation spans concise contextual display names derived from the invoked action's stable logical identifier while preserving `causeway.action.invocation` as the observation name and `causeway.action.id` as the canonical attribute.
+- Give Wicket entity-page render spans concise contextual display names derived from the rendered domain object's stable logical type while preserving `causeway.wicket.page.render` as the observation name and `causeway.object.type` as the canonical attribute.
+- Add one bounded Wicket action-prompt render observation identified by the prompted action, without creating spans for individual parameter fields.
+- Keep root-interaction and fine-grained fieldset, property, collection, and action-button render display names stable in this change.
+- Continue to prohibit object titles, bookmarks, primary keys, argument values, user identities, tenancy identifiers, and other instance-specific data from span names and attributes.
+- Document display-name normalization and truncation constraints and require canonical attributes to remain authoritative for filtering and correlation.
+
+## Capabilities
+
+### New Capabilities
+
+- `semantic-span-display-naming`: Defines human-readable contextual names for coarse Causeway semantic spans while retaining stable observation names, canonical attributes, and bounded cardinality.
+
+### Modified Capabilities
+
+- `wicket-region-render-observation`: Adds meaningful entity-page contextual names and a bounded action-prompt render observation to the existing Wicket render taxonomy.
+
+## Impact
+
+The change affects core runtime action instrumentation, Wicket render observation descriptors and attachment points, focused observation tests, and the Micrometer tracing operations documentation.
+It changes exported span display names for action invocations and Wicket entity-page rendering but does not change activation, trace parentage, sampling, SDK ownership, dependencies, or canonical span attributes.
diff --git a/openspec/changes/improve-semantic-span-names/specs/semantic-span-display-naming/spec.md b/openspec/changes/improve-semantic-span-names/specs/semantic-span-display-naming/spec.md
new file mode 100644
index 00000000000..76f6b917e73
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/specs/semantic-span-display-naming/spec.md
@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Meaningful action-invocation display name
+Causeway SHALL retain `causeway.action.invocation` as the stable observation name and SHALL assign each action-invocation observation a contextual display name derived from the action's stable logical type and logical member name.
+The display name SHALL identify the invocation operation and prompted member without requiring an operator to inspect span attributes.
+
+#### Scenario: Action identity is available
+- **WHEN** Causeway invokes an action with observation active
+- **THEN** the exported span display name identifies the operation as an invocation
+- **AND** it contains a compact form of the action's logical member and declaring type
+- **AND** the observation name remains `causeway.action.invocation`
+- **AND** `causeway.action.id` retains the full canonical action identifier
+
+### Requirement: Bounded contextual naming
+Causeway SHALL derive semantic span contextual names only from bounded operation names and static metamodel identifiers.
+Causeway MUST NOT include domain-object instance identifiers, object titles, bookmarks, values, arguments, localized labels, user identities, or tenancy identifiers in contextual names.
+
+#### Scenario: Invocation has instance-specific context
+- **WHEN** an observed action is invoked on a particular domain-object instance with argument values
+- **THEN** its contextual name contains no target-instance identity, object title, bookmark, or argument value
+- **AND** two invocations of the same logical action use the same contextual name
+
+### Requirement: Canonical identity remains authoritative
+Causeway SHALL retain full canonical logical identifiers as span attributes when it uses compact or truncated contextual display names.
+Operators SHALL be able to use those attributes to disambiguate equal display names and to identify spans whose contextual names were truncated by the tracing integration.
+
+#### Scenario: Compact names collide
+- **WHEN** two logical actions have the same compact type and member display name but different canonical logical identities
+- **THEN** their contextual names MAY be equal
+- **AND** their `causeway.action.id` attributes distinguish the actions
+
+#### Scenario: Contextual name exceeds tracing limit
+- **WHEN** a generated contextual name exceeds the tracing integration's display-name limit
+- **THEN** truncation does not remove or alter the full canonical identity attributes
+
+### Requirement: Generic root-interaction naming
+Causeway SHALL retain `causeway.root.interaction` as the contextual and stable observation name for the root interaction.
+Semantic child spans SHALL describe action invocation, prompt rendering, and domain-object rendering rather than assigning one inferred purpose to the root.
+
+#### Scenario: Request performs multiple semantic operations
+- **WHEN** one request performs more than one semantic operation
+- **THEN** the root span remains named `causeway.root.interaction`
+- **AND** each instrumented semantic operation is represented by its applicable child span
diff --git a/openspec/changes/improve-semantic-span-names/specs/wicket-region-render-observation/spec.md b/openspec/changes/improve-semantic-span-names/specs/wicket-region-render-observation/spec.md
new file mode 100644
index 00000000000..6b3a5eee195
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/specs/wicket-region-render-observation/spec.md
@@ -0,0 +1,67 @@
+## MODIFIED Requirements
+
+### Requirement: Entity-page render observation
+When observation is active, the Wicket viewer SHALL create one `causeway.wicket.page.render` observation for each server-side render of an entity page.
+The observation SHALL join the current Java-agent-owned trace, SHALL use the Wicket viewer module metadata convention, and SHALL have a contextual display name derived from the rendered object's stable logical type.
+The stable observation name SHALL remain `causeway.wicket.page.render`, and `causeway.object.type` SHALL retain the full canonical logical type.
+
+#### Scenario: Full entity-page render
+- **WHEN** Wicket renders an entity page during a full HTTP response with observation active
+- **THEN** one `causeway.wicket.page.render` observation covers the page's actual server-side rendering
+- **AND** the observation is a descendant of the current request or Causeway interaction span
+- **AND** its contextual display name identifies the render operation and a compact form of the logical object type
+- **AND** its `causeway.object.type` attribute contains the full canonical logical type
+
+#### Scenario: Observation is inactive
+- **WHEN** Wicket renders an entity page without the `observation` profile active
+- **THEN** rendering behavior and output remain unchanged
+- **AND** no exported Causeway Wicket render span is produced
+
+## ADDED Requirements
+
+### Requirement: Action-prompt render observation
+When observation is active, the Wicket viewer SHALL create one `causeway.wicket.action.prompt.render` observation around each actual render callback of an enclosing action-parameter prompt panel.
+The observation SHALL use a contextual display name derived from the prompted action's stable logical type and logical member name and SHALL use the existing Wicket render lifecycle infrastructure.
+
+#### Scenario: Parameterized action prompt is rendered
+- **WHEN** Wicket renders the enclosing prompt panel for a parameterized action
+- **THEN** one `causeway.wicket.action.prompt.render` observation covers the panel's actual render callback and descendant rendering
+- **AND** its contextual display name identifies the prompt operation and a compact form of the action's logical member and declaring type
+- **AND** it joins the current request trace with the active render region as its parent when one exists
+
+#### Scenario: Prompt presentation styles
+- **WHEN** the same logical action prompt is presented inline, in a modal, or in a sidebar
+- **THEN** the viewer uses the same semantic observation name and contextual naming convention
+- **AND** presentation-shell rendering does not create a duplicate action-prompt observation
+
+### Requirement: Bounded action-prompt metadata
+An action-prompt render observation SHALL carry the full canonical `causeway.object.type` and `causeway.action.id` attributes.
+It MUST NOT carry action arguments, parameter values, object titles, bookmarks, target-instance identifiers, localized labels, user identities, tenancy identifiers, or generated Wicket component paths.
+
+#### Scenario: Prompt contains populated parameters
+- **WHEN** Wicket renders an action prompt whose parameter models contain defaults or user-supplied values
+- **THEN** the observation identifies only the logical object type and action
+- **AND** neither its contextual name nor its attributes contain parameter values or target-instance data
+
+### Requirement: Single bounded prompt region
+The action-prompt observation SHALL cover the enclosing prompt render region and SHALL NOT create observations for individual action parameter fields.
+The observation SHALL represent rendering only and SHALL NOT be presented as covering defaults, choices, validation, usability, visibility, authorization, or other preparation performed outside the render callback.
+
+#### Scenario: Prompt has multiple parameters
+- **WHEN** an action prompt renders multiple parameter fields
+- **THEN** one enclosing action-prompt render observation is produced
+- **AND** the parameter fields do not produce `causeway.wicket.property.render` observations
+
+#### Scenario: Prompt preparation precedes rendering
+- **WHEN** defaults, choices, validation, or authorization work completes before the prompt panel's render callback
+- **THEN** that work is not attributed to `causeway.wicket.action.prompt.render`
+- **AND** operational documentation describes the render-only boundary
+
+### Requirement: Stable fine-grained render display names
+The Wicket viewer SHALL retain the existing stable contextual names for fieldset, property, collection, and action-button render observations in this change.
+Their canonical layout and metamodel attributes SHALL continue to identify the rendered region.
+
+#### Scenario: Entity member region is rendered
+- **WHEN** Wicket renders an observed fieldset, property, collection, or action-button region
+- **THEN** its contextual name remains the applicable stable `causeway.wicket.*.render` name
+- **AND** its existing canonical region attributes remain available for identification
diff --git a/openspec/changes/improve-semantic-span-names/tasks.md b/openspec/changes/improve-semantic-span-names/tasks.md
new file mode 100644
index 00000000000..bc9bfacfe9f
--- /dev/null
+++ b/openspec/changes/improve-semantic-span-names/tasks.md
@@ -0,0 +1,22 @@
+## 1. Contextual Naming Foundation
+
+- [ ] 1.1 Add an internal observation naming helper that produces bounded operation-first contextual names from logical type and member identifiers without using instance data or localized labels.
+- [ ] 1.2 Add focused unit tests for simple and namespaced logical types, action members, normalization, collisions, and names long enough to encounter the tracing display-name limit.
+
+## 2. Action Invocation Naming
+
+- [ ] 2.1 Update `MemberExecutorServiceDefault` to assign the existing action-invocation observation a contextual name derived from the owning action's logical type and member name while retaining the stable observation name and canonical attributes.
+- [ ] 2.2 Extend the action observation tests to verify the contextual name, stable observation name, canonical action identifier, parentage, success lifecycle, and failure lifecycle.
+
+## 3. Wicket Page and Prompt Rendering
+
+- [ ] 3.1 Update the Wicket render descriptor so entity-page observations receive a contextual name derived from the logical object type while existing fine-grained region contextual names remain stable.
+- [ ] 3.2 Add the `causeway.wicket.action.prompt.render` descriptor with compact contextual naming and canonical `causeway.object.type` and `causeway.action.id` attributes.
+- [ ] 3.3 Attach the reusable render observation behavior once at the common `ActionParametersPanel` boundary without instrumenting individual parameter fields or presentation-specific prompt shells.
+- [ ] 3.4 Extend Wicket observation tests to cover page naming, prompt metadata, render lifecycle and parentage, no-op operation, serialization safety, parameter exclusion, and the absence of duplicate prompt observations across supported presentation styles.
+
+## 4. Documentation and Validation
+
+- [ ] 4.1 Update `adoc/micrometer-tracing-operations.adoc` with the contextual naming convention, canonical-attribute guidance, 50-character tracing limit, prompt render boundary, privacy rules, and changed example trace tree.
+- [ ] 4.2 Run the focused core configuration, runtime-services, and Wicket UI observation test suites and record the results.
+- [ ] 4.3 Validate a representative action invocation, entity-page render, and parameterized action prompt against the Java-agent tracing fixture or local Jaeger, confirming meaningful display names, canonical attributes, correct nesting, and no per-parameter span amplification.