From 2424ba3f1c3f25a1cecaaa831b655321e20e3db9 Mon Sep 17 00:00:00 2001
From: "David H. Lam" <david.lam@sap.com>
Date: Thu, 16 Jul 2026 16:37:49 +0200
Subject: [PATCH 1/2] docs: add dev trace output section to Java observability
 page

Document the built-in dev-mode trace tree that renders CAP service
dispatch hierarchy as indented timing trees in the console log.
Covers activation logic, configuration, example output, and
relationship to the OpenTelemetry Java Agent.
---
 java/operating-applications/observability.md | 63 ++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index fb4b6085c..eb1d3b554 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -609,6 +609,69 @@ class CatalogServiceHandler implements EventHandler {
 ```
 
 
+#### Dev Trace Output { #dev-trace-output }
+
+In non-production profiles, CAP Java automatically logs completed request traces as indented timing trees to the console. This gives immediate visibility into which services, handlers, and database queries contribute to request latency — without any external tooling or agent setup.
+
+::: tip
+This feature is auto-enabled in development and disabled when the OpenTelemetry Java Agent is detected or in production profiles. No dependencies or JVM flags are required.
+:::
+
+##### Example Output
+
+A request to `GET /odata/v4/CatalogService/Books` produces:
+
+```log
+elapsed times (trace 4a1f7b2c...):
+     0.00 →   26.34 =   26.34 ms  RequestContext 1  [tenant=t1]
+     0.12 →   25.89 =   25.77 ms    CatalogService (READ)  [entity=Books]
+     1.45 →   24.20 =   22.75 ms      PersistenceService (READ)
+     2.10 →   23.80 =   21.70 ms        CQN SELECT CatalogService.Books
+```
+
+Each line shows:
+
+| Column | Meaning |
+|--------|---------|
+| `0.00` | Start time relative to trace start (ms) |
+| `26.34` | End time relative to trace start (ms) |
+| `26.34 ms` | Duration of the span |
+| Indentation | Parent → child nesting |
+| Name | CAP service, event, or CQN operation |
+| `[tenant=...]` | Tenant context (if available) |
+| `[entity=...]` | Target entity (if available) |
+| `[ERROR]` | Appears on failed spans |
+
+##### Configuration
+
+The feature is controlled by `cds.telemetry.dev-output.enabled`:
+
+| Value | Behavior |
+|-------|----------|
+| _not set_ | Auto-enabled in non-production when no OTel agent is detected |
+| `true` | Enabled (unless OTel agent is present) |
+| `false` | Disabled |
+
+To suppress the trace output via log level instead:
+
+```properties
+logging.level.com.sap.cds.telemetry=WARN
+```
+
+##### Relationship to the OpenTelemetry Java Agent
+
+The dev trace output and the [OpenTelemetry Java Agent](#agent-extension) serve complementary purposes:
+
+| | Dev Trace Output | OpenTelemetry Java Agent |
+|---|---|---|
+| **Use case** | Local development | Production observability |
+| **Setup** | Zero config | Agent JAR + exporter config |
+| **Span level** | CAP services, handlers, CQN | JVM frameworks (Spring MVC, JDBC) |
+| **Output** | Console log | Jaeger, Dynatrace, Cloud Logging |
+
+When the OpenTelemetry Java Agent is detected at startup, the dev trace output automatically backs off to avoid conflicts.
+
+
 ### Dynatrace { #dynatrace }
 
 [Dynatrace](https://www.dynatrace.com/support/help) is a comprehensive platform that delivers analytics and automation based on monitoring events sent by the backend services.

From b7e2638f585bb98103e63c99629fa5defbd49cbd Mon Sep 17 00:00:00 2001
From: David H Lam <david.lam@sap.com>
Date: Fri, 17 Jul 2026 13:56:26 +0200
Subject: [PATCH 2/2] Update observability.md

Removed output explanation
---
 java/operating-applications/observability.md | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index 6380d6b30..596e6d02b 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -630,19 +630,6 @@ elapsed times (trace 4a1f7b2c...):
      2.10 →   23.80 =   21.70 ms        CQN SELECT CatalogService.Books
 ```
 
-Each line shows:
-
-| Column | Meaning |
-|--------|---------|
-| `0.00` | Start time relative to trace start (ms) |
-| `26.34` | End time relative to trace start (ms) |
-| `26.34 ms` | Duration of the span |
-| Indentation | Parent → child nesting |
-| Name | CAP service, event, or CQN operation |
-| `[tenant=...]` | Tenant context (if available) |
-| `[entity=...]` | Target entity (if available) |
-| `[ERROR]` | Appears on failed spans |
-
 ##### Configuration
 
 The feature is controlled by `cds.telemetry.dev-output.enabled`: