@quanticdigit/web-logging

Application log for the client: component lifecycle, every call to the event and action handlers, and errors — filtered by a configuration the server decides, delivered by a writer you provide.

The base objects in @quanticdigit/web-component and @quanticdigit/web-errors are already wired to it. Screens get the log without a line of their own.

Install

npm install @quanticdigit/web-logging

Peer dependency: @angular/core. Nothing else — this package talks to no backend, because it does not know which one you have.

Turn it on

One provider. That is the whole integration.

{ provide: APPLICATION_LOG_WRITER, useClass: MyApplicationLogWriter }

IApplicationLogWriter has a single method, write(entry). What it does with the entry is yours: queue it, batch it, POST it. It must not throw and must not make anyone wait — the caller is in the middle of a screen.

Remove that provider and the log is off everywhere. The base objects look the writer up as optional, so without it every log call is a comparison against null and nothing else.

Nothing is logged until you say so

The configuration lives in sessionStorage under log.config, as an array of

[{ "path": "app-reports", "startsWith": true, "endsWith": false, "level": "D", "disabled": false }]

A path is matched by the four combinations of the two flags: both means equality, startsWith alone means prefix, endsWith alone means suffix, neither means "contains". Among the rows that match, the most verbose level wins, so a row at D for one screen does not require removing the general one at I.

No row that matches means no log. Not "log everything" — nothing. That is what makes it safe to ship the instrumentation long before deciding what to observe, and it is the same rule the server applies to its own log configuration.

Levels are the server's one-letter codes, and lower is more severe: F E W I D T.

The path

The root is the component selector, app-reports, not the class name — class names are mangled in a production build and a log you cannot read is worse than no log. Under it:

| path | what it is | | --- | --- | | app-reports.lifecycle | init and destroy, at I | | app-reports.eventHandler.onClickApplyFilters | a template call, enter/exit at D, arguments and result at T | | app-reports.actionHandler.load | the action behind it | | errors.http | what the error collector received | | errors.unhandled | what nobody caught, at F |

By hand

For code that is not a component:

const logger = new ApplicationLogger(inject(APPLICATION_LOG_WRITER, { optional: true }), 'import-job');
logger.log('I', 'run', 'started', { file: name });

To instrument an object of your own, wrapWithLogging(target, logger) returns a proxy that logs every method call. The method still runs on the real object, so private fields keep working and the calls the object makes to itself do not go through the proxy again.

The unhandled ones

LoggingErrorHandler replaces Angular's own and adds one line before it:

{ provide: ErrorHandler, useClass: LoggingErrorHandler }

An error inside a subscribe, a setTimeout or a template binding passes through neither the service layer nor a handler proxy. This is the only place it shows up.

The family

web-utils, web-model, web-services, web-component, web-errors and web-logging are released together and always share the same version. Install them at the same version.

License

Commercial. See LICENSE.txt in the package.