evitaDB's monitoring facilities are designed to help you monitor running evitaDB instances as well as to help you
optimise your application during development. All monitoring facilities are based on our operational experience and
development of e-commerce projects.
Work in progress
This article will contain description of Evita monitoring facilities - would it be directly Prometheus or OpenTelemetry.
There should be also information how to log slow queries or see other problems within application (logging).
The functionality is not finalized - see issue #18.
Logging
evitaDB uses the SLF4J logging facade for logging both application log messages and access log messages. By default
only application log messages are enabled, the access log messages must be explicitly enabled in configuration.
Access log
If the accessLog property is set to true in the configuration, the server will log
access log messages for all APIs using the
Slf4j logging facade. These messages are logged at the INFO level and contain the ACCESS_LOG
marker which you can use to separate standard messages from access log messages.
Access log messages can be further categorized using UNDERTOW_ACCESS_LOG and GRPC_ACCESS_LOG markers. This is because
evitaDB uses Undertow web server for REST and GraphQL APIs and separate web server
for gRPC. It might be sometimes useful to log these separately because even though they both
use the same log format, for example, gRPC doesn't support all properties as Undertow.
Server Logback utilities
evitaDB server comes ready with several custom utilities for easier configuration of the custom logged data.
Note: These utilities are only available in evitaDB server because the rest of the evitaDB codebase
doesn't rely on a concrete implementation of the Slf4j logging facade.
If the evitaDB is used as embedded instance, the following tools are not available, but can be used as reference to
custom implementation in chosen framework.
Log filters
The basic utilities are two Logback filters ready-to-use to easily separate access log messages
from app log messages.
There is io.evitadb.server.log.AccessLogFilter filter to only log access log messages.
This filter can be used as follows:
There is also io.evitadb.server.log.AppLogFilter filter to only log standard log messages.
This filter can be used as follows:
This filter exists because when you enable access logs the log messages with the ACCESS_LOG marker aren't filtered out
by default.
Tooling for log aggregators
If a log aggregator is used to consume evitaDB log messages, it is often useful to app log messages as one-line JSON objects.
Therefore, there is Logback layout ready-to-use to easily log app log messages as JSON objects.
This layout logs messages as JSON objects and makes sure that everything is properly escaped, even newline characters
in log messages (e.g. stack traces).
The layout is the io.evitadb.server.log.AppLogJsonLayout layout to log app log messages, and can be used as follows:
Client and request identification
In order to monitor which requests each client executes against evitaDB, each client and each request can be identified by
a unique identifier. In this way, evitaDB calls can be grouped by requests and clients. This may be useful, for example,
to see if a particular client is executing queries optimally and not creating unnecessary duplicate queries.
Both identifiers are provided by the client itself. The client identifier is expected to be a constant for a particular
client, e.g. Next.js application, and will group together all calls to a evitaDB from this client.
The request identifier is expected to be a UUID
but can be any string value, and will group together all evitaDB calls with this request identifier for a particular client.
The request definition (what a request identifier represents) is up to the client to decide, for example, a single request
for JavaScript client may group together all evitaDB calls for a single page render.
Configuration
This mechanism is not part of an evitaQL language. Check documentation for your specific client for more information.
Logging
These identifiers can be also used to group application log messages by clients and requests for easier debugging of
errors that happened during a specific request. This is done using MDC
support. evitaDB passes the client and request identifiers to the MDC context under clientId and requestId names.
The specific usage depends on the used implementation of the SLF4J logging facade. For example
in Logback this can be done using %X{clientId} and %X{requestId} patterns in the log pattern: