Fineract monitoring with Prometheus and OpenTelemetry

How to monitor Apache Fineract in production

A running Fineract deployment still has to answer two operational questions: is the API healthy, and will Close of Business finish before the next business day opens? Fineract is a headless Spring application, so monitoring is configured on the Fineract side while the backend and dashboards are chosen separately. The application exposes actuator health, info and prometheus endpoints. Prometheus can scrape the metrics endpoint, or Fineract metrics can be exported over OTLP through an OpenTelemetry Collector. On AWS, CloudWatch is a further option. Confirm which endpoints your release exposes by default and which of them your network policy allows you to reach.

Plan this design before go-live rather than after the first incident. The Fineract README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Your team or implementation partner therefore owns the monitoring design. Decide on the signals that must exist on day one: API latency and error rates, health of each instance type (read, write and batch), JVM and database connection pool metrics, and the duration of the Close of Business job. Each signal needs an owner and a documented response, so every alert leads to a specific action.

Before you build dashboards, ask your Fineract team or vendor to confirm three things: which endpoints are exposed and how they are secured, which instance runs the Close of Business job in your topology, and how long that job has taken on data volumes close to your production size during testing. Actuator endpoints should not be reachable from the public internet. Treat the monitoring stack as production infrastructure with its own access control, retention and backup, because a silent monitoring failure can look exactly like a healthy system.

What you need before enabling monitoring

Monitoring a Fineract deployment depends on decisions made before any dashboard exists: which Fineract release and database you run, which metrics backend receives the data, how the scraper or collector reaches every instance, and who acts on an alert. The cards below cover those prerequisites in the order you are likely to settle them.

Fineract 1.x release and PostgreSQL

Start by confirming the exact Fineract 1.x release and database you run, because endpoint paths, exposed actuator settings and metric names are tied to the version. Fineract 1.15.0 is the current stable release, and the project recommends PostgreSQL, with MariaDB and MySQL deprecated under FSIP-9. Record the database metrics source too, since slow queries often show up first as API latency. Confirm the exposure and authentication settings for your version before you write any scrape configuration.

Metrics backend choice

Decide where metrics and traces land before you enable export. Prometheus pulls metrics from HTTP endpoints and stores them locally, and its local storage is not clustered or replicated, so long retention or high availability needs a planned remote store. An OpenTelemetry Collector can receive OTLP from Fineract and forward to a backend you choose. Write down the owner, storage size and retention for whichever backend you pick.

Network paths to each instance

Map a network path from the Prometheus server or Collector to every Fineract instance, not only the public entry point. Fineract runs read, write and batch instances, and each one needs its own scrape target so that batch behavior and Close of Business job timing stay visible. Check firewall rules, Kubernetes network policies and service discovery labels that identify the instance type. Keep the metrics port reachable only from the monitoring network.

TLS certificates for HTTPS

Fineract documentation strongly encourages HTTPS only and configures SSL through environment variables such as FINERACT_SERVER_SSL_ENABLED. Decide whether Prometheus or the Collector will trust your internal certificate authority, how certificates are renewed, and where the private key is stored. An expired certificate will stop scrapes silently unless you alert on scrape failures. Confirm the exact SSL settings for your release before you configure scrape TLS.

Access to read, write and batch instances

Make sure your team can reach the logs, configuration and deployment settings of each instance type. The write instance runs Liquibase migrations, the batch instance runs scheduled jobs such as Close of Business, and read instances serve reporting and read traffic on replicas. Without access to all three, an alert on latency may point at the wrong tier. Ask your platform team to confirm which instance runs which job and how instance type is set through environment variables.

Alert recipients and authentication

Name the people or on-call rota who receive each alert before rules are written, and separate platform alerts from banking operations alerts. Confirm how the metrics endpoint is authenticated in your version, since basic authentication and OAuth2 settings affect whether Prometheus can scrape without stored credentials. Store any scrape credentials in your secrets manager and rotate them. Agree in writing who responds to a missed Close of Business job and within what window.

Configuring health, metrics and export in order

This sequence turns a running Fineract deployment into one that reports its health and performance. Each layer is verified before the next is added, so a failed check points to a single component. The result is endpoints scraped by Prometheus and, where chosen, telemetry exported through OpenTelemetry or CloudWatch.

