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:

    <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:

    <dependency>
      <groupId>fr.inrae.agroclim</groupId>
      <artifactId>sava-core-jakarta</artifactId>
      <version>${sava.version}</version>
    </dependency>

2. Extends MetricsBasicAuthServlet

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

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.

    <Parameter name="sava.key" value="HldIAeGvVxgxFcBj8z2j" />
    <Parameter name="sava.pass" value="AfEy82sBOD0yVvUeoMM6" />

With values generated by randomizer. Eg. for AgroClim:

• random_string.py or
• random_string.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:

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 file.

License

See LICENSE file.

Project status

Stable