Logging & Monitoring

Hub provides database-backed audit logging, crash reporting via Sentry, and real-time environment state monitoring.

SystemLog

LogProcessor/SystemLog.ts is a BaseConnector that persists audit log entries to the LogEntry MongoDB model. It provides both static convenience methods and instance methods callable via @Extern.

Static API

await SystemLog.Info("User registered successfully");
await SystemLog.Warning("Login attempt limit reached");
await SystemLog.Error("Database connection failed");
await SystemLog.Trace({
    message  : "Custom trace entry",
    traceBack: "MyConnector.MyMethod",
    level    : LogLevel.INFO,
    tags     : ["registration", "userId123"],
    onBehalf : "admin",
    token    : currentToken
});

Trace Properties

Property	Type	Purpose
message	string	Log message text
traceBack	string	Code location identifier (e.g. "AuthManager.LogIn")
level	LogLevel	INFO, WARNING, ERROR
tags	string[]	Filterable tags (log level is auto-added as first tag)
onBehalf	string	User acting on behalf of another
token	string	Auth token to resolve the current user
autoLogIt	boolean	Also output to console via LogIt (defaults to true for WARNING/ERROR)

Querying Logs

The @Extern method getLogsList($filter) supports:

Filter	Type	Purpose
date	string	Filter by date (returns entries for that day)
traceBack	string	Filter by code location
tags	string[]	Filter by tags (all must match)
limit	number	Max entries to return
offset	number	Pagination offset
ascending	boolean	Sort order (default: ascending by creation date)

Returns IModelListResult with data, size, limit, offset.

Auto-Cleanup

The Clean() method removes entries older than sysLog.maxAge days. It runs automatically during onDbPrepared() if sysLog.enabled is true.

sysLog: {
    enabled: true,
    maxAge : 30    // days to keep
}

User Resolution

Each log entry records the current user. The system resolves the user from the auth token:

• If authenticated: stores "Lastname Firstname" (or UserName if name fields are empty)
• If no token: stores "SYSTEM"

CrashAdapter

LogProcessor/Adapters/CrashAdapter.ts integrates with Sentry for automated crash reporting.

• Added as a log adapter during onEnvironmentLoad() (unless noReport: true)
• Captures unhandled exceptions and forwards to Sentry
• Maintains an ignore list (getCrashReportIgnoreList()) for non-critical errors
• Context setting via Loader.setLogsContext() adds additional context to reports

Suppressing expected throws from Sentry

Domain validation throws — ErrorLocalizable raised from @Extern methods on a user mistake — get logged at ERROR by WebResponse.OnError and would otherwise pollute Sentry. Configure substring/regex matchers in your solution's commons.jsonp:

sentry: {
    ignoreErrors: ["Period contains incomplete haulages", /^Validation failed:/]
},
logger: {
    reportIgnoreList: { "Unable to load client configuration from": true }
}

Both lists are merged into Sentry.init({ ignoreErrors }). STD/FILE/SystemLog still record the error — only Sentry drops the event. See LogProcessor — Suppressing Sentry noise for the full walkthrough.

Environment State Monitoring

EnvironmentStatePool in Utils/EnvironmentHelper.ts tracks the application initialization state and notifies registered listeners:

IDLE → LOADED → STARTING → DB_CONNECTING
                                ├→ DB_CONNECTED → DB_PREPARED → AGENTS_INIT → LOADED
                                ├→ DB_NOT_CONNECTED
                                └→ DB_CONNECTION_ERROR
                                                                           ↘ ADMIN_INIT

State Listeners

The AgentStatusResolver and frontend use AddHandler() to subscribe to state changes:

const pool = Loader.getInstance().getStatePool();
pool.AddHandler({
    OnChange  : ($state) => { /* state transition */ },
    OnComplete: ()       => { /* reached end state (LOADED) */ },
    OnError   : ($error) => { /* handler error */ }
});

Listeners are auto-removed when their associated request is aborted (via AddAbortHandler).

InMemoryAdapter & ForwardingAdapter

These adapters from hub-gui are added by the Loader:

Adapter	Environment	Purpose
InMemoryAdapter	Browser	Captures logs in memory for ApplicationLog() retrieval via GUI
ForwardingAdapter	Browser	Forwards logs to a remote endpoint (context-aware)
SentryAdapter	Server	Error reporting to Sentry (from commons)

---

See also: Logging | Hub Database Models | Hub Configuration | Hub Backend Overview