Monitoring — overview

Visibility into a running NomaUBL install splits across several surfaces — three pages of the web UI, the log file on the host and two HTTP endpoints. This page is the map: which surface answers which operational question, when to look where, what's missing and where to wire external monitoring.

Surface	What it answers	Where
IT dashboard	Live KPIs — invoices processed today, in flight, failed; per-PA submission state; scheduler activity; configuration check.	Navigation → IT dashboard — see Tech dashboard.
Diagnostics	What failed and what the server logged, in four views: integration errors, processing log (every step of every file, with timings), failures (every failure in one list, unresolved by default), server log (the log file, filtered by level and module).	Navigation → Diagnostics — see Diagnostics.
Scheduled jobs	Every background job with its state, last run, duration, result and next run, and the history of its runs.	Sync → Scheduled jobs — see Scheduled jobs.
Service log file	The JVM's stderr / stdout — startup, configuration loading, scheduler ticks, database errors.	<APP_HOME>/nomaubl-<env>.log on the host.
HTTP endpoints	Machine-readable build info + license state.	/api/build-info and /api/license on the running service.

The web UI pages are the operator's view; the log file + endpoints are the infrastructure's view (load balancers, external monitoring, CI smoke tests).

---

When to look where

Situation	Surface
"Did today's batch run successfully?"	IT dashboard — invoices processed today panel.
"What failed and is still open?"	Diagnostics → Failures — unresolved only, newest first.
"What's the status of invoice #12345?"	Diagnostics → Processing log — search by document number.
"Why is invoice #12345 stuck?"	Diagnostics → Processing log — drill into the step trace.
"Did the nightly job run?"	Scheduled jobs — last run, result and run history.
"Why isn't the scheduler firing?"	Scheduled jobs for the state of each job, then the Server log view or the log file.
"Did the JVM crash?"	Service log file + ./nomaubl.sh status (Linux / macOS) or nomaubl.cmd status (Windows).
"Is the database reachable?"	Service log file — look for Connected to db-nomaubl on start.
"Is the PA reachable?"	Diagnostics → Server log (module PA) or the log file — look for pa-default API call lines.
"Is the license still valid?"	curl /api/license — returns valid / expired / restricted.
"What version is running?"	curl /api/build-info — returns version + build timestamp.
"Did a process restart happen overnight?"	./nomaubl.sh status / nomaubl.cmd status shows current PID; the log file shows the startup banner.

The questions on invoices, failures and jobs go through the UI; everything below goes through the CLI or a curl. The next page (Service and logs) walks the CLI side in detail.

---

Permissions

Visibility:

Surface	Permission
IT dashboard	Available to every signed-in user — but the KPIs themselves respect each user's data filter (e.g. per-company scope).
Diagnostics	Each view is granted on its own on the Roles page — Integration errors, Processing log, Failures, Server log.
Scheduled jobs	The Scheduled Jobs page grant; running, pausing or saving a job also requires the Run batch jobs action.
Service log file / endpoints	Available to anyone with SSH / RDP / HTTP access to the host. Restrict via the firewall and the reverse proxy — /api/build-info and /api/license are unauthenticated.

The two unauthenticated HTTP endpoints don't leak secrets (no passwords, no tokens, only build metadata + license summary), but they do leak the version of NomaUBL you run. For public-facing installs, gate them behind the reverse proxy or your VPN if that matters.

---

At a glance

---

What NomaUBL does NOT expose

Knowing the gaps prevents misplaced searches:

Missing	Where to get it instead
Prometheus /metrics	Not built in. Scrape the host with node_exporter; mine the log file for application-level counters; or build a small JMX exporter on top of the JVM.
OpenTelemetry traces	Not built in. The processing pipeline emits structured per-step logs — pipe those into a log-based tracing system if you need waterfall views.
Per-request latency histograms	The IT dashboard surfaces aggregates; for percentiles + request-by-request, wire an APM in front of the reverse proxy.
Heap / GC stats	Standard JVM JMX — connect VisualVM or JConsole over JMX, or expose JMX via a JMX-to-Prometheus exporter.
Live database connection-pool metrics	NomaUBL uses a simple per-call connection model, not a pooled one. Connection count is a function of in-flight requests — observable through Oracle's V$SESSION or PostgreSQL's pg_stat_activity.

Most external-monitoring needs reduce to: scrape the host with the standard tools, mine the log file, wire an APM upstream. The framework itself stays focused on the in-app surfaces.

---

Day-zero monitoring setup

A minimal "production-ready" monitoring posture for a single host install:

1. Auto-start via systemd with Restart=on-failure — see Service and systemd.
2. Log rotation — built into the server: above the Log size cap (100 MB by default) the log is copied to .1 and truncated, five copies being kept (global → Logs). Logrotate is only needed when the server runs under another launcher.
3. Liveness probe from your load balancer / uptime monitor hitting /api/build-info every 30 seconds.
4. License alert — a small script that hits /api/license daily and pages if valid: false.
5. Log forwarding — pipe nomaubl-<env>.log to your central log store (Loki, ELK, Datadog Logs). The framework writes plain stderr/stdout — every line-based log shipper picks it up.
6. Database monitoring — the engine's own tooling (Oracle: V$SESSION, AWR; PostgreSQL: pg_stat_activity, pg_stat_statements; or whatever dashboards your DBA already runs).

Items 3, 4 and 5 are the cheap wins that catch 80% of production incidents.

---

What you actually do — quick map

Goal	Read
Walk the IT dashboard cards.	Application → IT dashboard.
Investigate a stuck or failed invoice.	Diagnostics → Processing log.
Use the wrapper's status + log tailing for incidents (Linux or Windows).	Service and logs.
Wire external monitoring (LB probes, alerting, log forwarding).	Service and logs.

---

What's next

• Service and logs — the CLI + endpoints layer in detail.
• Application → IT dashboard — the in-app live view.
• Diagnostics → Processing log — per-document trace.