Skip to content

Added dev trace output section to Java observability page #2753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davidhunglam wants to merge 3 commits into
base: main
Choose a base branch
from
+63 −0
Open

Added dev trace output section to Java observability page #2753

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2424ba3
docs: add dev trace output section to Java observability page
davidhunglam Jul 16, 2026
1aab2fb
Merge branch 'main' into docs/java-dev-trace-output
davidhunglam Jul 16, 2026
fc080f5
Merge branch 'main' into docs/java-dev-trace-output
davidhunglam Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions java/operating-applications/observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -610,6 +610,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:

@StefanHenke StefanHenke Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the log output is pretty much self explaining so that we could remove the following table.


| 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.
Expand Down
Loading