From 8c250fc7f6c85db1efaf4a42c28461df796e3c13 Mon Sep 17 00:00:00 2001
From: Olivier Maury <olivier.maury@inrae.fr>
Date: Tue, 25 Jun 2024 11:06:33 +0200
Subject: [PATCH] =?UTF-8?q?Resolve=20"D=C3=A9crire=20l'utilisation=20dans?=
 =?UTF-8?q?=20README"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 88 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 554945a..b3c0a32 100644
--- a/README.md
+++ b/README.md
@@ -11,25 +11,106 @@ 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**
+
+```
+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`**
+
+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)
+# 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
 
-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