Instance Metrics

Unikraft Cloud provides an endpoint to retrieve real-time hardware and network metrics for your running instances. These metrics are useful for monitoring the performance, memory usage, and network traffic handled by your app.

Prerequisites

To access the instance metrics, you must have the developer permission role for your user.

Retrieving metrics

You can retrieve the metrics of one or more instances by making a GET request to the /instances/metrics endpoint. The request body must contain an array of instance UUIDs or names. Use a tool like curl for ad-hoc queries, or configure your monitoring system to consume the endpoint's Prometheus-formatted output.

Example

The following example creates an instance and retrieves its metrics using curl.

First, provision a new instance:

This command will create the NGINX instance with scale-to-zero enabled:

[●] Deployed successfully!
 │
 ├────────── name: nginx-26g86
 ├────────── uuid: 3605978e-5feb-4209-8f9e-de45f00a7d66
 ├───────── state: running
 ├─────────── url: https://black-snowflake-iy7509ap.fra.unikraft.app
 ├───────── image: nginx@sha256:19854a12fe97f138313cb9b4806828cae9cecf2d050077a0268d98129863f954
 ├───── boot time: 7.77 ms
 ├──────── memory: 256 MiB
 ├─────── service: black-snowflake-iy7509ap
 ├── private fqdn: nginx-26g86.internal
 ├──── private ip: 172.16.6.1
 └────────── args: /usr/bin/nginx -c /etc/nginx/nginx.conf

Now, request the metrics for that instance. Set UKC_TOKEN and UKC_METRO for the API calls:

curl -X GET "https://api.$UKC_METRO.unikraft.cloud/v1/instances/metrics" \
  -H "Authorization: Bearer $UKC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[{"name":"nginx-26g86"}]'

Code
{
  "status": "success",
  "data": {
    "instances": [
      {
        "status": "success",
        "uuid": "3605978e-5feb-4209-8f9e-de45f00a7d66",
        "name": "nginx-26g86",
        "state": "standby",
        "start_count": 2,
        "started_at": "2026-03-18T12:31:49Z",
        "stopped_at": "2026-03-18T12:31:50Z",
        "uptime_s": 7.817000,
        "boot_time_s": 0.005900,
        "net_time_s": 0.025256,
        "rss_bytes": 0,
        "cpu_time_s": 0,
        "rx_bytes": 1614,
        "rx_packets": 10,
        "tx_bytes": 537,
        "tx_packets": 5,
        "nconns": 0,
        "nreqs": 0,
        "nqueued": 0,
        "ntotal": 1,
        "wakeup_latency_seconds": [
          {
            "bucket_s": 0.001000,
            "count": 0
          },
          {
            "bucket_s": 0.002000,
            "count": 0
          },
          {
            "bucket_s": 0.004000,
            "count": 0
          },
          {
            "bucket_s": 0.008000,
            "count": 0
          },
          {
            "bucket_s": 0.016000,
            "count": 0
          },
          {
            "bucket_s": 0.032000,
            "count": 1
          },
          {
            "bucket_s": 0.064000,
            "count": 0
          },
          {
            "bucket_s": 0.128000,
            "count": 0
          },
          {
            "bucket_s": 0.256000,
            "count": 0
          },
          {
            "bucket_s": 0.512000,
            "count": 0
          },
          {
            "bucket_s": 1.024000,
            "count": 0
          },
          {
            "bucket_s": 2.048000,
            "count": 0
          },
          {
            "bucket_s": 4.096000,
            "count": 0
          },
          {
            "bucket_s": null,
            "count": 0
          }
        ],
        "wakeup_latency_seconds_sum": 0.023
      }
    ]
  },
  "op_time_us": 125
}

If the request is successful, you will receive a response reporting the instance's performance and network data.

Understanding the Response

The metrics response contains fields for CPU, memory, boot time, and networking. The Prometheus output comments contain details about each metric. Below is a detailed breakdown of each field returned in the metrics object.

Instance Info

uuid

The UUID of the instance.

name

The name of the instance.

state

The current state of the instance. Possible values: stopped, starting, running, draining, stopping, standby, template.

Lifecycle and uptime

start_count

Number of times the instance started, including scale-to-zero wakeups.

started_at

Timestamp of the most recent instance start, in RFC 3339 format.

stopped_at

Timestamp of the most recent instance stop, in RFC 3339 format.

uptime_s

Total accumulated uptime of the instance in seconds across all starts.

Memory & CPU

rss_bytes

Resident set size in bytes. This is the amount of physical memory that the instance has touched and is currently reserved for it. It grows as the instance uses more memory up to the configured limit. This metric drops to 0 when the instance is in standby.

cpu_time_s

Consumed CPU time in seconds for the last second. This metric drops to 0 when the instance is in standby.

Boot and network initialization times

boot_time_s

Boot time in seconds. Calculated as the time between the virtualization toolstack responding to a boot request and the moment the guest OS starts executing user code.

net_time_s

Network initialization time in seconds. This is the time from when the instance started until the user-level app starts listening on a non-localhost port.

Network traffic

rx_bytes

Total amount of network bytes received.

rx_packets

Total count of network packets received.

tx_bytes

Total amount of network bytes transmitted.

tx_packets

Total count of network packets transmitted.

Connections & Requests

nconns

Number of currently established inbound connections (non-HTTP). This metric drops to 0 when the instance is in standby.

nreqs

Number of in-flight HTTP requests. This metric drops to 0 when the instance is in standby.

nqueued

Number of queued inbound connections and HTTP requests. This metric drops to 0 when the instance is in standby.

ntotal

Total number of inbound connections and HTTP requests handled.

Wakeup latency

wakeup_latency_seconds

A histogram of scale-to-zero wakeup latencies. Each entry contains a bucket_s threshold (in seconds) and the count of wakeups that fell within that bucket. The final bucket has bucket_s: null, representing the +Inf overflow bucket for wakeups exceeding all defined thresholds.

wakeup_latency_seconds_sum

The sum of all wakeup latencies in seconds. Together with the histogram buckets this allows computing a mean wakeup latency: wakeup_latency_seconds_sum / ntotal.

Conclusion

Instance metrics give you a real-time view into the performance and health of your Unikraft Cloud instances. By monitoring memory usage, CPU time, boot and network initialization times, and connection statistics, you can understand how your app behaves under load. The Prometheus format lets you plug these metrics directly into monitoring tools such as Grafana or any other Prometheus-compatible system.

Learn more

• Scale to zero and how it affects instance lifecycle.
• Scale to zero triggers for controlling when instances wake up.
• Platform instances for managing and inspecting your instances.
• The CLI reference and the legacy CLI reference.