Achieve — High Level Logic Project. Creating a new meta design pattern.

Friendly in development. Fast in production. Just build your apps. Let Achieve do the rest.

← Back to documentation index

Achieve Logging

Created November 6, 2026 · Updated November 6, 2026 · Achieve 3.1.0 · Qualified runtime: Node.js 24.22.2

Achieve 3.1.0 is a Node.js HTTP application server with separate facilities for startup reporting, interactive development diagnostics, persistent server events, and persistent access records. These channels serve different purposes and can be controlled without turning all reporting on or off together.

Startup reporting

When a listener starts, Achieve identifies the protocol, port, Achieve version, and Node.js version on the console. It then reports the effective application path and configuration, including mode, NODE_ENV, caching, compression, buffered-input limit, logging selections, log path, MIME configuration, CORS policies, route mappings, path mappings, and registered methods.

Startup reporting remains visible in production and when persistent logging is disabled. A startup warning or configuration failure is therefore not hidden by a logging choice. When persistent server logging is enabled, startup and configuration records are also appended to the server log.

Development and production modes

Development mode is the default. It writes request flow, resource selection, servlet lifecycle information, warnings, and errors to the console. This diagnostic output supports interactive development and is controlled by setMode(), not by persistent logging configuration.

Production mode suppresses routine developer-oriented console traces and uses stable servlet and helper-module caching until restart. It does not disable error handling, startup reporting, access logging, or persistent server events.

achieve.setMode("production");

Achieve mode and NODE_ENV are separate settings. Changing one does not implicitly change the other.

Persistent logging

Persistent logging is disabled by default. setLogging() selects server logging, access logging, or both:

achieve.setLogging("server");
achieve.setLogging("access");
achieve.setLogging("server", "access");

achieve.setLogging(true);  // both persistent logs
achieve.setLogging(false); // neither persistent log

The named form is declarative: selecting only "access" does not enable server logging. Unknown selections and mixed boolean/name forms are rejected rather than partially applied. Logging configuration must be completed before the first call to a listener.

Log location and organization

The default log root is a logs directory beneath the server startup entry directory. setLogPath() accepts an absolute path or a path relative to that startup directory. Changing the application space does not relocate the log root.

achieve.setLogPath("./logs");
achieve.setLogging("server", "access");

Server and access records are separated into local-date files:

logs/server/YYYY-MM-DD.log
logs/access/YYYY-MM-DD.log

Each record begins with a local timestamp containing milliseconds and the numeric UTC offset. A new daily file is opened when the local date changes.

Server logs

The server log contains START and CONFIG records, operational warnings, and server errors. When an Error object is available, the persistent error record includes stack information. Routine development request traces are not copied into the server-event file.

Uncaught synchronous servlet exceptions and rejected servlet promises are reported through the server-error channel when they reach Achieve's response-completion boundary. Errors in registered handlers, compression, file streaming, listener operation, and request dispatch use the same channel. Application code's own console.log() and console.error() calls are not captured automatically.

Access logs

Access logging writes one record when a response finishes or closes prematurely. A record contains the remote address, request method, received request target, final status code, elapsed time in milliseconds, and a completion state of complete or aborted.

remote="127.0.0.1" method="GET" target="/report.htm"
status=200 elapsed=1.427ms state=complete

Quoted values escape backslashes, quotation marks, and control characters so a request value cannot create a second physical record. Access records are not printed to the console or mixed into the server log. The same record form is used in development and production and for requests accepted through Node.js HTTP/1.1 and HTTP/2 compatibility interfaces.

Operational behavior

Selected persistent sinks are initialized before the listener starts. If a directory or initial file cannot be opened, Achieve reports the failure directly and does not start the listener while claiming that the selected logging is active.

A write failure after startup disables the affected sink and reports the failure once. Later records for that sink are dropped, while the HTTP service and an independent healthy sink remain available. Restart the process after correcting a failed destination.

The built-in facilities provide append-only daily text files. Retention, archival, compression, aggregation, search, and application-specific audit records remain deployment or application responsibilities. Access logs can contain request targets and client addresses, so deployments should apply retention and access controls appropriate to that data.

Automated verification

The logging regression suite verifies startup reporting across HTTP, HTTPS, h2c, and secure HTTP/2; development and production console behavior; configuration validation and startup locking; daily file names and timestamps; path resolution; server/access separation; access-record fields and escaping; aborted requests; and HTTP/2 access records.

Fault-injection cases verify initialization failures, runtime stream failures, daily rollover failures, one-time diagnostics, sink isolation, continued HTTP service after a runtime logging failure, and catchall error reporting followed by a successful request.

See the Configuration Reference for the public API and Achieve test documentation for the stable verifier entry point.