Enable the health and info endpoints
The platform team enables the actuator health and info endpoints on every read, write and batch instance, using the property names listed in the Fineract documentation for the version in use. Health comes first because load balancers and orchestrators depend on it, and the batch instance needs the same check as the others. Done when a request to the health endpoint on each instance returns an UP status and the info endpoint returns build details that match the deployed release.
Expose the Prometheus endpoint securely
Next, the team enables the prometheus endpoint on the same instances and restricts who can read it. Metrics can reveal internal hostnames, query patterns and job timings, so limit access to the network path used by the Prometheus servers and review the Prometheus security model before widening access. Done when a request from a scraper host returns plain-text metrics, and the metric names are confirmed against the version in use, and a request from outside that network is refused.
Scrape each instance type separately
Add one scrape job per instance type in the Prometheus configuration, with a label that marks each target as read, write or batch. Separate labels let latency panels compare read replicas with the write path and keep batch job load out of API charts. Give Prometheus every target directly, because its local storage is single node and must be managed like any other database. Done when the Targets page shows every instance as up and a query on the label returns one series per instance.
Export traces and metrics through OTLP
Where the team wants OTLP export, deploy an OpenTelemetry Collector as an agent beside Fineract or as a gateway for several instances, then enable Fineract's OTLP export using the property names in its documentation. Build a Collector pipeline with an OTLP receiver and an exporter to the chosen backend, and decide whether the receiver needs an authenticator extension. Review the Collector configuration best practices before exposing the receiver beyond the host. Done when Collector logs show received telemetry and the backend displays a trace from a test API call.
Route metrics to CloudWatch on AWS
This step applies only if CloudWatch is part of the design. On AWS, configure the Fineract metrics registry for CloudWatch as the version's documentation describes, setting the namespace and region in the same place. Grant the task or node role only the metric publishing permissions it needs, and avoid storing long-lived keys in configuration files. Confirm which metrics reach CloudWatch for each instance type, since read and batch instances may need different settings. Done when metrics from each instance appear in the chosen namespace with a dimension that identifies the instance type.
Verify the full path with a test call
Send a known test call through the API, such as one read and one write, and confirm its effect appears in each path the team enabled: the Prometheus request rate, the OTLP trace or the CloudWatch metric. Record the observed values as a baseline before any alert thresholds are set, so the first thresholds reflect how this deployment behaves. Done when the same request is visible in every enabled backend and the baseline is saved with the configuration version.

Choosing between Prometheus, OTLP and CloudWatch

Prometheus collects metrics by pulling them over HTTP from targets found through service discovery or static configuration. For a Fineract deployment, that means the platform team exposes the actuator prometheus endpoint and Prometheus scrapes it on a schedule. Storage is local to the Prometheus server. The project's storage documentation says local storage is not clustered or replicated and should be managed like any other single-node database, and default retention is 15 days. Keeping metrics longer means configuring remote write to an external long-term store, which becomes a second system to operate.

Pull model: Prometheus must be able to reach each Fineract instance on its metrics port, so network paths and scrape credentials are part of the design.
Local storage: Plan disk, retention by time or size, and a backup or replacement strategy for the Prometheus server itself.
Remote write: Choose an external long-term store if audit or capacity reviews need history beyond the local window.
Alerting: Alertmanager handles grouping, inhibition and silences, and should be clustered for high availability with Prometheus pointed at every instance.
Precision: The Prometheus docs say it values reliability over precision and is not suited to per-request billing, which fits latency dashboards but not billing-grade counts.

Confirm with your platform team whether they already run Prometheus, who is on call for it, and where the metrics are allowed to be stored.

Dashboards and alerts for API latency and Close of Business

Watch three signal groups: REST API request latency and error rates, JVM and database connection health, and the duration and status of the Close of Business Day Spring Batch job. The COB job is the one that matters most to a bank's operating day. The Fineract README says it can run for several hours on deployments with millions of accounts, so a dashboard that only shows API latency will miss the failure that delays posting. Build a panel for the job's start time, elapsed time, and final status, and alert when it has not finished by the time operations expects. Confirm the exact metric names your Fineract build exposes on the prometheus endpoint before writing any query, because they vary with the actuator and Micrometer configuration in your release.

Set every threshold from a measured baseline in your own environment. Collect at least several weeks of latency percentiles, error rates, connection pool usage, and COB durations under normal month-end and batch load, then set alerts above that observed range. A fixed number copied from another deployment will either page constantly or stay silent during a real degradation. Prometheus values reliability over precision, so treat short spikes as signals to correlate, not as proof of loss. Use for durations in alert rules so a single scrape does not page the on-call team, and record the baseline and the date it was measured alongside each rule so that the next review has a reference point.

Route alerts through Alertmanager, which groups related alerts, applies inhibition, and supports silences for planned maintenance such as a Fineract upgrade or a database failover. Group alerts by environment and tenant so that one incident produces one notification. Run Alertmanager as a cluster using its --cluster flags for high availability, and configure every Prometheus server to send alerts to each Alertmanager instance rather than through a load balancer. Confirm the on-call routing, escalation path, and silence approval process with your operations team before go-live, because these decisions determine whether a missed COB reaches a person within the time your operating procedures require.

