Table of Contents

Exposing a Health endpoint for your Pyronaut application

Learn how to expose a health endpoint for your Pyronaut application.

1. Getting Started

In this guide, we will create a Python application built with Pyronaut.

You will learn how to use the Micronaut Management feature to enable the "health" endpoint for your application.

2. What you will need

To complete this guide, you will need the following:

  • Some time on your hands

  • GraalPy installed and the Pyronaut CLI available locally

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Pyronaut CLI (Command Line Interface) or Pyronaut Launch

pyronaut create example.micronaut.micronautguide --features=management

4.1. Testing Health Endpoints

The Micronaut management dependency added for the project supports monitoring your application via endpoints: special URIs that return details about the health and state of your application. Once the management dependency is included a /health endpoint is exposed.

tests/example/micronaut/test_health.py
import pytest
import requests

from pyronaut.test import MicronautTest, micronaut_test_fixture


@pytest.fixture
def my_context(request):
    fixture = micronaut_test_fixture(
        request,
        MicronautTest(environments=["test"], transactional=False),  (1)
    )
    yield fixture
    fixture.stop()


@pytest.fixture
def client(my_context):
    return requests.with_context(my_context)


def test_health_endpoint_exposed(client):
    response = client.get("/health")  (2)

    assert response.status_code == 200  (3)
1 MicronautTest starts the application context and embedded server.
2 The test sends an HTTP request with a context-bound requests client.
3 The health endpoint returns information about the "health" of the application, which is determined by any number of "health indicators".

4.1.1. Base Path

The base path for all endpoints is / by default. If you prefer the management endpoints to be available under a different base path, configure endpoints.all.path as in the following test.

The leading and trailing / are required for endpoints.all.path, unless micronaut.server.context-path is set, in which case just the leading / isn’t necessary.
tests/example/micronaut/test_health_path.py
import pytest
import requests

from pyronaut.test import MicronautTest, micronaut_test_fixture


@pytest.fixture
def my_context(request):
    fixture = micronaut_test_fixture(
        request,
        MicronautTest(
            environments=["test"],
            transactional=False,
            properties={"endpoints.all.path": "/endpoints/"},  (1)
        ),
    )
    yield fixture
    fixture.stop()


@pytest.fixture
def client(my_context):
    return requests.with_context(my_context)


def test_health_endpoint_exposed_at_non_default_endpoints_path(client):
    response = client.get("/endpoints/health")  (2)
    assert response.status_code == 200

    response = client.get("/health")
    assert response.status_code == 404  (3)
1 Sets the base path for all management endpoints to /endpoints/. This is normally specified in the application configuration (e.g. application.properties).
2 The "health" endpoint is now rooted at /endpoints/health
3 The "health" endpoint is no longer reachable at the default path and results in a "Not Found" status (HTTP 404).

4.1.2. Failed Health Status

Disk-space threshold is one of the built-in indicators. This test demonstrates a failed health status when free disk space drops below the specified threshold. The endpoints.health.disk-space.threshold configuration property can be provided as a string, like "10MB" or "200KB", or the number of bytes.

tests/example/micronaut/test_poor_health.py
import pytest
import requests

from pyronaut.test import MicronautTest, micronaut_test_fixture


@pytest.fixture
def my_context(request):
    fixture = micronaut_test_fixture(
        request,
        MicronautTest(
            environments=["test"],
            transactional=False,
            properties={
                "endpoints.health.disk-space.threshold": "999999999999999999",  (1)
            },
        ),
    )
    yield fixture
    fixture.stop()


@pytest.fixture
def client(my_context):
    return requests.with_context(my_context)


def test_health_endpoint_exposes_out_of_disk_space(client):
    response = client.get("/health")

    assert response.status_code == 503  (2)
    assert "DOWN" in response.text  (3)
1 Sets the endpoints.health.disk-space.threshold property to an impossibly high value to force a service down status. This is normally specified in the application configuration (e.g. application.properties).
2 A failed health check results in a Service Unavailable status (HTTP 503)
3 The response body of the error contains the json string {"status":"DOWN"}

5. Testing the Application

To run the tests:

pyronaut install
pyronaut validate-config
pyronaut test

6. Running the Application

To run the application, use the pyronaut dev command, which starts the application on port 8080.

You can execute the health endpoint exposed by the application:

curl localhost:8080/health
{"status":"UP"}

You can execute the health endpoint exposed by the native image:

curl localhost:8080/health
{"status":"UP"}

7. Next Steps

Visit Micronaut Management & Monitoring to learn more.

8. License

All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).