A service using the qsu runtime can run in two different contexts. One is (perhaps not optimally) referred to as running in the foreground, and the other is referred to as running as a service.

The intended use-case for running a service in foreground mode is during development and initial testing and troubleshooting of a service application. Normally when running in this mode, the service is run from the command line, in a terminal window, and all its logs are written to the terminal.

Running as a service means that the service application is assumed to be running under a service subsystem, such a the Windows Service subsystem, or systemd on linux. Logs will be sent to the appropriate system-specific logging system (Windows Event Log on Windows, the systemd journal on linux with systemd). Starting and stopping a qsu application running as a service should be done using the regular system service management tools.

When a qsu application uses the qsu argument parser, running the command without any subcommand will cause it to run in foreground mode. Running it with the subcommand run-service (though this is configurable) the service application will integrate into the platform's native service subsystem as appropriate.

Configuring logging

When running in foreground mode, production logging is controlled using the LOG_LEVEL environment variable. It can be set to none, error, warn, info, debug and trace (in order of increasing verbosity). If the variable is not set, it will default to warn.

To configure the development logs, use the TRACE_FILTER environment variable instead. This log uses the tracing_subscriber crate's environment filter. The filter format is feature rich and is is out of scope in this document, but in its simplest form it can be set to the same values as LOG_LEVEL. In order to reduce noise it can be configured to only observe certain modules. This is accomplished by disabling all logs, and then only enabling a subset: TRACE_FILTER="none,qsu::rt=trace". The development log defaults to none.

In some cases it may be helpful to write the development logs to a file. This can be done by setting the TRACE_FILE environment variable to the path and filename of the logfile to write developer logs to.

On unixy platforms, the same environment variables (LOG_LEVEL, TRACE_FILTER, TRACE_FILE) control logging when running as a service.

On Windows, when running as a service, production logging will log to the Windows Events Log. The development logs will be lost unless written to a file. The logging is controlled in the registry under HKLM:\SYSTEM\CurrentControlSet\Services\[service_name]\Parameters, where:

• The key LogLevel takes the role of the LOG_LEVEL environment vairable.
• The keys TraceFile and TraceFilter correspond to the environment variables TRACE_FILE and TRACE_LEVEL. Both these must be configured in the registry to enable development logging.

Unixy platforms & signals

On unixy platforms, the qsu runtime claims ownership of certain signals. SIGINT and SIGTERM are used to indicate that the service should shut down. SIGHUP can be used to instruct the service application to reload its configuration. SIGUSR1 and SIGUSR2 are translated to custom application-specific evnts.

Applications/libraries must avoid disrupting qsu's signal handlers.

Windows foreground

When running in foreground mode, the qsu runtime on Windows claims ownership of the Ctrl+C and Ctrl+Break handlers. Applications/libraries must avoid disrupting these.

Windows service

When running under the Windows Service subsystem, qsu will check if the service's Parameters registry subkey contains a string called WorkDir. If this is set it will set the process current working directory to that directory before calling the service handler's init().