Mapping Fineract signals to dashboards and alerts

This table maps each Fineract signal to the endpoint or metric that reports it, the instance type it comes from, the dashboard panel that shows it and the team that should act on its alert. Confirm every metric and endpoint name against your running Fineract version and exporter before you write alert rules, because names can change between releases. Agree the alert owners with your operations and on-call teams before go-live.

Signal	Source endpoint or metric	Instance type and dashboard panel	Alert owner
Health status	Actuator health endpoint, polled for each instance	Write, batch and read instances; panel shows up or down per instance	Platform on-call
API latency	Prometheus endpoint request timing for REST calls, confirm the metric name	Read and write instances; panel shows latency percentiles by endpoint group	Platform team with the application owner
Error rate	Prometheus endpoint HTTP status counts, confirm the labels	All instances; panel shows the share of server errors by instance type	Platform on-call with the application owner
COB job duration	Batch job timing exposed by the batch instance, confirm in logs or metrics	Batch instance; panel shows start, end and duration per business date	Operations lead for the financial institution
Batch instance backlog	Queue depth on the ActiveMQ or Kafka broker used for remote partitioning	Batch coordinator and worker nodes; panel shows pending partitions and consumer lag	Platform team with the messaging owner
Database connection use	Connection pool metrics on the Prometheus endpoint, plus PostgreSQL statistics from your exporter	Each write, batch and read instance and each replica; panel shows active against maximum connections	Database administrator
Build and version	Actuator info endpoint, confirm the fields your build returns	All instances; panel shows version annotations on each deployment	Release manager

Securing the monitoring surface

Metrics, health and trace data expose how Fineract runs, which is useful to attackers and sometimes sensitive in its own right. The cards below cover the four places monitoring traffic crosses a trust boundary: the Fineract endpoints, the scrape path, the collector, and the backends that store the data.

Restrict actuator endpoints to monitoring networks

The actuator health, info and prometheus endpoints should be reachable only from the monitoring subnet or the Prometheus or collector hosts that need them, not from the staff or client-facing network. Confirm in your Fineract configuration which actuator endpoints are exposed and whether the info endpoint returns build details you would rather keep private. Test the restriction from outside the allowed network, not only from inside it, and repeat the test after each release.

Require authentication on metrics scrapes

Where the metrics endpoint supports authentication, require it rather than relying on network location alone. Prometheus scrape configuration can carry credentials, so the secret belongs in a managed secret store and not in a plain configuration file in source control. Grafana's hardening guidance takes the same position for its own metrics endpoint, and the same reasoning applies to Fineract. Confirm the supported authentication method for each endpoint in your Fineract version before you write the scrape job.

Serve monitoring endpoints over HTTPS

Fineract's documentation strongly encourages HTTPS only and configures SSL through environment variables such as FINERACT_SERVER_SSL_ENABLED. Decide whether TLS terminates at Fineract or at a gateway, and document the certificate lifecycle for the scrape path as well as the API path. Check that Prometheus is configured to verify the certificate chain and that no scrape job silently falls back to plain HTTP. Use the same review for health endpoints that load balancers call.

Authenticate incoming collector connections

If OpenTelemetry data reaches a Collector gateway from services or agents over the network, the Collector's authenticator extensions can check incoming connections, for example with OIDC. Decide which identity provider issues the tokens and who may send telemetry into each pipeline. Without this check, anyone who can reach the receiver port can inject spans and metrics that appear to come from Fineract, which can mislead incident response and inflate dashboards.

Secure outgoing exporter credentials

When the Collector exports to a managed backend, the oauth2client extension can add credentials to outgoing requests, so the Collector does not need a static token in its configuration. Store the client secret in a secrets manager, rotate it on a schedule you set, and grant the client only the write scope it needs. Review the Collector's configuration best practices before you deploy, especially for how exporters handle TLS and credentials.

Plan access to stored telemetry

Metrics, traces and logs can contain customer identifiers, loan references or error messages that describe account state. Limit who can query Grafana and the data stores, and decide how that access maps to your staff roles. Grafana's SAML, team sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud, so confirm which identity options your edition supports before you design the access model. Ask the vendor for the current list of edition differences.

Common monitoring failures and fixes

This table lists the monitoring failures we see most often in Fineract deployments, with the likely cause and the fix for each. Read it as a checklist to run against your own setup before go-live and after every infrastructure change.

