Exit code upon SIGTERM

[oliviercailloux]

I’d like to know how I can tell Quarkus to gracefully exit with code 0 upon receiving SIGTERM. I’d still like to react differently (i.e. with an “error” exit code, meaning any number strictly greater than 0) to other exit conditions (such as receiving another signal than SIGTERM).

I have read Graceful Shutdown but it does not talk about specifically reacting to SIGTERM.

I suppose that this might involve ApplicationLifecycleManager or Quarkus#asyncExit() but I’d appreciate having some official doc or some best practices advice rather than try / error, if this is available somewhere. (It is currently unclear to me exactly when and how I am supposed to use ApplicationLifecycleManager, if this is indeed the recommended way, or when exactly it is permitted to call Quarkus#asyncExit().)

The reason for this question is that the free hosting plan of Render sends SIGTERM to applications after 15 minutes of inactivity, and Render will consider it an error if the application exits with a non-zero code and will log it accordingly (and, perhaps, react differently). I’d like to distinguish error conditions from usual, expected activity.

Question also asked on SO.

[maxandersen]

@dmlloyd can you shed light on ways to handle this signal handling?

[dmlloyd]

In native mode

Quarkus typically installs four signal handlers when starting up in native mode:

• INT - exit the program
• TERM - exit the program
• HUP - exit the program
• QUIT - print diagnostics

On Windows, HUP and QUIT do not exist; so, on this platform we register the pseudo-signal called BREAK which prints diagnostics.

The exit signal handler follows the UNIX standard of exiting the program with 128 plus the signal number.

If you set the environment variable DISABLE_SIGNAL_HANDLERS to true, the signal handlers will not be installed and the default will be used instead (though I believe the default has similar exit code semantics).

In JVM mode

In JVM mode we do not install any signal handlers (at least I don't believe we do).

Overriding behaviors

If you're in native mode, disable the signal handlers as above first, otherwise nothing here will have an effect.

To install your own signal handler you'll need to provide your own main method, or otherwise hook into early run time initialization (for example by writing an extension).

The actual code is quite simple:

package myapp;

import io.quarkus.runtime.Quarkus;
import sun.misc.Signal;

public class Main {

    public static void main(String[] args) {
        Signal.handle(new Signal("TERM"), sig -> System.exit(0));
        // ... continue with normal startup ...
        Quarkus.run(args);
    }
}

There is more info on providing a main method in the documentation. Note that sun.misc.Signal is technically not a supported JDK API, though it is fairly widely used. At some point we should abstract this though, and maybe make signal behaviors generally customizable.

[oliviercailloux]

Thank you for the answer.

I suppose that I use the JVM mode as I start Quarkus using the java -jar … command. It does seem to install its handlers in that case, considering the behavior that I observe (reported in the original post).

I use the application.properties file to set various options for Quarkus, can I use it as well for disabling its signal handlers? It is not much practical to have to set DISABLE_SIGNAL_HANDLERS specifically as an environment variable.

[dmlloyd]

If you are running in JVM mode then you are using the JVM's signal handlers, which cannot be disabled but can be overridden as I described above.

[oliviercailloux]

Ok, I had not understood that point.

I intend to use the native mode at some point though (currently not just for simplicity), so my question remains about using the application.properties file to disable Quarkus’ signal handlers.

[dmlloyd]

In native mode the answer is the same except you would set the aforementioned environment variable to disable the Quarkus-supplied handlers so they don't override the one that you set.