Skip to main content

Monitoring — overview

Visibility into a running NomaUBL install splits across four surfaces — three in the web UI, one on the host. This page is the map: which surface answers which operational question, when to look where, what's missing and where to wire external monitoring.

SurfaceWhat it answersWhere
Tech DashboardLive KPIs — invoices processed today, in flight, failed; per-PA submission state; scheduler activity.Application → Tech Dashboard (existing page).
Processing LogPer-document trace — every step of every invoice, with the timing, the XSD/Schematron result, the PA call.Management → Processing Log (existing page).
Service log fileThe JVM's stderr / stdout — startup, configuration loading, scheduler ticks, database errors.<APP_HOME>/nomaubl-<env>.log on the host.
HTTP endpointsMachine-readable build info + license state./api/build-info and /api/license on the running service.

The two web UI surfaces 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​

SituationSurface
"Did today's batch run successfully?"Tech Dashboard — invoices processed today panel.
"What's the status of invoice #12345?"Processing Log — search by document number.
"Why is invoice #12345 stuck?"Processing Log — drill into the step trace.
"Why isn't the scheduler firing?"Service log file — look for scheduler tick lines.
"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?"Service 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 first two 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:

SurfacePermission
Tech DashboardAvailable to every signed-in user — but the KPIs themselves respect each user's data filter (e.g. per-company scope).
Processing LogRestricted to roles with the processing-log permission (typically operators + admins).
Service log file / endpointsAvailable 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​

NomaUBL monitoring — four surfacesTECH DASHBOARDLive KPIsToday's batch statePer-PA submissionApplication → Tech DashboardPROCESSING LOGPer-document traceStep timing, XSD resultPA call breakdownManagement → Processing LogSERVICE LOG FILEnomaubl-<env>.logStartup, scheduler ticksJDBC / PA / FTP errorsnomaubl.sh / nomaubl.cmd log envHTTP ENDPOINTS/api/build-info/api/licenseMachine-readable statusExternal monitoring · LB probesAUDIENCEWeb UI surfaces (left two) → operators and accountants — daily ops.Host surfaces (right two) → ops / SRE — incident response, smoke tests, automated alerting.WHAT'S NOT EXPOSED OUT OF THE BOXPrometheus /metrics · OpenTelemetry traces · per-request latency histograms — wire externally (see below).

What NomaUBL does NOT expose​

Knowing the gaps prevents misplaced searches:

MissingWhere to get it instead
Prometheus /metricsNot 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 tracesNot 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 histogramsThe Tech Dashboard surfaces aggregates; for percentiles + request-by-request, wire an APM in front of the reverse proxy.
Heap / GC statsStandard JVM JMX — connect VisualVM or JConsole over JMX, or expose JMX via a JMX-to-Prometheus exporter.
Live database connection-pool metricsNomaUBL 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 with logrotate (copytruncate) — same page.
  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​

GoalRead
Walk the Tech Dashboard cards.Application → Tech Dashboard.
Investigate a stuck or failed invoice.Management → 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​