From 377f3ecf3b9541c3e69720bf506419d9b603d2e7 Mon Sep 17 00:00:00 2001
From: Olivier Maury <olivier.maury@inrae.fr>
Date: Thu, 14 Dec 2023 09:16:46 +0100
Subject: [PATCH 1/5] First usage description

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 554945a..7de2074 100644
--- a/README.md
+++ b/README.md
@@ -11,25 +11,83 @@ Suivi des Applications jaVa d'Agroclim
 ## Development
 
 SAVA is a Maven project, using Java 11.
-Simply use `mvn package`, then use the library in a webapp running on Tomcat.
+
+Maven modules are:
+- `sava-core contains` all the classes to use SAVA.
+- `sava-core-jakarta` contains all the classes to use SAVA on Jakarta (e.g.: Tomcat 10).
+- `sava-example` shows an use case of integration in a simple application, with only the servlet exposing demo values.
+
 The Java EE implementation is the origin.
 Jakarta library is converted from the Java EE library.
+To generate `sava-core-jakarta`, run `bin/update_sava-core-jakarta.sh`.
 
 ## Usage
 
-- sava-core contains all the classes to use SAVA.
-- sava-core-jakarta contains all the classes to use SAVA on Jakarta (e.g.: Tomcat 10).
-- sava-example shows an use case of integration in a simple application, with only the servlet exposing demo values.
+**1. Add SAVA to your project**
 
