io7m | single-page | multi-page | epub | Looseleaf User Manual
5. Usage
Previous
Front Matter
Up
7. Base Endpoints
Next

# 6. Monitoring

- 6.1. Overview
- 6.2. Metrics
  - 6.2.1. Names
- 6.3. Logs
- 6.4. Traces
- 6.5. Grafana Dashboard

## 6.1. Overview

1
The looseleaf package is extensively instrumented with OpenTelemetry in order to allow for the database to be continually monitored. The package publishes metrics, logs, and traces, all of which can be independently enabled or disabled. Most installations will only want to enable metrics or logs in production; traces are more useful when trying to diagnose performance problems, or for doing actual development on the looseleaf package.

## 6.2. Metrics

## 6.2.1. Names

1
The package publishes the following metrics that can be used for monitoring:

### 6.2.1.2. Metrics

Name | Description
--- | ---
looseleaf_db_reads | A counter that is incremented every time a key is successfully read from the database.
looseleaf_db_writes | A counter that is incremented every time a key is successfully written in the database.
looseleaf_db_errors | A counter that is incremented every time an error occurs when trying to read or write the database. This can occur on database transaction conflicts.
looseleaf_auth_errors | A counter that is incremented every time a user fails to authenticate properly.
looseleaf_db_deletes | A counter that is incremented every time a key is successfully deleted from the database.
looseleaf_db_time | A gauge that is periodically updated with the time the most recent database access took in nanoseconds. This can give a general view of how well the database is performing.
looseleaf_db_keys | A gauge that is periodically updated with the approximate number of keys present in the database.
looseleaf_db_size | A gauge that is periodically updated with the approximate size of the database in bytes.
looseleaf_http_request_time | A gauge that is periodically updated with the duration of the most recently processed HTTP request. This is an important metric for showing the overall latency of the service.
looseleaf_http_error_400 | A counter that is incremented every time an HTTP request results in an HTTP response with a 4xx status code.
looseleaf_http_error_500 | A counter that is incremented every time an HTTP request results in an HTTP response with a 5xx status code.
looseleaf_http_request | A counter that is incremented every time an HTTP request is made. This is an important metric for showing the overall traffic level to the service.
looseleaf_up | A guage that provides a fixed 1 value whenever the service is up.

3
The package may produce other metrics, however these are undocumented and should not be relied upon.

## 6.3. Logs

1
The looseleaf package is conservative in the amount of logging output it produces by default. The package is written to publish only a specific set of log messages to telemetry logs in order to increase the signal-to-noise ratio. There are very few kinds of errors that can even occur; the database might fail on reading or writing, and users might fail to authenticate properly. The looseleaf package logs errors at ERROR severity with at least the following attributes:

### 6.3.2. Message Attributes

Name | Description
--- | ---
looseleaf.user | The user that triggered the error.
looseleaf.key | The database key associated with the error.
looseleaf.operation | The operation being performed, such as "read", "update", etc.
looseleaf.remoteAddress | The address of the client that triggered the error.

## 6.4. Traces

1
The looseleaf package publishes traces for all internal operations. No specific documentation is provided on the structures of the traces as they are effectively tied to the internal structure of the code and are subject to change.

### 6.4.2. Trace Display

## 6.5. Grafana Dashboard

1
The looseleaf package provides a basic Grafana dashboard. The dashboard can be imported from https://raw.githubusercontent.com/io7m/looseleaf/develop/com.io7m.looseleaf.grafana/src/main/resources/com/io7m/looseleaf/grafana/dashboard.json.

### 6.5.2. Dashboard

5. Usage
Previous
Front Matter
Up
7. Base Endpoints
Next
io7m | single-page | multi-page | epub | Looseleaf User Manual