Failure	Likely cause	Fix
Scrape target shows down after a network change	A network policy, security group or firewall rule was tightened, so Prometheus can no longer reach the actuator port on the Fineract pods or hosts	Allow traffic from the Prometheus server or scrape pods to the management port, then confirm the target returns to up in the Prometheus targets view
Health endpoints open without authentication	Actuator endpoints were exposed on the same port and ingress as the public API with no access restriction	Serve management endpoints on a separate internal port or path, restrict them at the gateway or network layer, and expose only the endpoints you need
Metrics missing from read instances	Only the write instance was configured as a scrape target, so read instances on database replicas report nothing	Add every read instance and the batch instance as targets, and label them by instance type so dashboards can separate write, read and batch behavior
COB duration alerts fire during planned batch windows	The alert threshold was set for normal request traffic and does not account for the Close of Business job, which can run for hours on large deployments	Scope the COB alert to the batch window, suppress it with an Alertmanager silence during planned runs, and alert on a job that runs longer than its expected window
Prometheus history lost after a node failure	Local storage was treated as durable, but Prometheus local storage is not clustered or replicated and the default retention is 15 days	Back up the data directory on a schedule, run a second Prometheus for resilience, and send samples to external long-term storage through remote write where audit or trend history matters
Alerts duplicated or missing	Prometheus was pointed at a load balancer in front of Alertmanager, or only one Alertmanager instance was configured	Point Prometheus at every Alertmanager instance directly and run Alertmanager as a cluster using its cluster flags
Collector version drift across environments	Collector releases were upgraded in one environment and not others, so receivers, exporters or processors behave differently between test and production	Pin collector versions in each environment, track the release notes for every upgrade, and check component stability levels before enabling a new pipeline
Traces or metrics absent after an OTLP change	The exporter endpoint, authentication settings or TLS configuration changed on one side only	Verify the exporter endpoint and credentials with the collector logs, and confirm the Fineract OpenTelemetry settings match the collector receiver configuration

Questions teams ask before setting up Fineract monitoring

What drives the effort of monitoring a Fineract deployment?

The main drivers are the number of Fineract instances, whether you already run Prometheus or use CloudWatch, how many alerts you need and who acts on them, and how long you must keep metrics. A single write instance with one batch instance is a smaller job than a set of read instances behind a load balancer, each needing scrape targets and dashboards. Teams that already operate Prometheus or Grafana mostly add scrape configuration and alert rules, while teams starting from nothing also need storage, Alertmanager routing and access control. Retention matters because Prometheus keeps local data for 15 days by default, so longer history means remote storage. Ask for the instance inventory and existing tooling in writing before scoping.

Can our own team set up Fineract monitoring without outside help?

Yes, a team with Kubernetes or Linux operations experience and some Prometheus knowledge can expose the actuator endpoints, configure scraping and build basic dashboards. The harder parts are alert design for Close of Business batch runs, correct handling of Fineract tenants and instance types, and keeping the monitoring stack patched. The Prometheus storage documentation states that local storage is not clustered or replicated, so a single Prometheus server needs the same operational care as any single-node database. An outside partner is most useful when the team lacks time, needs the alert thresholds validated against a real load profile, or wants the work documented for an audit. Confirm your skills and staffing against the written scope before deciding.

How long does Fineract monitoring work usually take?

Duration depends on scope, so no fixed figure applies here. A small deployment that reuses an existing Prometheus or Grafana stack and needs only a few dashboards and alerts takes far less time than a multi-instance estate that adds OpenTelemetry pipelines, CloudWatch integration, and alerting tied to on-call rotations. Time also goes into establishing baselines, because alert thresholds for API latency and Close of Business duration should reflect your own traffic rather than defaults. Testing alert routes and running a full batch cycle under observation adds further time. Ask the partner for a phased plan with the work listed per phase and a written timeline before you commit.

What do we need to provide from the bank for this work?

The work needs access and people more than tools. Typically you provide read access to the Fineract instances and their actuator endpoints, network paths from the monitoring server, and credentials or service accounts the monitoring stack will use. You also need named on-call owners who will receive alerts and agree what a response looks like, and historic performance data or a period of normal operation to set baselines. Security teams will want to review how metrics endpoints are exposed, since the Grafana hardening guidance recommends requiring authentication for the metrics endpoint. Agree these responsibilities in the written scope so that no alert is created without an owner.

What does it cost to run Fineract monitoring each year?

