Skip to content

Commit

Permalink
[RELEASE]merging 'release-1.0.1' into 'master'
Browse files Browse the repository at this point in the history
  • Loading branch information
jpmsilva committed Mar 24, 2018
2 parents 150118d + 1fdc49a commit faa34d8
Show file tree
Hide file tree
Showing 18 changed files with 956 additions and 623 deletions.
112 changes: 2 additions & 110 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,113 +10,5 @@ may contain interesting and reusable components for other projects.
When using Spring Boot, simply import the `com.github.jpmsilva.jsystemd:systemd-spring-boot-starter`
dependency into your own project.

Auto-configuration takes place through the class `com.github.jpmsilva.jsystemd.SystemdAutoConfiguration`,
and will notify systemd once your application starts up successfully, via a event listener for events
of type `org.springframework.boot.context.event.ApplicationReadyEvent`.

When using this library, you service units can now use `Type=notify` under the `[Service]` unit configuration.

### Additional status

When using the auto-configuration class, beans of type `com.github.jpmsilva.jsystemd.SystemdNotify`
will also be searched and used to compose an extended status message that systemd will display
when using the `status` verb.

Out of the box this module will show memory and classloader information:

```
[root@machine ~]# systemctl status myservice.service
● myservice.service - My Spring Boot Service
Loaded: loaded (/etc/systemd/system/myservice.service; disabled; vendor preset: disabled)
Active: active (running) since Qui 2018-02-15 10:19:28 WET; 1h 24min ago
Main PID: 11142 (java)
Status: "Heap: 139.5 MiB/256 MiB, Non-heap: 62.7 MiB/64.1 MiB, Classes: 7915"
CGroup: /system.slice/myservice.service
└─11142 /opt/jdk1.8.0/bin/java -XX:+ExitOnOutOfMemoryError -Xms256M -Xmx512M -XX:+UseG1GC -jar /opt/myservice/myservice.jar
```

You can create your own status information by providing instances of `SystemdNotify` to the application context.

Status is updated once every five seconds.

### Startup feedback

