(causeway) 07/10: CAUSEWAY-4068: propose built-in agent observation bridge

[da...@apache.org]

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 a7c3d3584e65b7ffd2e612e99d58858427d08435
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Oct 7 12:05:00 2026 +0100

    CAUSEWAY-4068: propose built-in agent observation bridge
---
 .../.openspec.yaml                                 |  2 +
 .../provide-agent-observation-bridge/design.md     | 27 +++++++++++++
 .../provide-agent-observation-bridge/proposal.md   | 23 +++++++++++
 .../specs/agent-observation-bridge/spec.md         | 45 ++++++++++++++++++++++
 .../provide-agent-observation-bridge/tasks.md      | 11 ++++++
 5 files changed, 108 insertions(+)

diff --git a/openspec/changes/provide-agent-observation-bridge/.openspec.yaml b/openspec/changes/provide-agent-observation-bridge/.openspec.yaml
new file mode 100644
index 00000000000..a26662f7a5f
--- /dev/null
+++ b/openspec/changes/provide-agent-observation-bridge/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-07
diff --git a/openspec/changes/provide-agent-observation-bridge/design.md b/openspec/changes/provide-agent-observation-bridge/design.md
new file mode 100644
index 00000000000..ba6ad9c637b
--- /dev/null
+++ b/openspec/changes/provide-agent-observation-bridge/design.md
@@ -0,0 +1,27 @@
+## Context
+
+Petclinic and the tracing fixture duplicate an OtelTracer/ObservationRegistry bridge. Manual exclusions select the agent as trace owner. Core configuration already selects the single or primary registry and tracer.
+
+## Goals / Non-Goals
+
+Goals: configuration-only adoption, one trace owner, preserved Boot defaults and Micrometer metrics, tested production bridge.
+Non-goals: downloading or attaching the agent automatically; span duration filtering; changing instrumentation boundaries.
+
+## Decisions
+
+Use a guarded Boot auto-configuration with optional Micrometer OTel bridge dependencies. With both profiles active, create missing tracer and registry beans; the tracer wraps GlobalOpenTelemetry and creates no SDK or exporter. An application registry retains responsibility for its handlers. The existing fallback registry is limited to observation without agent, avoiding early duplicate registration.
+
+Use an EnvironmentPostProcessor after ConfigData to merge the supported baseline's tracing/WebMVC exclusions whenever the agent profile is active, including when Causeway observations are inactive. This prevents a competing Boot trace owner independently of Causeway activation. Disable Boot OTEL environment mapping and trace export for this profile, retaining Micrometer metrics despite OTEL_METRICS_EXPORTER=none. Preserve unrelated application exclusions. A missing bridge dependency with [...]
+
+Use real agent and Boot exported-trace fixtures without application bridge copies or agent exclusions to verify ownership, ancestry, classification and inactive behavior.
+
+## Risks / Trade-offs
+
+- Boot class names evolve → pin exclusions to current baseline and validate real Boot startup.
+- Agent profile without an attached agent → bridge uses the global API (possibly no-op); documentation makes attachment explicit and no SDK is constructed.
+- HTTP observation exclusion removes Boot HTTP request meters → document this; JVM and Causeway Micrometer meters remain available.
+- Custom registry handlers can target another pipeline → preserve customization and document responsibility to share the selected tracer.
+
+## Migration Plan
+
+Delete app-owned bridge and manual agent exclusions; retain the BOM-managed bridge dependency, attach the agent and activate observation,agent. To return to Boot mode remove attachment and agent profile. Existing explicit exclusions remain compatible.
diff --git a/openspec/changes/provide-agent-observation-bridge/proposal.md b/openspec/changes/provide-agent-observation-bridge/proposal.md
new file mode 100644
index 00000000000..458978ccfea
--- /dev/null
+++ b/openspec/changes/provide-agent-observation-bridge/proposal.md
@@ -0,0 +1,23 @@
+## Why
+
+Agent-managed tracing currently requires application-owned bridge code and Boot exclusions. This makes a supported telemetry setup unnecessarily difficult to adopt and maintain.
+
+## What Changes
+
+- Supply the agent observation bridge in Causeway when `observation,agent` profiles are active.
+- Automatically exclude competing Boot tracing and HTTP observation configuration for the `agent` profile, preserving existing exclusions and Micrometer metrics.
+- Keep the bridge dependency optional and respect application-provided registry/tracer beans.
+- Remove sample/fixture bridge copies and update the M3 how-to and user guide to show configuration-only adoption.
+
+## Capabilities
+
+### New Capabilities
+- `agent-observation-bridge`: Built-in agent-owned tracing setup with optional dependencies, profile activation and application overrides.
+
+### Modified Capabilities
+
+None. This implements the existing single-owner telemetry guarantees without changing instrumentation boundaries.
+
+## Impact
+
+Core configuration, Petclinic observation profile, exported-trace compatibility fixtures, M3 how-to and observability user guide. No duration filtering or exporter is introduced.
diff --git a/openspec/changes/provide-agent-observation-bridge/specs/agent-observation-bridge/spec.md b/openspec/changes/provide-agent-observation-bridge/specs/agent-observation-bridge/spec.md
new file mode 100644
index 00000000000..38f02a93a01
--- /dev/null
+++ b/openspec/changes/provide-agent-observation-bridge/specs/agent-observation-bridge/spec.md
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Agent tracing is available without application bridge code
+
+Causeway SHALL supply a missing Micrometer tracer wrapping GlobalOpenTelemetry and a missing observation registry using that tracer when observation and agent profiles are active with the OTel bridge dependency. It SHALL NOT construct an SDK or exporter. A missing bridge dependency SHALL produce an actionable startup error. Agent attachment SHALL remain the application's responsibility.
+
+#### Scenario: Attached agent observes framework work
+- **WHEN** an application attaches the agent and activates observation,agent without custom bridge code
+- **THEN** framework spans, identity/correlation attributes and entry classification join automatic HTTP and JDBC spans in one trace without duplicate framework export
+
+#### Scenario: Optional dependency is absent in Boot mode
+- **WHEN** the agent profile is inactive and the bridge dependency is absent
+- **THEN** ordinary Causeway startup remains supported
+
+#### Scenario: Required dependency is absent in agent mode
+- **WHEN** both profiles are active without the bridge dependency
+- **THEN** startup explains which dependency to add
+
+### Requirement: Agent profile selects one trace owner
+
+The agent profile SHALL automatically suppress competing Boot SDK, tracing exporter, tracing handler and WebMVC observation configuration. It SHALL preserve unrelated user exclusions and keep Micrometer metrics independent of agent-only OTEL environment settings. Boot-managed configuration SHALL remain unchanged without that profile.
+
+#### Scenario: Agent tracing with Micrometer metrics
+- **WHEN** the agent profile is active with OTEL_METRICS_EXPORTER=none
+- **THEN** Boot does not create a competing trace pipeline and Micrometer metrics remain enabled by their application configuration
+
+#### Scenario: Causeway observations are inactive
+- **WHEN** only the agent profile is active
+- **THEN** automatic agent HTTP/JDBC tracing remains available without Causeway framework spans
+
+#### Scenario: Existing application exclusions
+- **WHEN** an application already excludes another auto-configuration
+- **THEN** that exclusion remains alongside the agent ownership exclusions
+
+### Requirement: Application telemetry customization remains supported
+
+The bridge SHALL back off from application-provided registry or tracer beans. The framework SHALL use single or primary candidates and reject ambiguous active candidates. Custom registry owners SHALL remain responsible for their observation handlers.
+
+#### Scenario: Custom tracer
+- **WHEN** an application supplies one tracer with both profiles active
+- **THEN** the default agent registry and Causeway entry classifier share that tracer
+
+#### Scenario: Custom registry
+- **WHEN** an application supplies a registry with both profiles active
+- **THEN** the bridge does not replace it or install additional handlers into it
diff --git a/openspec/changes/provide-agent-observation-bridge/tasks.md b/openspec/changes/provide-agent-observation-bridge/tasks.md
new file mode 100644
index 00000000000..868a03e4094
--- /dev/null
+++ b/openspec/changes/provide-agent-observation-bridge/tasks.md
@@ -0,0 +1,11 @@
+## 1. Framework wiring
+
+- [ ] 1.1 Add optional OTel bridge dependency and guarded agent tracer/registry auto-configuration.
+- [ ] 1.2 Add early agent ownership defaults preserving user exclusions and metrics.
+- [ ] 1.3 Test profiles, optional dependency, custom beans and exclusion merging.
+
+## 2. Adoption and verification
+
+- [ ] 2.1 Remove Petclinic and fixture bridge copies/manual agent exclusions; exercise production wiring.
+- [ ] 2.2 Update M3 how-to, user guide, sample instructions and roadmap.
+- [ ] 2.3 Validate focused core tests, exported Boot/agent trace regressions and sample packaging.