Prometheus has no paid enterprise edition, since it is licensed under Apache-2.0, so ongoing costs come from infrastructure, storage and the people who run the stack. Infrastructure covers the servers or containers for Prometheus and Alertmanager, plus any remote long-term storage. Visualization may add Grafana, which is licensed under AGPLv3 for the core product and offers a Grafana Enterprise option, so licensing terms should be checked against your use. People costs are recurring: someone must patch components, review alerts, and respond to incidents. OpenTelemetry Collector releases are also frequent, so budget for upgrades. Request a quote that separates one-time setup from recurring infrastructure, support and upgrade effort.

Do alerts on API latency and Close of Business jobs need special design?

Yes. Latency and batch alerts should be built from your own baselines, grouped so one incident does not page several people, and routed to named owners through Alertmanager. The Fineract README notes that the Close of Business Day job can run for several hours on deployments with millions of accounts, so a fixed duration threshold may fire every night on a large estate and be ignored. Instead, alert on jobs that have not finished by the agreed window or on a sudden change from the normal duration. Alertmanager supports grouping, inhibition and silences, which helps prevent alert storms. Review every rule with the people who will receive it before go-live.

Should we use Prometheus, OpenTelemetry or CloudWatch for Fineract?

These tools overlap less than they seem. Prometheus collects and queries time-series metrics by pulling them from HTTP targets, OpenTelemetry provides a vendor-neutral way to generate and route traces, metrics and logs through the Collector, and CloudWatch is the metrics service for AWS-hosted resources. Many teams use Prometheus for application metrics and add OpenTelemetry when they need traces across services. If you run on AWS and already rely on CloudWatch alarms, keep those alarms and add Prometheus only where it closes a gap. The Prometheus documentation also notes that it favors reliability over precision, so it is not a fit where every event must be counted exactly, such as per-request billing. Decide the mix in the written design before building dashboards.

Keeping the monitoring stack current

The monitoring stack needs its own patch and upgrade plan, separate from the Fineract release calendar. Prometheus starts a new minor release cycle every 6 weeks, and a minor release generally stops receiving bug fixes after those 6 weeks, so a team that runs a minor version for long periods will fall behind quickly. For a longer support window, Prometheus long-term support lines receive bug fixes for one year. The current LTS line is 3.13, released July 1, 2026 and supported until July 31, 2027, while LTS 3.5 reached end of life on July 31, 2026. Decide early which line you will run, write down the date you will next review it, and confirm the support dates on the Prometheus release cycle page before you lock the version into your infrastructure code.

The OpenTelemetry Collector and Grafana need the same discipline. Collector releases are frequent: v0.163.0 was released on October 16, 2026, after v0.162.0 on September 29 and v0.161.0 on September 16, 2026. Pin the exact version in your deployment, check the component stability notes in each README before enabling a receiver or exporter, and verify the signed artifacts and SHA256 checksums that each release publishes. Grafana's upgrade guidance describes major releases once a year, minor releases every other month, and patch releases at least monthly, with each minor release supported for 9 months. Plan a recurring patch window for each component, and test every upgrade against a non-production copy of your dashboards and alert rules first.

How DeployOpen scopes and supports Fineract monitoring

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and monitoring for Apache Fineract is handled the same way. We start from the Fineract endpoints, the metrics your team needs for API latency and Close of Business jobs, and the telemetry backends you already run.

How we scope

The written scope names which Fineract instances, environments and cloud accounts are covered by monitoring.
Scope lists the endpoints in use, including health, info and prometheus, and which are exposed to which networks.
Scope records the metrics, dashboards and alert conditions to be delivered, agreed before work starts.
Engagements are fixed-scope, so deliverables and timelines are confirmed in writing before any build begins.

How we build

We configure Prometheus scrape targets or OTLP export for each Fineract instance type, read, write and batch.
We wire Alertmanager with alert rules for API latency and Close of Business job duration and failure.
We test each alert against staged failures and confirm dashboards show the data the runbooks depend on.
We check that metrics endpoints require authentication and are reachable only from approved monitoring networks.

How we hand over

Handover includes configuration files, dashboard definitions, alert rules and a description of each metric's meaning.
Runbooks explain what each Close of Business alert means and which Fineract logs and jobs to check first.
We document retention, storage sizing and the Prometheus and Grafana versions in use, so your team can upgrade them.
Your team walks through a live alert and a recovery procedure before the engagement closes.

How we support

Ongoing support, upgrades and continuous testing of the monitoring stack are available as a retainer.
A retainer can cover Prometheus, Alertmanager, Grafana and OpenTelemetry Collector version upgrades on a planned schedule.
Support can include tuning alert thresholds as Fineract volumes grow and Close of Business run times change.
Ask for a quote built from the written scope, which sets out the one-time build and any recurring support separately.

Apache Fineract monitoring with Prometheus and OpenTelemetry