0
# Quarkus SmallRye Health SPI
1

2
Service Provider Interface (SPI) for SmallRye Health extension in Quarkus. Provides build-time integration for health check functionality, enabling extensions and applications to register health checks during the Quarkus compilation process.
3

4
## Package Information
5

6
- **Package Name**: quarkus-smallrye-health-spi
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Include as dependency in your `pom.xml` (typically with `provided` scope for extension development):
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-smallrye-health-spi</artifactId>
15
    <version>3.26.2</version>
16
    <scope>provided</scope>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;
24
```
25

26
For implementing health checks:
27

28
```java
29
import org.eclipse.microprofile.health.HealthCheck;
30
import org.eclipse.microprofile.health.HealthCheckResponse;
31
```
32

33
## Basic Usage
34

35
```java
36
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;
37

38
// Create a build item to register a health check during build time
39
HealthBuildItem healthItem = new HealthBuildItem(
40
    "com.example.MyHealthCheck", 
41
    true
42
);
43

44
// The health check class must implement org.eclipse.microprofile.health.HealthCheck
45
public class MyHealthCheck implements org.eclipse.microprofile.health.HealthCheck {
46
    @Override
47
    public HealthCheckResponse call() {
48
        return HealthCheckResponse.up("my-service");
49
    }
50
}
51
```
52

53
## Architecture
54

55
This SPI is designed for Quarkus extension developers and follows the Quarkus build-time optimization pattern:
56

57
- **Build Items**: `HealthBuildItem` extends `MultiBuildItem` to allow multiple health checks to be registered
58
- **Build-Time Registration**: Health checks are registered during Quarkus application compilation, not at runtime
59
- **Extension Integration**: Used by Quarkus extensions to programmatically register health checks that implement the MicroProfile Health specification
60
- **Native Image Support**: Enables optimal runtime performance by avoiding reflection in native images
61
- **SmallRye Health Integration**: Registered health checks are processed by the SmallRye Health processor and automatically included in standard health endpoints (`/q/health`, `/q/health/live`, `/q/health/ready`)
62

63
## Capabilities
64

65
### Health Check Registration
66

67
Register health check classes during the Quarkus build phase for inclusion in the final application.
68

69
```java { .api }
70
/**
71
 * Build-time item for registering health check classes during Quarkus application compilation.
72
 * Extends MultiBuildItem to allow multiple health checks to be registered.
73
 * 
74
 * This class is immutable and thread-safe.
75
 */
76
public final class HealthBuildItem extends MultiBuildItem {
77
    
78
    /**
79
     * Creates a new HealthBuildItem instance.
80
     * 
81
     * @param healthCheckClass the name of the health check class, must implement
82
     *        org.eclipse.microprofile.health.HealthCheck
83
     * @param enabled whether the health check is enabled
84
     */
85
    public HealthBuildItem(String healthCheckClass, boolean enabled);
86
    
87
    /**
88
     * Deprecated constructor - use the two-parameter version instead.
89
     * 
90
     * @param healthCheckClass the name of the health check class
91
     * @param enabled whether the health check is enabled  
92
     * @param configRootName this parameter is not used
93
     * @deprecated Use HealthBuildItem(String, boolean) instead.
94
     */
95
    @Deprecated
96
    public HealthBuildItem(String healthCheckClass, boolean enabled, String configRootName);
97
    
98
    /**
99
     * Returns the name of the health check class.
100
     * 
101
     * @return the health check class name (immutable)
102
     */
103
    public String getHealthCheckClass();
104
    
105
    /**
106
     * Returns whether the health check is enabled.
107
     * 
108
     * @return true if the health check is enabled, false otherwise
109
     */
110
    public boolean isEnabled();
111
}
112
```
113

114
## Types
115

116
```java { .api }
117
/**
118
 * Base class from io.quarkus.builder.item package that allows multiple 
119
 * instances of the same build item type to be produced.
120
 */
121
abstract class MultiBuildItem {
122
    // Inherited from quarkus-core-deployment
123
}
124
```
125

126
## Usage Examples
127

128
### Basic Health Check Registration
129

130
```java
131
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;
132

133
// Register an enabled health check
134
HealthBuildItem activeCheck = new HealthBuildItem(
135
    "com.example.DatabaseHealthCheck", 
136
    true
137
);
138

139
// Register a disabled health check  
140
HealthBuildItem inactiveCheck = new HealthBuildItem(
141
    "com.example.CacheHealthCheck", 
142
    false
143
);
144
```
145

146
### In a Quarkus Extension Build Step
147

148
```java
149
import io.quarkus.deployment.annotations.BuildStep;
150
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;
151

152
@BuildStep
153
HealthBuildItem registerCustomHealthCheck() {
154
    return new HealthBuildItem(
155
        "com.myextension.CustomHealthCheck",
156
        true
157
    );
158
}
159
```