❤️Health check

This article describes the health check functionality of the PORTOS API.

Get health check

GET {{server_adddress}}/api/v2/health

This endpoint allows you to get system-wide health check.

200 Health check successfully retrieved.

{
    "status": "Unhealthy",
    "totalDuration": "00:00:00.7933458",
    "entries":
    {
        "diskstorage":
        {
            "data":
            {},
            "description": "Minimum configured megabytes for disk C:\\ is 512 but actual free space are 252 megabytes",
            "duration": "00:00:00.0414471",
            "status": "Degraded"
        },
        "license":
        {
            "data":
            {
                "remaningDays": 196,
                "expirationDate": "2021-05-13T00:00:00"
            },
            "description": "Licencia exspiruje za 196 dní.",
            "duration": "00:00:00.0000619",
            "status": "Healthy"
        },
        "fiscalPrinters":
        {
            "data":
            {
                "entries":
                [
                    {
                        "key": "Fiscal2",
                        "result":
                        {
                            "data":
                            {},
                            "status": "Healthy"
                        }
                    },
                    {
                        "key": "eKasa",
                        "result":
                        {
                            "data":
                            {},
                            "description": "Tlačiareň nie je pripravená. Skontrolujte, či je tlačiareň zapnutá a pripojená do chráneného dátového úložiska.",
                            "status": "Degraded"
                        }
                    },
                    {
                        "key": "Virtual",
                        "result":
                        {
                            "data":
                            {},
                            "description": "Tlačiareň nie je zastihnuteľná na adrese 'usb-printer' (chyba: PrinterNotOpened).",
                            "status": "Unhealthy"
                        }
                    }
                ]
            },
            "duration": "00:00:00.7677499",
            "status": "Unhealthy"
        },
        "orderEndpoints":
        {
            "data":
            {
                "entries":
                [
                    {
                        "key": "Kuchyna",
                        "result":
                        {
                            "data":
                            {},
                            "description": "Tlačiareň nie je zastihnuteľná na adrese 'usb-printer' (chyba: PrinterNotOpened).",
                            "status": "Unhealthy"
                        }
                    },
                    {
                        "key": "01",
                        "result":
                        {
                            "data":
                            {},
                            "status": "Healthy"
                        }
                    }
                ]
            },
            "duration": "00:00:00.0056070",
            "status": "Unhealthy"
        },
        "portos.Features.Qerko":
        {
            "data":
            {
                "displayName": "Qerko"
            },
            "duration": "00:00:00.0113119",
            "status": "Healthy"
        }
    }
}

The response HTTP status is always 200 for all health report status values. No authorization is required for accessing API health check.

Response payload

The response payload is based on Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions library and consists of following classes:

Health status

String enumeration of following values:

• healthy Indicates that the health check determined that the component was healthy.

• degraded Indicates that the health check determined that the component was in a degraded state.

• unhealthy Indicates that the health check determined that the component was unhealthy, or an unhandled exception was thrown while executing the health check.

Health report

The response payload is represented by HealthReport class, which contains following properties:

Property		Description
status	HealthStatus	Represents the aggregate status of all the health checks. The value is most servere status reported by a health check. If no checks were executed, the value is always healthy.
totalDuration	string	Time the health check service took to execute in time span format ([d.]hh:mm:ss).
entries	HealthReportEntry[]	Dictionary map with each executed health check. The keys in this dictionary map the name of each executed health check to a health report data (represented by HealthReportEntry class) returned from the corresponding health check.

Health report entry

The values in health report entries dictionary map are represented by the HealthReportEntry class, which contains following properties:

Property		Description
status	HealthStatus	Health status of the specific health check.
duration	string	Health check execution duration in time span format ([d.]hh:mm:ss).
description	string | null	Optional human-readable description of the status of the component that was checked.
data	object | null	Additional key-value pairs describing the health of the component. Structure may vary for each health check.
exception	HealthReportException	Optional exception object representing the exception that was thrown when checking for status (if any). Equal to null when status is healthy.

Health report exception

Represents information about failed health report check.

message

string | null

The exception message.

Health check result

Some health checks contains collection of inner health checks. Each element of such collection is represented by the HealthCheckResult class, which contains following properties:

Property		Description
status	HealthStatus	Health status of the specific health check.
description	string | null	Optional human-readable description of the status of the component that was checked.
data	object | null	Additional key-value pairs describing the health of the component. Structure may vary for each health check.
exception	HealthReportException	Optional exception object representing the exception that was thrown when checking for status (if any). Equal to null when status is healthy.

Health checks

The health report's entries dictionary contains information for all API components such as:

• "core" parts of API

• optional API "features" (known as modules).

Core health checks

There are following core health report entries:

Name	Entry key name	Note
Disk storage	diskstorage	From version 4.0.36
License	license
Fiscal printers	fiscalPrinters
Order endpoints	orderEndpoints

Disk storage health check

Disk storage health check is associated with the diskstorage` identifier. This health check verifies free space on disk, on which executing assembly (the API service/deamon) is stored. Following table explains relationship between free megabytes and health status of health check.

Health status	Free megabytes
healthy	512 or more
degraded	Less than 512

License health check

License health check is associated with the license identifier. License health check verifies expiration date of product license. Following table explains relationship between remaining license days and health status of license health check.

Health status	Remaining license days
healthy	More than 14
degraded	Up to 14
unhealthy	0

The data section contains following values:

Property name	Description
remainingDays	The number of days to license expiration.
expirationDate	The license expiration date (in iso 8601 format).

The keys may not be present, if exception property of license health report entry is set.

Fiscal printers health check

Fiscal printers health check is associated with the fiscalPrinters identifier. Checks health of every fiscal device marked as active.

The data section contains following values:

Property name	Description
entries	The collection of FiscalPrintersHealthCheckResultEntry. Each element represents health check result for one fiscal device.

The FiscalPrintersHealthCheckResultEntry class contains following properties:

Property name	Description
Key	The unique fiscal name.
Result	The data describing the health of fiscal device, represented by HealthCheckResult class.

Order endpoints health check

Order endpoints health check is associated with the orderEndpoints identifier. Checks health of every order endpoint device marked as active.

The data section contains following values:

Property name	Description
entries	The collection of OrderEndpointsHealthCheckResultEntry. Each element represents health check result for one order endpoint device.

The OrderEndpointsHealthCheckResultEntry class contains following properties:

Property name	Description
Key	The unique order endpoint name.
Result	The data describing the health of order endpoint device, represented by HealthCheckResult class.

Feature health checks

If some optional features are enabled on API server, health report contains report entries for such feature. Name of health report entry is equal to feature name, that is prefixed with portos.Features prefix (e.g. Qerko feature is associated with report entry with name portos.Features.Qerko) and contains displayName property in it's data.