Health Endpoint

The health endpoint indicates whether the engine is UP or DOWN.

The engine is considered UP when all its critical modules respond positively to a health check, indicating that:

• Clients can connect to the engine via any of the supported protocols.
• Soft transactions can be processed (if enabled).
• Adapters can establish connections with remote data sources.

The last point has a special meaning: if a data source is unreachable, the overall health of the engine is reported as DOWN.

Health status is particularly important not only for monitoring Kubling instances but also for integrating Kubling into complex pipelines, as it provides a mechanism to check readiness before proceeding with the next steps.

Health Check Endpoint:

GET http[s]://[address]:8282/observe/health

Contributors v25.3.1+

By default, data sources’ adapters contribute to overall health. However, that option can be disabled to provide the flexibility and granularity needed to determine whether an unreachable remote data source should impact the engine’s health status.

You can configure this behavior using the contributesToHealth property in each data source.
For more information, please see the configuration schemas.

Metrics

Kubling provides a set of metrics that can be integrated into your observability stack. We prioritize offering a concise, meaningful set of metrics that provide accurate insights rather than overwhelming you with an extensive list of unhelpful metrics that could unnecessarily consume system resources, particularly CPU.

Metrics Format

By default, Kubling provides metrics in a base standard format. While this format may not be directly compatible with most observability stacks, Kubling adapts these base metrics to other widely used formats to ensure compatibility. Importantly, the underlying metrics remain unchanged; only the presentation is adapted for the specific monitoring tool or format.

This documentation focuses on the default format because it is easier to read and provides a clear view of the metrics’ structure. Despite the formatting changes, the metrics’ core data and meaning remain consistent across all formats.

Current support formats are Prometheus and Azure Monitor.

Metrics endpoint

Metrics list can be fetch from GET http[s]://[address]:8282/observe/metrics
Each metric’s measurement and tags can be fetch from GET http[s]://[address]:8282/observe/metrics/[metric_name]

HTTP related metrics

http.server.requests

Gathers information about HTTP requests.

{
    "name": "http.server.requests",
    "baseUnit": "seconds",
    "measurements": [
        {
            "statistic": "COUNT",
            "value": 0.0
        },
        {
            "statistic": "TOTAL_TIME",
            "value": 0.0
        },
        {
            "statistic": "MAX",
            "value": 0.0
        }
    ],
    "availableTags": [
        {
            "tag": "exception",
            "values": [
                "none"
            ]
        },
        {
            "tag": "method",
            "values": [
                "GET"
            ]
        },
        {
            "tag": "error",
            "values": [
                "none"
            ]
        },
        {
            "tag": "uri",
            "values": [
                "/observe/metrics",
                "/observe/prometheus",
                "/observe/metrics/{requiredMetricName}"
            ]
        },
        {
            "tag": "outcome",
            "values": [
                "SUCCESS"
            ]
        },
        {
            "tag": "status",
            "values": [
                "200"
            ]
        }
    ]
}

http.server.requests.active

Provides information about currently active HTTP requests.

{
    "name": "http.server.requests.active",
    "baseUnit": "seconds",
    "measurements": [
        {
            "statistic": "ACTIVE_TASKS",
            "value": 0.0
        },
        {
            "statistic": "DURATION",
            "value": 0.0
        }
    ],
    "availableTags": [
        {
            "tag": "exception",
            "values": [
                "none"
            ]
        },
        {
            "tag": "method",
            "values": [
                "GET"
            ]
        },
        {
            "tag": "uri",
            "values": [
                "UNKNOWN"
            ]
        },
        {
            "tag": "outcome",
            "values": [
                "SUCCESS"
            ]
        },
        {
            "tag": "status",
            "values": [
                "200"
            ]
        }
    ]
}

Engine related metrics

kubling.engine.sql.sessions.active Gauge

Provides the number of current active SQL Sessions (Native & PG transports).

kubling.engine.sql.plan.active Gauge

Number of current active SQL atomic plans. Atomic plans are effective work items within the DQP, that is, once the DQP identified the Data Sources involved in the query.

kubling.engine.sql.plan.enqueued.current Gauge

Number of current Jobs (queries sent by any valid session) waiting for a free thread to process the plan.

kubling.engine.sql.plan.enqueued.max Gauge v24.5.5+

The maximum number of execution plans that were in the queue, waiting for a free thread, at any point during the current execution.

kubling.engine.sql.threads.active Gauge

Number of current active SQL related threads, like DQP’s plan processing. Take into account that one query may trigger multiple threads, one per atomic plan.

kubling.engine.sql.jobs.total Gauge

Number of total submitted SQL Jobs.

kubling.engine.sql.jobs.completed Gauge

Number of total completed SQL Jobs.

kubling.engine.sql.jobs.enqueued Gauge

Number of current enqueued SQL Jobs.

kubling.engine.sql.jobs.max Gauge

Maximum number of SQL jobs running in parallel during the current execution.

kubling.engine.sql.jobs.enqueued.max Gauge

Maximum number of SQL jobs enqueued during the current execution.

JavaScript related metrics

kubling.js.threads.active Gauge

Provides the number of current active JavaScript context threads.

kubling.js.executions Counter

Provides the number of total JavaScript context threads claimed during current execution.

kubling.js.auth.thread.active Gauge

Provides the number of current active JavaScript Auth* context threads. Same measurement as kubling.js.threads.active.

kubling.js.auth.executions Counter

Provides the number of total JavaScript Auth* context threads claimed during current execution. Same measurement as kubling.js.executions.

Cache related metrics v24.5.3+

kubling.cache.request.count Counter

Number of times the Engine requested for a Cache.

kubling.cache.entries.current Gauge

Current cached result sets.

kubling.cache.hit.count Counter

Number of times the Engine requested for a Cache and lookup methods have returned a cached value.

kubling.cache.hit.ratio Gauge

Ratio of cache requests which were hits.

kubling.cache.mem.usage Gauge

Total memory usage in Megabytes.

Prometheus

The metrics mentioned above are automatically adapted to Prometheus format.
Metrics in this format can be obtained from GET http[s]://[address]:8282/observe/prometheus

Azure Monitor

Metrics can be pushed to Azure Monitor using a built-in client. To activate it, you only need to pass an Application Insights instrumentation key via INST_AZ_MON_KEY environment variable.

See the official documentation for more information about Application Insights.