-To generate `sava-core-jakarta`, run `bin/update_sava-core-jakarta.sh`.
+If you use Java EE (<= Tomcat 9), add to your dependencies in `pom.xml`:
+```xml
+    <dependency>
+      <groupId>fr.inrae.agroclim</groupId>
+      <artifactId>sava-core</artifactId>
+      <version>${sava.version}</version>
+    </dependency>
+```
+
+If you use Jakarta (>= Tomcat 10), add to your dependencies in `pom.xml`:
+```xml
+    <dependency>
+      <groupId>fr.inrae.agroclim</groupId>
+      <artifactId>sava-core-jakarta</artifactId>
+      <version>${sava.version}</version>
+    </dependency>
+```
+
+**2. Extends [`MetricsBasicAuthServlet`](https://forgemia.inra.fr/agroclim/sava/-/blob/main/sava-core-jakarta/src/main/java/fr/agroclim/sava/core/MetricsBasicAuthServlet.java)**
+
+By default, histograms for all requests are created.
+
+**3. Example to add information about the application**
+
+**4. Example to add information about the PostgreSQL**
+
+**5. Configure Tomcat `context.xml`**
+
+Add key and password for HTTP Basic Authentication of MetricsBasicAuthServlet implementation.
+
+```xml
+    <Parameter name="sava.key" value="HldIAeGvVxgxFcBj8z2j" />
+    <Parameter name="sava.pass" value="AfEy82sBOD0yVvUeoMM6" />
+```
+
+With values generated by randomizer.
+Eg. for AgroClim:
+- [random_string.py](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.py?ref_type=heads) or 
+- [random_string.sh](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.sh?ref_type=heads)
+  ```sh
+  #!/bin/sh
+  LC_ALL=C tr -dc 'A-Za-z0-9!.?' </dev/urandom | head -c 20
+  echo
+  ```
+
+**6. Test from curl**
+
+The metrics are exposed by the `MetricsBasicAuthServlet` implementation, protected by HTTP Basic Authentication. So you need to set the HTTP header like this:
+
+```bash
+SAVA_KEY="HldIAeGvVxgxFcBj8z2j"
+SAVA_PASS="AfEy82sBOD0yVvUeoMM6"
+BASE64_AUTH=$(echo -n "$SAVA_KEY:$SAVA_PASS" | base64)
+curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH"
+```
 
 ## Authors
 
-See [`AUTHORS`](AUTHORS) file.
+See [`AUTHORS.md`](AUTHORS.md) file.
 
 ## License
 
 See [`LICENSE`](LICENSE) file.
 
 ## Project status
-Development in progress
\ No newline at end of file
+Development in progress
-- 
GitLab


From 5916ce2f4445a17f9288e1bbed54ed8750cf820b Mon Sep 17 00:00:00 2001
From: Olivier Maury <olivier.maury@inrae.fr>
Date: Thu, 14 Dec 2023 14:46:48 +0100
Subject: [PATCH 2/5] OpenTelemetry format

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 7de2074..204ac58 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,10 @@ The metrics are exposed by the `MetricsBasicAuthServlet` implementation, protect
 SAVA_KEY="HldIAeGvVxgxFcBj8z2j"
 SAVA_PASS="AfEy82sBOD0yVvUeoMM6"
 BASE64_AUTH=$(echo -n "$SAVA_KEY:$SAVA_PASS" | base64)
+# in Prometheus format
 curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH"
+# in OpenTelemetry format
+curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH" --header 'Accept: application/openmetrics-text; version=1.0.0; charset=utf-8'
 ```
 
 ## Authors
-- 
GitLab


From 8c8915e8d758a03fca7f50512c8efcdeae8644cf Mon Sep 17 00:00:00 2001
From: Olivier Maury <olivier.maury@inrae.fr>
Date: Thu, 14 Dec 2023 09:16:46 +0100
Subject: [PATCH 3/5] First usage description

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 554945a..7de2074 100644
--- a/README.md
+++ b/README.md
@@ -11,25 +11,83 @@ Suivi des Applications jaVa d'Agroclim
 ## Development
 
 SAVA is a Maven project, using Java 11.
-Simply use `mvn package`, then use the library in a webapp running on Tomcat.
+
+Maven modules are:
+- `sava-core contains` all the classes to use SAVA.
+- `sava-core-jakarta` contains all the classes to use SAVA on Jakarta (e.g.: Tomcat 10).
+- `sava-example` shows an use case of integration in a simple application, with only the servlet exposing demo values.
+
 The Java EE implementation is the origin.
 Jakarta library is converted from the Java EE library.
+To generate `sava-core-jakarta`, run `bin/update_sava-core-jakarta.sh`.
 
 ## Usage
 
-- sava-core contains all the classes to use SAVA.
-- sava-core-jakarta contains all the classes to use SAVA on Jakarta (e.g.: Tomcat 10).
-- sava-example shows an use case of integration in a simple application, with only the servlet exposing demo values.
+**1. Add SAVA to your project**
 
-To generate `sava-core-jakarta`, run `bin/update_sava-core-jakarta.sh`.
+If you use Java EE (<= Tomcat 9), add to your dependencies in `pom.xml`:
+```xml
+    <dependency>
+      <groupId>fr.inrae.agroclim</groupId>
+      <artifactId>sava-core</artifactId>
+      <version>${sava.version}</version>
+    </dependency>
+```
+
+If you use Jakarta (>= Tomcat 10), add to your dependencies in `pom.xml`:
+```xml
+    <dependency>
+      <groupId>fr.inrae.agroclim</groupId>
+      <artifactId>sava-core-jakarta</artifactId>
+      <version>${sava.version}</version>
+    </dependency>
+```
+
+**2. Extends [`MetricsBasicAuthServlet`](https://forgemia.inra.fr/agroclim/sava/-/blob/main/sava-core-jakarta/src/main/java/fr/agroclim/sava/core/MetricsBasicAuthServlet.java)**
+
+By default, histograms for all requests are created.
+
+**3. Example to add information about the application**
+
+**4. Example to add information about the PostgreSQL**
+
+**5. Configure Tomcat `context.xml`**
+
+Add key and password for HTTP Basic Authentication of MetricsBasicAuthServlet implementation.
+
+```xml
+    <Parameter name="sava.key" value="HldIAeGvVxgxFcBj8z2j" />
+    <Parameter name="sava.pass" value="AfEy82sBOD0yVvUeoMM6" />
+```
+
+With values generated by randomizer.
+Eg. for AgroClim:
+- [random_string.py](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.py?ref_type=heads) or 
+- [random_string.sh](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.sh?ref_type=heads)
+  ```sh
+  #!/bin/sh
+  LC_ALL=C tr -dc 'A-Za-z0-9!.?' </dev/urandom | head -c 20
+  echo
+  ```
+
+**6. Test from curl**
+
+The metrics are exposed by the `MetricsBasicAuthServlet` implementation, protected by HTTP Basic Authentication. So you need to set the HTTP header like this:
+
+```bash
+SAVA_KEY="HldIAeGvVxgxFcBj8z2j"
+SAVA_PASS="AfEy82sBOD0yVvUeoMM6"
+BASE64_AUTH=$(echo -n "$SAVA_KEY:$SAVA_PASS" | base64)
+curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH"
+```
 
 ## Authors
 
-See [`AUTHORS`](AUTHORS) file.
+See [`AUTHORS.md`](AUTHORS.md) file.
 
 ## License
 
 See [`LICENSE`](LICENSE) file.
 
 ## Project status
-Development in progress
\ No newline at end of file
+Development in progress
-- 
GitLab


From ab1e2d6db5dfb73dc942c565a312ff3c5f21aff3 Mon Sep 17 00:00:00 2001
From: Olivier Maury <olivier.maury@inrae.fr>
Date: Thu, 14 Dec 2023 14:46:48 +0100
Subject: [PATCH 4/5] OpenTelemetry format

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 7de2074..204ac58 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,10 @@ The metrics are exposed by the `MetricsBasicAuthServlet` implementation, protect
 SAVA_KEY="HldIAeGvVxgxFcBj8z2j"
 SAVA_PASS="AfEy82sBOD0yVvUeoMM6"
 BASE64_AUTH=$(echo -n "$SAVA_KEY:$SAVA_PASS" | base64)
+# in Prometheus format
 curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH"
+# in OpenTelemetry format
+curl http://localhost:8080/metrics --header "Authorization: Basic $BASE64_AUTH" --header 'Accept: application/openmetrics-text; version=1.0.0; charset=utf-8'
 ```
 
 ## Authors
-- 
GitLab


From 49ec52908e715fdcc4378d293666c1a34d7b4d13 Mon Sep 17 00:00:00 2001
From: Olivier Maury <Olivier.Maury@inrae.fr>
Date: Fri, 12 Jan 2024 15:43:57 +0100
Subject: [PATCH 5/5] Ajouter deux exemples. refs #9

---
 README.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 204ac58..b3c0a32 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,27 @@ By default, histograms for all requests are created.
 
 **3. Example to add information about the application**
 
-**4. Example to add information about the PostgreSQL**
+```
+SavaUtils.addCounter("app_version", "Version number of the application, "", "version");
+SavaUtils.incrementCounter("app_vendor", "1.0.0");
+```
+
+**4. Example to add information about PostgreSQL**
+
+```java
+final String schemaName = "public";
+SavaUtils.addGauge(
+    "schema_size",
+    "Database schema size, in bytes",
+    Map.of(
+        schemaName,
+        () -> dao.getSchemaSize(schemaName)
+    ),
+    1,
+    TimeUnit.HOURS,
+    "schema_name"
+);
+```
 
 **5. Configure Tomcat `context.xml`**
 
@@ -62,7 +82,7 @@ Add key and password for HTTP Basic Authentication of MetricsBasicAuthServlet im
 
 With values generated by randomizer.
 Eg. for AgroClim:
-- [random_string.py](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.py?ref_type=heads) or 
+- [random_string.py](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.py?ref_type=heads) or
 - [random_string.sh](https://forgemia.inra.fr/agroclim/common/devops/-/blob/main/scripts/random_string.sh?ref_type=heads)
   ```sh
   #!/bin/sh
-- 
GitLab