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/21 22:00:43 UTC
(causeway) 12/14: CAUSEWAY-3975: proposes Boot 2.7 tracing operations guide
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-3975
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit b8fb6c56e407532d091083e5e052b410ec85b343
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Sep 21 22:00:11 2026 +0100
CAUSEWAY-3975: proposes Boot 2.7 tracing operations guide
---
.../.openspec.yaml | 2 +
.../design.md | 90 +++++++++++++++++++
.../proposal.md | 29 ++++++
.../boot27-micrometer-tracing-operations/spec.md | 100 +++++++++++++++++++++
.../tasks.md | 31 +++++++
5 files changed, 252 insertions(+)
diff --git a/openspec/changes/document-boot27-micrometer-tracing-operations/.openspec.yaml b/openspec/changes/document-boot27-micrometer-tracing-operations/.openspec.yaml
new file mode 100644
index 00000000000..563fab5abae
--- /dev/null
+++ b/openspec/changes/document-boot27-micrometer-tracing-operations/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-21
diff --git a/openspec/changes/document-boot27-micrometer-tracing-operations/design.md b/openspec/changes/document-boot27-micrometer-tracing-operations/design.md
new file mode 100644
index 00000000000..1e2e8405812
--- /dev/null
+++ b/openspec/changes/document-boot27-micrometer-tracing-operations/design.md
@@ -0,0 +1,90 @@
+## Context
+
+The maintenance branch provides an opt-in observation substrate and semantic observations for root interactions and action invocations.
+The validated deployment model uses OpenTelemetry Java agent 1.31.0 with Spring Boot 2.7.18 and Java 11, while the Java agent owns the SDK, HTTP and JDBC instrumentation, sampling, and export.
+The target deployment platform is Azure Container Apps, whose optional managed OpenTelemetry agent is a collector and routing service rather than a replacement for the in-process Java instrumentation agent.
+The team needs concise repository-local guidance rather than material intended for the Causeway website.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a one-page runbook under `adoc/` for local evaluation with Jaeger.
+- Specify the minimal Docker image change needed to package the Java agent.
+- Specify application-level and managed-environment-level Azure Container Apps configuration.
+- Clearly distinguish the OpenTelemetry Java agent from the Azure Container Apps managed OpenTelemetry agent.
+- Provide enough verification and troubleshooting information for the maintenance team to prove the semantic trace ancestry.
+
+**Non-Goals:**
+
+- Add the guide to Antora or any published website navigation.
+- Add or change production code, dependencies, runtime defaults, or public APIs.
+- Provide a complete Azure infrastructure template for a specific application or observability vendor.
+- Document an application-owned OpenTelemetry SDK or duplicate exporter.
+- Promise semantic spans beyond root interactions and action invocations.
+
+## Decisions
+
+### Keep one repository-local runbook
+
+The implementation will add `adoc/micrometer-tracing-operations.adoc` as a concise one-page runbook.
+It will use three primary sections matching the team's workflow: local laptop, Docker image, and Azure Container Apps runtime.
+This location follows the repository's existing internal build and operational notes without implying that the file is part of the Antora website.
+
+An Antora page was rejected because this branch's guidance will not be published on the website.
+A release-note page was rejected because the runbook must remain easy for the maintenance team to find after the release date.
+
+### Package the Java agent in the image but configure it at runtime
+
+The Docker example will copy the validated agent JAR to a stable path such as `/opt/opentelemetry/opentelemetry-javaagent.jar`.
+The image will not bake the OTLP endpoint, service name, sampling rate, or Spring profile into an environment-specific layer.
+The runtime platform will attach the JAR through `JAVA_TOOL_OPTIONS` and supply all deployment-specific settings.
+No additional listening port is required in the application container for trace export.
+
+Downloading the agent at container startup was rejected because it adds network availability and artifact-integrity risks to every replica start.
+Baking all telemetry settings into the image was rejected because the same image must move safely between local and Azure environments.
+
+### Use Jaeger all-in-one for local evaluation
+
+The local procedure will run a pinned Jaeger all-in-one container exposing OTLP HTTP on 4318 and the UI on 16686.
+The application will use the validated Java agent with traces exported over `http/protobuf`, metrics and logs exporters disabled, always-on sampling for local testing, and the `observation` profile active.
+The procedure will tell the developer to invoke an HTTP action that performs JDBC work and then inspect the expected semantic ancestry in Jaeger.
+
+### Treat the two agents as separate layers
+
+The OpenTelemetry Java agent runs inside the application JVM and supplies bytecode instrumentation, the SDK, sampling, and OTLP export.
+The Azure Container Apps managed OpenTelemetry agent runs at the managed-environment level and receives OTLP data before routing it to Application Insights or another configured destination.
+When the managed agent is enabled, Azure automatically injects `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`, and `OTEL_RESOURCE_ATTRIBUTES`; the application must not override those values unless deliberately bypassing the managed agent.
+The Java agent JAR is still required because the managed Azure agent does not instrument the application JVM.
+
+### Keep application and environment settings explicit
+
+The Container App revision will set `JAVA_TOOL_OPTIONS`, include the `observation` Spring profile, set `OTEL_SERVICE_NAME`, select the OTLP traces exporter, disable metrics and logs export for this tracing-only slice, and set a production sampling policy.
+The managed Container Apps environment will configure the managed OpenTelemetry destination and trace routing when that option is used.
+If the managed agent is not used, the Container App will instead set the OTLP endpoint, protocol, and any authentication headers needed by the external collector, using secret references for sensitive values.
+The guide will note that changing Container App environment variables creates a new revision.
+
+### Preserve the narrow semantic and privacy contract
+
+The runbook will list `causeway.root.interaction` and `causeway.action.invocation`, plus `causeway.action.id` and `causeway.execution.initiatedBy`.
+It will show the ordered ancestry `HTTP → causeway.root.interaction → causeway.action.invocation → JDBC` while allowing automatic intermediary spans.
+It will state that Causeway semantic instrumentation does not capture arguments, results, target identifiers, user names, tenancy tokens, or other instance-specific application data.
+
+## Risks / Trade-offs
+
+- [Risk] Developers confuse the Java agent with the Azure managed agent → Use separate definitions and state that both are needed when Azure provides the collector path.
+- [Risk] Azure managed OpenTelemetry behavior changes → Link to the Microsoft documentation and state the currently relevant injected variables and gRPC constraint rather than copying a full infrastructure template.
+- [Risk] Agent or Jaeger examples silently drift → Pin example versions and direct upgrades through the Java 11 regression test.
+- [Risk] `SPRING_PROFILES_ACTIVE` replaces application-specific profiles → Show either appending `observation` to the existing active profile list or using the application's established profile composition mechanism.
+- [Risk] Production always-on sampling creates excessive volume → Use always-on only for local evaluation and require an explicit production sampler and rate.
+- [Trade-off] A one-page runbook cannot cover every backend → Keep Azure managed-agent and direct-OTLP paths concrete while referring backend-specific destination setup to the platform owner.
+
+## Migration Plan
+
+No migration is required because tracing remains opt-in.
+The same application image can be rolled out first with the agent JAR present but unattached, then activated in a new Container App revision through runtime settings.
+Rollback removes the `observation` profile and `-javaagent` option or reverts to the prior revision.
+
+## Open Questions
+
+None.
diff --git a/openspec/changes/document-boot27-micrometer-tracing-operations/proposal.md b/openspec/changes/document-boot27-micrometer-tracing-operations/proposal.md
new file mode 100644
index 00000000000..bb0aa05a1e8
--- /dev/null
+++ b/openspec/changes/document-boot27-micrometer-tracing-operations/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+The Boot 2.7 observation substrate and initial semantic spans are implemented, but maintenance-branch developers do not yet have a concise runbook for trying them locally or deploying them to Azure Container Apps.
+The material will not be published as website documentation, so the team needs a repository-local one-page guide focused on the actual development and deployment workflow.
+
+## What Changes
+
+- Add a repository-local one-page runbook for downloading the validated OpenTelemetry Java agent, running Jaeger locally, starting an application, and inspecting traces.
+- Document the Docker image change needed to include the agent JAR at a stable path without baking environment-specific exporter configuration into the image.
+- Document Azure Container Apps runtime settings for attaching the Java agent, activating the `observation` profile, naming the service, selecting traces-only export, and configuring sampling.
+- Explain how the Azure Container Apps managed OpenTelemetry agent acts as the OTLP collector and injects its endpoint, protocol, and resource attributes when configured at the managed-environment level.
+- Describe the alternative of exporting directly to an external OTLP endpoint when the managed OpenTelemetry agent is not used.
+- Distinguish the in-process OpenTelemetry Java agent from the Azure Container Apps managed OpenTelemetry agent and preserve Java-agent ownership of the SDK and automatic instrumentation.
+- Include expected span names, privacy boundaries, verification checks, and concise troubleshooting guidance.
+
+## Capabilities
+
+### New Capabilities
+- `boot27-micrometer-tracing-operations`: A repository-local runbook for local evaluation, Docker image preparation, and Azure Container Apps runtime configuration of the Boot 2.7 tracing slice.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change adds a single developer-facing AsciiDoc file under `adoc/` and does not affect Antora navigation or published website content.
+It changes no production code, public API, dependency, or runtime default.
+The intended readers are maintenance-branch developers and the team responsible for the application's Docker image and Azure Container Apps environment.
diff --git a/openspec/changes/document-boot27-micrometer-tracing-operations/specs/boot27-micrometer-tracing-operations/spec.md b/openspec/changes/document-boot27-micrometer-tracing-operations/specs/boot27-micrometer-tracing-operations/spec.md
new file mode 100644
index 00000000000..ca5557fc33b
--- /dev/null
+++ b/openspec/changes/document-boot27-micrometer-tracing-operations/specs/boot27-micrometer-tracing-operations/spec.md
@@ -0,0 +1,100 @@
+## ADDED Requirements
+
+### Requirement: Provide a repository-local one-page runbook
+The repository SHALL contain a concise developer runbook under `adoc/` covering local evaluation, Docker image preparation, and Azure Container Apps operation.
+The runbook MUST remain independent of Antora and published website navigation.
+It SHALL identify Spring Boot 2.7.18, Java 11, and OpenTelemetry Java agent 1.31.0 as the validated baseline and SHALL direct version changes through compatibility verification.
+
+#### Scenario: Find maintenance-branch tracing instructions
+- **WHEN** a maintenance-branch developer needs to evaluate or deploy tracing
+- **THEN** a single repository-local document provides the local, image, and Azure Container Apps procedures without requiring website documentation
+
+#### Scenario: Evaluate an agent upgrade
+- **WHEN** the team wants to use an OpenTelemetry Java agent version other than 1.31.0
+- **THEN** the runbook directs the team to re-run Java 11 compatibility and semantic parentage verification before deployment
+
+### Requirement: Explain local evaluation with Jaeger
+The runbook SHALL provide copyable steps to obtain the validated Java agent, run a pinned Jaeger all-in-one container, start an application with the agent and `observation` profile, generate an HTTP-triggered action with JDBC work, and inspect the trace in Jaeger.
+The local example SHALL configure traces through OTLP HTTP/protobuf, disable metrics and logs exporters, use a local-only always-on sampling policy, and assign an explicit service name.
+
+#### Scenario: Try tracing on a laptop
+- **WHEN** a developer follows the local procedure on a machine with Java 11 and Docker
+- **THEN** Jaeger receives a trace from the application and exposes it through the local UI
+
+#### Scenario: Inspect semantic ancestry
+- **WHEN** the developer invokes an HTTP action that performs JDBC work
+- **THEN** the runbook enables the developer to find the ordered ancestry `HTTP → causeway.root.interaction → causeway.action.invocation → JDBC`, allowing additional agent-created intermediary spans
+
+### Requirement: Specify the Docker image change
+The runbook SHALL show how to add the validated Java agent JAR to a stable path in the application image.
+The image instructions MUST leave agent attachment, Spring-profile activation, OTLP destination, service name, credentials, and sampling as runtime configuration.
+The runbook SHALL state that the application container requires no additional inbound port for OTLP trace export.
+
+#### Scenario: Build one image for multiple environments
+- **WHEN** the team builds the application image with the Java agent JAR included but no environment-specific telemetry settings baked in
+- **THEN** the same image can run with tracing disabled locally or be activated by Azure Container Apps runtime configuration
+
+#### Scenario: Roll back tracing
+- **WHEN** operators remove the `-javaagent` option and `observation` profile or revert to an earlier Container App revision
+- **THEN** the application runs without Causeway semantic tracing and requires no application code change
+
+### Requirement: Document Azure Container Apps runtime configuration
+The runbook SHALL separate settings applied to the Container App revision from settings applied to the Azure Container Apps managed environment.
+The Container App settings SHALL cover `JAVA_TOOL_OPTIONS`, inclusion of the `observation` Spring profile, `OTEL_SERVICE_NAME`, traces exporter selection, disabling metrics and logs export for this slice, and an explicit production sampling policy.
+The runbook SHALL warn that changing Container App environment variables creates a new revision and that existing Spring profiles must be preserved when adding `observation`.
+
+#### Scenario: Activate an application revision
+- **WHEN** operators deploy an image containing the agent JAR and apply the documented Container App environment settings
+- **THEN** the JVM attaches the Java agent, Causeway semantic observation is active, the service is identifiable, and trace volume follows the configured production sampler
+
+#### Scenario: Preserve existing application profiles
+- **WHEN** the application already uses one or more active Spring profiles
+- **THEN** the runbook directs operators to add `observation` without replacing the existing profile set
+
+### Requirement: Explain the Azure managed-agent collector path
+The runbook SHALL distinguish the in-process OpenTelemetry Java agent from the Azure Container Apps managed OpenTelemetry agent.
+It SHALL explain that the Java agent instruments the JVM while the Azure managed agent receives and routes OTLP data at the managed-environment level.
+For the managed-agent path, the runbook SHALL describe destination and trace-routing configuration on the managed environment and SHALL identify the automatically injected `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`, and `OTEL_RESOURCE_ATTRIBUTES` values.
+It MUST warn against overriding those injected values unless intentionally bypassing the managed agent.
+
+#### Scenario: Export through the Azure managed agent
+- **WHEN** the managed Container Apps environment has OpenTelemetry trace routing configured to Application Insights or another supported destination
+- **THEN** the Java agent exports over the Azure-injected gRPC OTLP endpoint and the managed agent forwards the traces to that destination
+
+#### Scenario: Avoid confusing the two agents
+- **WHEN** the Azure managed OpenTelemetry agent is enabled
+- **THEN** the runbook states that the application image still requires the OpenTelemetry Java agent JAR for JVM instrumentation
+
+### Requirement: Support a direct external OTLP path
+The runbook SHALL describe direct export to an external OTLP collector when the Azure managed OpenTelemetry agent is not used.
+That path SHALL identify endpoint, protocol, and authentication configuration and SHALL direct sensitive values to Azure Container Apps secret references rather than the image or plain repository content.
+
+#### Scenario: Use an external collector
+- **WHEN** the application does not use the Azure managed OpenTelemetry agent
+- **THEN** the Container App revision supplies the external OTLP endpoint, supported protocol, and any required secret-backed authentication settings
+
+### Requirement: Preserve telemetry ownership and privacy boundaries
+The runbook SHALL state that the OpenTelemetry Java agent owns the SDK, automatic HTTP and JDBC instrumentation, sampling, and export.
+It MUST warn against adding an application-owned SDK, Spring Boot 4 OpenTelemetry starter, Micrometer OTLP registry, or duplicate in-process exporter.
+It SHALL document the `causeway.root.interaction` and `causeway.action.invocation` span names and the `causeway.action.id` and `causeway.execution.initiatedBy` attributes.
+It MUST state that Causeway semantic instrumentation does not capture action arguments, results, target instance identifiers, user names, tenancy tokens, or other instance-specific application data.
+
+#### Scenario: Prepare application dependencies
+- **WHEN** the team enables tracing through the documented Java-agent path
+- **THEN** it does not add another telemetry SDK or exporter to the application
+
+#### Scenario: Review emitted semantic data
+- **WHEN** the team reviews a Causeway action span
+- **THEN** the runbook identifies the bounded metadata that is emitted and the instance-specific values that are deliberately excluded
+
+### Requirement: Provide concise verification and troubleshooting
+The runbook SHALL provide checks for Java and agent compatibility, agent attachment, Spring profile activation, service naming, endpoint and protocol, exporter selection, sampling, collector reachability, absent spans, duplicate spans, and unexpected parentage.
+The checks SHALL cover both the Azure managed-agent path and direct external OTLP export.
+
+#### Scenario: Automatic spans exist but semantic spans are absent
+- **WHEN** HTTP or JDBC spans are exported but Causeway semantic spans are missing
+- **THEN** the runbook directs the developer to verify activation of the `observation` profile
+
+#### Scenario: No spans are exported in Azure
+- **WHEN** no application traces reach the configured destination
+- **THEN** the runbook directs the operator to verify Java-agent attachment, sampling, Azure-injected or explicitly configured OTLP settings, managed-environment trace routing, credentials, and destination reachability
diff --git a/openspec/changes/document-boot27-micrometer-tracing-operations/tasks.md b/openspec/changes/document-boot27-micrometer-tracing-operations/tasks.md
new file mode 100644
index 00000000000..0ab5751ab80
--- /dev/null
+++ b/openspec/changes/document-boot27-micrometer-tracing-operations/tasks.md
@@ -0,0 +1,31 @@
+## 1. Establish the Repository-Local Runbook
+
+- [ ] 1.1 Add `adoc/micrometer-tracing-operations.adoc` with the standard license header and a concise scope statement for maintenance-branch developers.
+- [ ] 1.2 Structure the one-page runbook around local laptop evaluation, Docker image changes, and Azure Container Apps runtime configuration without adding it to Antora navigation.
+- [ ] 1.3 Cross-check every version, profile, span name, attribute, and exporter setting against the BOM, production substrate, and Java 11 regression fixture.
+
+## 2. Document Local Laptop Evaluation
+
+- [ ] 2.1 Add commands to download or locate OpenTelemetry Java agent 1.31.0 and run a pinned Jaeger all-in-one container with OTLP HTTP and UI ports.
+- [ ] 2.2 Add a copyable Java 11 startup example using the `observation` profile, local service name, traces-only OTLP HTTP/protobuf export, and local always-on sampling.
+- [ ] 2.3 Explain how to generate an HTTP-triggered action with JDBC work and find the expected semantic ancestry in the Jaeger UI.
+
+## 3. Document the Docker Image Change
+
+- [ ] 3.1 Add a Dockerfile fragment that copies the validated Java agent JAR to `/opt/opentelemetry/opentelemetry-javaagent.jar`.
+- [ ] 3.2 State which settings remain runtime concerns, that no extra inbound application port is required, and why the agent should not be downloaded at replica startup.
+- [ ] 3.3 Document tracing activation and rollback using the same image without application code changes.
+
+## 4. Document Azure Container Apps Operation
+
+- [ ] 4.1 Add the Container App revision settings for `JAVA_TOOL_OPTIONS`, preserving existing Spring profiles while adding `observation`, service naming, traces-only export, and production sampling.
+- [ ] 4.2 Explain the separate roles of the in-process Java agent and Azure Container Apps managed OpenTelemetry agent.
+- [ ] 4.3 Document the managed-environment destination and trace-routing responsibility plus Azure's injected OTLP endpoint, gRPC protocol, and resource attributes.
+- [ ] 4.4 Document the direct external-OTLP alternative, including protocol, endpoint, authentication, secret references, and the creation of a new revision when environment variables change.
+
+## 5. Document Boundaries and Troubleshooting
+
+- [ ] 5.1 Document agent ownership of the SDK, instrumentation, sampling, and export, and warn against Boot 4 starters, application-owned SDKs, Micrometer OTLP registries, and duplicate exporters.
+- [ ] 5.2 Document stable semantic names and attributes, ordered parentage with possible intermediary spans, privacy exclusions, and the deliberately narrow initial scope.
+- [ ] 5.3 Add concise troubleshooting checks for local Jaeger, the Azure managed-agent path, and direct external OTLP export.
+- [ ] 5.4 Validate AsciiDoc formatting and external links, run strict OpenSpec validation, and confirm that no Antora navigation, production code, public API, dependency, or runtime default changed.