CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-quarkus--quarkus-smallrye-health-spi

Service Provider Interface (SPI) for SmallRye Health extension in Quarkus - provides build-time integration for health check functionality

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Quarkus SmallRye Health SPI

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.

Package Information

  • Package Name: quarkus-smallrye-health-spi
  • Package Type: maven
  • Language: Java
  • Installation: Include as dependency in your pom.xml (typically with provided scope for extension development):
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-health-spi</artifactId>
    <version>3.26.2</version>
    <scope>provided</scope>
</dependency>

Core Imports

import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;

For implementing health checks:

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;

Basic Usage

import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;

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

// The health check class must implement org.eclipse.microprofile.health.HealthCheck
public class MyHealthCheck implements org.eclipse.microprofile.health.HealthCheck {
    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("my-service");
    }
}

Architecture

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

  • Build Items: HealthBuildItem extends MultiBuildItem to allow multiple health checks to be registered
  • Build-Time Registration: Health checks are registered during Quarkus application compilation, not at runtime
  • Extension Integration: Used by Quarkus extensions to programmatically register health checks that implement the MicroProfile Health specification
  • Native Image Support: Enables optimal runtime performance by avoiding reflection in native images
  • 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)

Capabilities

Health Check Registration

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

/**
 * Build-time item for registering health check classes during Quarkus application compilation.
 * Extends MultiBuildItem to allow multiple health checks to be registered.
 * 
 * This class is immutable and thread-safe.
 */
public final class HealthBuildItem extends MultiBuildItem {
    
    /**
     * Creates a new HealthBuildItem instance.
     * 
     * @param healthCheckClass the name of the health check class, must implement
     *        org.eclipse.microprofile.health.HealthCheck
     * @param enabled whether the health check is enabled
     */
    public HealthBuildItem(String healthCheckClass, boolean enabled);
    
    /**
     * Deprecated constructor - use the two-parameter version instead.
     * 
     * @param healthCheckClass the name of the health check class
     * @param enabled whether the health check is enabled  
     * @param configRootName this parameter is not used
     * @deprecated Use HealthBuildItem(String, boolean) instead.
     */
    @Deprecated
    public HealthBuildItem(String healthCheckClass, boolean enabled, String configRootName);
    
    /**
     * Returns the name of the health check class.
     * 
     * @return the health check class name (immutable)
     */
    public String getHealthCheckClass();
    
    /**
     * Returns whether the health check is enabled.
     * 
     * @return true if the health check is enabled, false otherwise
     */
    public boolean isEnabled();
}

Types

/**
 * Base class from io.quarkus.builder.item package that allows multiple 
 * instances of the same build item type to be produced.
 */
abstract class MultiBuildItem {
    // Inherited from quarkus-core-deployment
}

Usage Examples

Basic Health Check Registration

import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;

// Register an enabled health check
HealthBuildItem activeCheck = new HealthBuildItem(
    "com.example.DatabaseHealthCheck", 
    true
);

// Register a disabled health check  
HealthBuildItem inactiveCheck = new HealthBuildItem(
    "com.example.CacheHealthCheck", 
    false
);

In a Quarkus Extension Build Step

import io.quarkus.deployment.annotations.BuildStep;
import io.quarkus.smallrye.health.deployment.spi.HealthBuildItem;

@BuildStep
HealthBuildItem registerCustomHealthCheck() {
    return new HealthBuildItem(
        "com.myextension.CustomHealthCheck",
        true
    );
}

docs

index.md

tile.json