README.md

# SAVA

Suivi des Applications jaVa d'Agroclim

## Goals

- Facilitate export and exposure of internal data on AgroClim's Java applications.
- Use Prometheus format to expose metrics.
- Add the library to a Java application running on Tomcat.

## Development

SAVA is a Maven project, using Java 11.

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

**1. Add SAVA to your project**

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.1");
```

**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.md`](AUTHORS.md) file.

## License

See [`LICENSE`](LICENSE) file.

## Project status

Stable