Starting from version 25.5, the configuration schema for instrumentation has changed.
As a result, environment variables like INST_AZ_MON_KEY have been deprecated in favor of a more expressive and structured configuration approach.
Please refer to the main application configuration for details.
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/healthContributors 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.
There could be use cases we are not aware of, in which case we encourage you to open an issue and make the request or to communicate with us using any of the available channels.
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.
See measurements and tags
{
"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.
See measurements and tags
{
"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.
kubling.nw.inbound.total Counter v25.4+
Total number of inbound network bytes received since the current instance started.
This is a per-transport metric. Use the attached tags (transport=native and transport=pg) to determine which transport the value refers to.
kubling.nw.outbound.total Counter v25.4+
Total number of outbound network bytes sent since the current instance started.
As with inbound metrics, this is collected per transport. Use the transport tag to filter and attribute usage correctly.
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.
Metrics come with without any tags by default. You can specify yours in the metricsCommonTags attribute of the Main application configuration.
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
Bear in mind that Kubling does not push Prometheus metrics, since Prometheus uses a pull-based model for monitoring, that is, the server pulls metrics from configured targets by scraping their endpoints which is, from the Kubling Engine stand pot of view, the preferred option.
OpenTelemetry v25.5+
Kubling encourages the use of OpenTelemetry for metric collection, as its format is supported by nearly all modern monitoring platforms.
If your provider does not support the OTLP protocol natively, you can always use an intermediate collector.
This approach keeps the Kubling binary lightweight. Adding native support for every monitoring tool would unnecessarily bloat the final binary size.
Enabling OpenTelemetry is straightforward. In your main application configuration, simply enable it like so:
instrumentation:
openTelemetry:
enabled: true
# Example for New Relic
url: "https://otlp.eu01.nr-data.net/v1/metrics"
headers:
api-key: "abc..."The configuration is flexible enough to support most providers, with the ability to define custom HTTP headers for the requests.
DataDog v25.5+
Due to its widespread adoption, DataDog is also supported via a native embedded exporter. Configuration is simple and minimal:
instrumentation:
dataDog:
enabled: true
apiKey: 'abc...'
url: https://app.datadoghq.euAzure Monitoring DEPRECATED
It is still possible to enable the native Azure Monitor exporter, although it is deprecated and will be removed in a future release.
The configuration mechanism has changed in version 25.5, and now lives under the instrumentation section of the main application configuration:
instrumentation:
azureMonitor:
enabled: true
connectionString: ...