As the application starts up, the Spring Boot application progresses through the stages defined
in [SpringApplicationRunListener](https://docs.spring.io/spring-boot/docs/1.5.10.RELEASE/api/org/springframework/boot/SpringApplicationRunListener.html):
* starting
* context loaded
* context prepared
* environment prepared
* finished

This status is shown when requesting the service status:
```
[root@machine ~]# systemctl status myservice.service
● myservice.service - My Spring Boot Service
Loaded: loaded (/etc/systemd/system/myservice.service; disabled; vendor preset: disabled)
Active: activating (start) since Wed 2018-03-07 23:01:10 WET; 3s ago
Main PID: 21034 (java)
Status: "State: context prepared"
CGroup: /system.slice/myservice.service
└─21034 /opt/jdk1.8.0/bin/java -XX:+ExitOnOutOfMemoryError -Xms256M -Xmx512M -XX:+UseG1GC -jar /opt/myservice/myservice.jar
```

As soon as the application context is ready and starts creating beans, the status will also show the progress on bean creation, which can give you an
approximate measure of the percent complete.
```
[root@machine ~]# systemctl status myservice.service
● myservice.service - My Spring Boot Service
Loaded: loaded (/etc/systemd/system/myservice.service; disabled; vendor preset: disabled)
Active: activating (start) since Wed 2018-03-07 23:01:10 WET; 11s ago
Main PID: 21034 (java)
Status: "State: context loaded, Creating bean 94 of 472"
CGroup: /system.slice/myservice.service
└─21034 /opt/jdk1.8.0/bin/java -XX:+ExitOnOutOfMemoryError -Xms256M -Xmx512M -XX:+UseG1GC -jar /opt/myservice/myservice.jar
```

This status information will only be shown during the startup sequence of the Spring Boot application, and will not be displayed after systemd is notified
that the unit is ready.

### Startup timeout

During startup, as status updates are sent to systemd to notify on progress, the timeout is extended.
This means that as long as the application context is making progress in creating beans, the startup will not
timeout. The default timeout of 30 seconds that systemd implements should be sufficient to ensure the
service starts up correctly.

### Tomcat information

Additionally, when using the Tomcat starter, the Catalina mbeans will be used to show connector usage on the service status. The connector status corresponds
to the current usage of the thread pool, in the form of <busy threads>/<total available threads>. So, `http-nio-8080: 5/10` means that 5 out of the 10
available threads of the `http-nio-8080` connector are actively serving requests.

```
[root@machine ~]# systemctl status myservice.service
● myservice.service - My Spring Boot Service
Loaded: loaded (/etc/systemd/system/myservice.service; disabled; vendor preset: disabled)
Active: active (running) since Wed 2018-03-07 23:01:36 WET; 11min ago
Main PID: 21034 (java)
Status: "Heap: 339 MiB/512 MiB, Non-heap: 118.1 MiB/121.5 MiB, Classes: 15734, http-nio-8080: 2/10"
CGroup: /system.slice/myservice.service
└─21034 /opt/jdk1.8.0/bin/java -XX:+ExitOnOutOfMemoryError -Xms256M -Xmx512M -XX:+UseG1GC -jar /opt/myservice/myservice.jar
```

### Native library

Out of the box, the implementation relies on the presence of the dependency of `net.java.dev.jna:jna` to
interface with `libsystemd` natively.

You can however suppress this dependency, in which case the strategy will switch to calling the `systemd-notify` binary,
by spawning a separate process. This method has it's drawbacks, though, as the service type must now allow
all processes from the same process group to send notification messages, by adding the configuration `NotifyAccess=all` to the `[Service]`
key.

In the absence of `systemd-notify` the implementation library chosen will be `com.github.jpmsilva.jsystemd.SystemdNotifyNoop`, and no integration will
be performed.

### Conditionals

The auto-configuration class is guarded with `com.github.jpmsilva.jsystemd.ConditionalOnSystemd`.
This conditional searches for the presence of the environment property `NOTIFY_SOCKET` (see the
[sd_notify documentation](https://www.freedesktop.org/software/systemd/man/sd_notify.html#%24NOTIFY_SOCKET) for
more details), as well as the operating system being Linux.
Refer to the [documentation site](https://jpmsilva.github.io/jsystemd-site/)
for more information.
2 changes: 1 addition & 1 deletion do-site-release
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ SCRIPTPATH=$(dirname "$SCRIPT")

set -e

"${SCRIPTPATH}"/mvnw clean site site:site
"${SCRIPTPATH}"/mvnw clean package site site:site --debug
108 changes: 54 additions & 54 deletions jsystemd-core/pom.xml
Original file line number Diff line number Diff line change
@@ -1,54 +1,54 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
Copyright 2018 Joao Silva
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<artifactId>jsystemd-core</artifactId>

<parent>
<groupId>com.github.jpmsilva.jsystemd</groupId>
<artifactId>jsystemd</artifactId>
<version>1.0.0</version>
</parent>

<name>jsystemd core</name>
<description>
The core library for systemd integration. This component does not depend on Spring, and can be used in any Java application.
</description>

<dependencies>
<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>com.jakewharton.byteunits</groupId>
<artifactId>byteunits</artifactId>
</dependency>
<dependency>
<groupId>com.github.jpmsilva.groundlevel-utilities</groupId>
<artifactId>groundlevel-utilities</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</project>
<?xml version="1.0" encoding="UTF-8"?>

<!--
Copyright 2018 Joao Silva
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<artifactId>jsystemd-core</artifactId>

<parent>
<groupId>com.github.jpmsilva.jsystemd</groupId>
<artifactId>jsystemd</artifactId>
<version>1.0.1</version>
</parent>

<name>jsystemd core</name>
<description>
The core library for systemd integration. This component does not depend on Spring, and can be used in any Java application.
</description>

<dependencies>
<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>com.jakewharton.byteunits</groupId>
<artifactId>byteunits</artifactId>
</dependency>
<dependency>
<groupId>com.github.jpmsilva.groundlevel-utilities</groupId>
<artifactId>groundlevel-utilities</artifactId>
<version>1.0.1</version>
</dependency>
</dependencies>
</project>
26 changes: 26 additions & 0 deletions jsystemd-core/src/site/site.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
<body>
<menu ref="reports"/>
</body>
</project>
102 changes: 51 additions & 51 deletions jsystemd-spring-boot-starter/pom.xml
Original file line number Diff line number Diff line change
@@ -1,51 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
Copyright 2018 Joao Silva
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<artifactId>jsystemd-spring-boot-starter</artifactId>

<parent>
<groupId>com.github.jpmsilva.jsystemd</groupId>
<artifactId>jsystemd</artifactId>
<version>1.0.0</version>
</parent>

<name>jsystemd starter module for Spring Boot</name>
<description>Spring boot starter that provides auto-configuration for jsystemd, effectively turning any spring boot application into a proper system service
under systemd.
</description>

<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>jsystemd-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
</project>
<?xml version="1.0" encoding="UTF-8"?>

<!--
Copyright 2018 Joao Silva
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<artifactId>jsystemd-spring-boot-starter</artifactId>

<parent>
<groupId>com.github.jpmsilva.jsystemd</groupId>
<artifactId>jsystemd</artifactId>
<version>1.0.1</version>
</parent>

<name>jsystemd starter module for Spring Boot</name>
<description>Spring boot starter that provides auto-configuration for jsystemd, effectively turning any spring boot application into a proper system service
under systemd.
</description>

<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>jsystemd-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
</project>
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ void state(ApplicationState state) {
}

/**
* Enumeration of supported application startup sequence state
* Enumeration of supported application startup sequence state.
*/
public enum ApplicationState {
STARTING, ENVIRONMENT_PREPARED, CONTEXT_PREPARED, CONTEXT_LOADED
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ public class SystemdSpringApplicationRunListener implements SpringApplicationRun
* @param springApplication the current Spring Application
* @param args the arguments passed to the Spring Application
*/
@SuppressWarnings("PMD.UnusedFormalParameter")
public SystemdSpringApplicationRunListener(SpringApplication springApplication, String[] args) {
if (SystemdUtilities.isUnderSystemd()) {
Systemd systemd = springApplication.getInitializers().stream()
Expand Down
Loading

0 comments on commit faa34d8

Please sign in to comment.