From 16416786ff12f9cc947ecc5f339de03f0b622884 Mon Sep 17 00:00:00 2001
From: "David H. Lam" <david.lam@sap.com>
Date: Wed, 25 Sep 2024 16:55:02 +0200
Subject: [PATCH 1/4] Added JDBC tracing section in Java Observability

---
 java/operating-applications/observability.md | 51 ++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index 790c32de8..88cc00f7f 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -218,6 +218,57 @@ In case you've configured `cf-java-logging-support` as described in [Logging Ser
 By default, the ID is accepted and forwarded via HTTP header `X-CorrelationID`. If you want to accept `X-Correlation-Id` header in incoming requests alternatively,
 follow the instructions given in the guide [Instrumenting Servlets](https://github.com/SAP/cf-java-logging-support/wiki/Instrumenting-Servlets#correlation-id).
 
+### JDBC Tracing in SAP Hana
+
+In order to activate JDBC tracing in the SAP Hana JDBC driver, you have to use the driver [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html). You can activate these without stopping and restarting the application using the [command line](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/e411647b03f1425fab1e33bb495c9c42.html).
+
+When running in the cloud it depends on the buildpacks used for the CAP Java application where the exact location of the Hana JDBC driver and the `java` executable are. The following assumes the usage of the [Cloud Native Buildpacks](https://pages.github.tools.sap/unified-runtime/docs/building-blocks/unified-build-and-deploy/buildpacks) as recommended by the [Unified Runtime](https://pages.github.tools.sap/unified-runtime/).
+
+#### On Kyma
+
+Step by step description on how to access a bash session in the application's container in order to use trace options in the Hana JDBC driver:
+
+1. Execute bash in the pod that runs the CAP Java application:
+
+   To identify the pod name, use
+   ```sh
+   kubectl get pods
+   ```
+   in the right namespace and
+   ```sh
+   kubectl exec -it pod/<POD_NAME> -- bash
+   ```
+   to acquire a bash session in the container.
+
+1. Locate java executable and JDBC driver:
+
+   By default `JAVA_HOME` is not set in the buildpack and contains minimal tooling, as it tries to minimize the container size. However, the default location of the `java` executable is `/layers/paketo-buildpacks_sap-machine/jre/bin`.
+   
+   For convenience, store the path into a variable, e.g. `JAVA_HOME`:
+   ```sh
+   export JAVA_HOME=/layers/paketo-buildpacks_sap-machine/jre/bin/
+   ```
+
+   The JDBC driver is usually located in `/workspace/BOOT-INF/lib`. Store it into another variable, e.g. `JDBC_DRIVER_PATH`:
+   ```sh
+   export JDBC_DRIVER_PATH=/workspace/BOOT-INF/lib
+   ```
+
+1. Use JDBC trace options in the driver, using the correct (versioned) name of the `ngdbc.jar`:
+   ```sh
+   $JAVA_HOME/java -jar $JDBC_DRIVER_PATH/ngdbc-<VERSION>.jar <option>
+   ```
+
+   [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html) lists the available options.
+
+   Before turning on tracing with `TRACE ON`, it is recommended to set `TRACE FILENAME` to a path that the current shell user has write access to, e.g.:
+   ```sh
+   $JAVA_HOME/java -jar $JDBC_DRIVER_PATH/ngdbc-<VERSION>.jar TRACE FILENAME ~/tmp/traces/jdbctrace
+   ```
+
+1. Read the trace file while the pod is still running, or use [`kubectl cp`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_cp/) to copy the file to your local machine.
+
+
 
 ## Monitoring { #monitoring }
 

From e3a66cce153b1ce40560d768e689d4e99c9fd1bf Mon Sep 17 00:00:00 2001
From: "David H. Lam" <david.lam@sap.com>
Date: Tue, 1 Oct 2024 16:55:30 +0200
Subject: [PATCH 2/4] Added tracing activation via datasource properties

---
 java/operating-applications/observability.md | 56 ++++++++++++++++++--
 1 file changed, 53 insertions(+), 3 deletions(-)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index 88cc00f7f..f71ba5e39 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -220,11 +220,61 @@ follow the instructions given in the guide [Instrumenting Servlets](https://gith
 
 ### JDBC Tracing in SAP Hana
 
-In order to activate JDBC tracing in the SAP Hana JDBC driver, you have to use the driver [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html). You can activate these without stopping and restarting the application using the [command line](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/e411647b03f1425fab1e33bb495c9c42.html).
+In order to activate JDBC tracing in the SAP Hana JDBC driver, you have to use the driver [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html). You can activate these by setting datasource properties in the `application.yaml` which requires you to stop and restart the application, or without stopping and restarting by using the [command line](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/e411647b03f1425fab1e33bb495c9c42.html).
 
-When running in the cloud it depends on the buildpacks used for the CAP Java application where the exact location of the Hana JDBC driver and the `java` executable are. The following assumes the usage of the [Cloud Native Buildpacks](https://pages.github.tools.sap/unified-runtime/docs/building-blocks/unified-build-and-deploy/buildpacks) as recommended by the [Unified Runtime](https://pages.github.tools.sap/unified-runtime/).
+#### Using datasource properties
 
-#### On Kyma
+In the `application.yaml` under `cds.dataSource.<service-binding-name>:` specify `hikari.data-source-properties.traceFile` and `hikari.data-source-properties.traceOptions`, e.g.
+
+::: code-group
+```yaml [srv/src/main/resources/application.yaml]
+cds:
+  dataSource:
+    service-manager: # name of service binding
+      hikari:
+        data-source-properties:
+          traceFile: "/home/user/jdbctraces/trace_.log" # use a path that is write accessible
+          traceOptions: "CONNECTIONS,API,PACKET"
+```
+:::
+
+::: tip
+Use a `_` at the end in the file name for the trace file for better readability, as the JDBC tracing process creates several files and appends random numeric values to the file names:
+
+```sh
+~/jdbctraces/ $ ls
+
+trace_10324282997834295561.log
+trace_107295864860396783.log
+trace_10832681394984179734.log
+trace_11222964343246588836.log
+trace_11899150308439828686.log
+```
+:::
+
+[Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html) lists available command line options. For the datasource property only use the option name, such as `CONNECTIONS`, `API` or `PACKET`. You can specify more than one option, separated by commas.
+
+This method of activating JDBC tracing requires restarting the application. For cloud deployments on Cloud Foundry this typically means redeploying via MTA, on Kyma this means rebuilding the application, recreating and publishing the container image to the container image registry and redeploying the application via Helm.
+
+Once the `application.yaml` of the deployed application contains both `hikari.data-source-properties.traceFile` and `hikari.data-source-properties.traceOptions`, their values can also be overwritten by setting the corresponding environment variables in the container.
+
+For example, to overwrite the tracefile path for the `application.yaml` you have to set the environment variable such as this with `SERVICE_MANAGER` being the name of the service binding:
+```yaml
+CDS_DATASOURCE_SERVICE_MANAGER_HIKARI_DATA_SOURCE_PROPERTIES_TRACEFILE: "/home/cnb/jdbctraces/sm/trace_.log"
+```
+To overwrite the tracing options respectively:
+```yaml
+CDS_DATASOURCE_SERVICE_MANAGER_HIKARI_DATA_SOURCE_PROPERTIES_TRACEOPTIONS: "DISTRIBUTIONS"
+```
+
+#### Using the command line
+
+Using the command line to activate JDBC tracing it is not required to restart the application.
+
+However, when running in the cloud it depends on the buildpacks used for the CAP Java application where the exact location of the Hana JDBC driver and the `java` executable are. The following assumes the usage of the [Cloud Native Buildpacks](https://pages.github.tools.sap/unified-runtime/docs/building-blocks/unified-build-and-deploy/buildpacks) as recommended by the [Unified Runtime](https://pages.github.tools.sap/unified-runtime/).
+
+
+##### On Kyma
 
 Step by step description on how to access a bash session in the application's container in order to use trace options in the Hana JDBC driver:
 

From 0ea4ff713c70d0d3ea0b41a631ed59f57455345e Mon Sep 17 00:00:00 2001
From: "David H. Lam" <david.lam@sap.com>
Date: Wed, 2 Oct 2024 10:08:30 +0200
Subject: [PATCH 3/4] Corrected statement about filenames of tracing files

---
 java/operating-applications/observability.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index f71ba5e39..a0694bfe0 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -239,7 +239,7 @@ cds:
 :::
 
 ::: tip
-Use a `_` at the end in the file name for the trace file for better readability, as the JDBC tracing process creates several files and appends random numeric values to the file names:
+Use a `_` at the end in the file name for the trace file for better readability, as the JDBC tracing process creates several files and appends an epoch timestamp to the file names:
 
 ```sh
 ~/jdbctraces/ $ ls

From 982f364e433385c7b2e86e41e0594cc01a3c636e Mon Sep 17 00:00:00 2001
From: Mahati Shankar <m.shankar@sap.com>
Date: Fri, 13 Dec 2024 14:43:02 +0100
Subject: [PATCH 4/4] cosmetics

---
 java/operating-applications/observability.md | 33 +++++++++-----------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/java/operating-applications/observability.md b/java/operating-applications/observability.md
index ad6ca28b3..b14bad84d 100644
--- a/java/operating-applications/observability.md
+++ b/java/operating-applications/observability.md
@@ -219,13 +219,12 @@ follow the instructions given in the guide [Instrumenting Servlets](https://gith
 
 ### JDBC Tracing in SAP Hana
 
-In order to activate JDBC tracing in the SAP Hana JDBC driver, you have to use the driver [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html). You can activate these by setting datasource properties in the `application.yaml` which requires you to stop and restart the application, or without stopping and restarting by using the [command line](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/e411647b03f1425fab1e33bb495c9c42.html).
+To activate JDBC tracing in the SAP Hana JDBC driver, you have to use the driver [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html). You can activate it either by setting datasource properties in the `application.yaml` and restarting the application, or, while the application is running by using the [command line](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/e411647b03f1425fab1e33bb495c9c42.html).
 
 #### Using datasource properties
 
-In the `application.yaml` under `cds.dataSource.<service-binding-name>:` specify `hikari.data-source-properties.traceFile` and `hikari.data-source-properties.traceOptions`, e.g.
+In the `application.yaml` under `cds.dataSource.<service-binding-name>:` specify `hikari.data-source-properties.traceFile` and `hikari.data-source-properties.traceOptions`:
 
-::: code-group
 ```yaml [srv/src/main/resources/application.yaml]
 cds:
   dataSource:
@@ -235,10 +234,9 @@ cds:
           traceFile: "/home/user/jdbctraces/trace_.log" # use a path that is write accessible
           traceOptions: "CONNECTIONS,API,PACKET"
 ```
-:::
 
 ::: tip
-Use a `_` at the end in the file name for the trace file for better readability, as the JDBC tracing process creates several files and appends an epoch timestamp to the file names:
+ Add an underscore at the end of the trace file's name. It helps redability by separating the string of numbers that the JDBC tracing process appends for the epoch timestamp.
 
 ```sh
 ~/jdbctraces/ $ ls
@@ -246,14 +244,13 @@ Use a `_` at the end in the file name for the trace file for better readability,
 trace_10324282997834295561.log
 trace_107295864860396783.log
 trace_10832681394984179734.log
-trace_11222964343246588836.log
-trace_11899150308439828686.log
+...
 ```
 :::
 
-[Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html) lists available command line options. For the datasource property only use the option name, such as `CONNECTIONS`, `API` or `PACKET`. You can specify more than one option, separated by commas.
+[Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html) lists the available command line options. For the datasource property, you only need the option's name, such as `CONNECTIONS`, `API`, or `PACKET`. You can specify more than one option, separated by commas.
 
-This method of activating JDBC tracing requires restarting the application. For cloud deployments on Cloud Foundry this typically means redeploying via MTA, on Kyma this means rebuilding the application, recreating and publishing the container image to the container image registry and redeploying the application via Helm.
+This method of activating JDBC tracing requires restarting the application. For cloud deployments on Cloud Foundry this typically means redeploying via MTA, on Kyma this means rebuilding the application, re-creating, and publishing the container image to the container image registry and redeploying the application via Helm.
 
 Once the `application.yaml` of the deployed application contains both `hikari.data-source-properties.traceFile` and `hikari.data-source-properties.traceOptions`, their values can also be overwritten by setting the corresponding environment variables in the container.
 
@@ -268,22 +265,22 @@ CDS_DATASOURCE_SERVICE_MANAGER_HIKARI_DATA_SOURCE_PROPERTIES_TRACEOPTIONS: "DIST
 
 #### Using the command line
 
-Using the command line to activate JDBC tracing it is not required to restart the application.
+Using the command line to activate JDBC tracing doesn't require an application restart.
 
 However, when running in the cloud it depends on the buildpacks used for the CAP Java application where the exact location of the Hana JDBC driver and the `java` executable are. The following assumes the usage of the [Cloud Native Buildpacks](https://pages.github.tools.sap/unified-runtime/docs/building-blocks/unified-build-and-deploy/buildpacks) as recommended by the [Unified Runtime](https://pages.github.tools.sap/unified-runtime/).
 
 
 ##### On Kyma
 
-Step by step description on how to access a bash session in the application's container in order to use trace options in the Hana JDBC driver:
+Step-by-step description on how to access a bash session in the application's container to use trace options in the Hana JDBC driver:
 
-1. Execute bash in the pod that runs the CAP Java application:
+1. Run bash in the pod that runs the CAP Java application:
 
-   To identify the pod name, use
+   First, identify the pod name:
    ```sh
    kubectl get pods
    ```
-   in the right namespace and
+   in the right namespace run:
    ```sh
    kubectl exec -it pod/<POD_NAME> -- bash
    ```
@@ -291,14 +288,14 @@ Step by step description on how to access a bash session in the application's co
 
 1. Locate java executable and JDBC driver:
 
-   By default `JAVA_HOME` is not set in the buildpack and contains minimal tooling, as it tries to minimize the container size. However, the default location of the `java` executable is `/layers/paketo-buildpacks_sap-machine/jre/bin`.
+   By default `JAVA_HOME` isn't set in the buildpack and contains minimal tooling, as it tries to minimize the container size. However, the default location of the `java` executable is `/layers/paketo-buildpacks_sap-machine/jre/bin`.
    
-   For convenience, store the path into a variable, e.g. `JAVA_HOME`:
+   For convenience, store the path into a variable, for example, `JAVA_HOME`:
    ```sh
    export JAVA_HOME=/layers/paketo-buildpacks_sap-machine/jre/bin/
    ```
 
-   The JDBC driver is usually located in `/workspace/BOOT-INF/lib`. Store it into another variable, e.g. `JDBC_DRIVER_PATH`:
+   The JDBC driver is usually located in `/workspace/BOOT-INF/lib`. Store it into another variable, for example, `JDBC_DRIVER_PATH`:
    ```sh
    export JDBC_DRIVER_PATH=/workspace/BOOT-INF/lib
    ```
@@ -310,7 +307,7 @@ Step by step description on how to access a bash session in the application's co
 
    [Trace Options](https://help.sap.com/docs/SAP_HANA_CLIENT/f1b440ded6144a54ada97ff95dac7adf/4033f8e603504c0faf305ab77627af03.html) lists the available options.
 
-   Before turning on tracing with `TRACE ON`, it is recommended to set `TRACE FILENAME` to a path that the current shell user has write access to, e.g.:
+   Before turning on tracing with `TRACE ON`, it's recommended to set `TRACE FILENAME` to a path that the current shell user has write access to, for example:
    ```sh
    $JAVA_HOME/java -jar $JDBC_DRIVER_PATH/ngdbc-<VERSION>.jar TRACE FILENAME ~/tmp/traces/jdbctrace
    ```