> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes monitoring

> What the Kubernetes section's clusters, nodes, pods, namespaces and containers are built from, the attributes that fill each tab, and what it cannot show.

The Kubernetes section lists the clusters, nodes, namespaces, pods and
containers that sent telemetry in the selected time range, with counts and
resource usage for each.

It is built from your **telemetry**, not from the Kubernetes API. aiAxonIQ never
connects to your cluster's control plane. Every row is "something that reported
from this pod (or node, or cluster) in the window", which decides both what the
section can show and what it cannot.

<Info>
  **Before you start.** Install a Collector in the cluster — see
  [Send data from Kubernetes](/send-data/platforms/kubernetes). For traces from
  workloads without changing their code, see
  [Zero-code instrumentation on Kubernetes](/zero-code/kubernetes).
</Info>

## Where the rows come from

Every tab groups **metrics** by the OpenTelemetry resource attributes below. A
metric that does not carry the attribute a tab groups by does not appear on that
tab.

| Tab            | Grouped by                                               | Also shows                                                                    |
| :------------- | :------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **Clusters**   | `k8s.cluster.name`                                       | Distinct nodes, namespaces, pods and services, last seen                      |
| **Nodes**      | `k8s.node.name`                                          | Cluster, distinct pods and containers, last seen                              |
| **Namespaces** | `k8s.namespace.name`                                     | Cluster, pods, services, and the namespace's log, span and error counts       |
| **Pods**       | `k8s.pod.uid`, named by `k8s.pod.name`                   | Namespace, node, cluster, containers, services, last seen                     |
| **Containers** | `container.id`, for containers that carry `k8s.pod.name` | Image, pod, namespace, host, CPU, memory, last seen                           |
| **Images**     | `container.image.name`                                   | Containers, hosts, up to ten namespaces and environments, first and last seen |

Pods are keyed by their **uid**, not their name. A Deployment that rolls reuses
pod names, and two pods with the same name in different namespaces are two
different pods — both appear as separate rows.

The **Namespaces** tab is the one that joins three signals: the pod and service
counts come from metrics, and the log, span and error counts come from logs and
spans carrying the same `k8s.namespace.name`. A namespace appears when it has
metrics; one that has metrics but no traces shows zero spans rather than
disappearing.

<Warning>
  **Set `k8s.cluster.name` yourself.** A cluster does not report its own name in
  its telemetry, so the **Clusters** tab stays empty until your Collector adds
  it — and without it, two clusters reporting into one organization cannot be
  told apart. Add it on every collector in the cluster, for example with a
  `resource` processor, and include the processor in each pipeline:

  ```yaml theme={null}
  processors:
    resource/cluster:
      attributes:
        - key: k8s.cluster.name
          value: prod-cluster-1
          action: upsert
  ```

  Nodes, pods and namespaces do not depend on it, and still appear without it.
</Warning>

### Container CPU and memory

The **CPU**, **Memory** and **Memory used** columns average these metrics over
the window:

| Column      | Metric                         |
| :---------- | :----------------------------- |
| CPU         | `container.cpu.utilization`    |
| Memory      | `container.memory.percent`     |
| Memory used | `container.memory.usage.total` |

These are the names the Collector's `docker_stats` receiver emits. A container
that reports other metrics still appears, with a dash in these columns rather
than a zero — a dash means "not measured", not "idle".

## Every count describes the window

The numbers here are counts of what **reported**, over the selected time range:

* **Pods** on a cluster is the number of distinct pods that sent a metric in the
  window, not the number running now. Narrow the range and it drops.
* A pod that stops reporting disappears from the list. It is not shown as
  unhealthy, because there is no source here that could say it is unhealthy.
* **Last seen** is the newest sample from that row. Use it to tell a quiet pod
  from one that has gone.

## What this section cannot show

Some Kubernetes facts are not telemetry — they live only in the Kubernetes API,
which aiAxonIQ does not read. The section has tabs for four of them, and each
says the API does not serve it yet instead of showing an empty table:

| Tab           | Would show                                                                              |
| :------------ | :-------------------------------------------------------------------------------------- |
| **Workloads** | Deployments, StatefulSets, DaemonSets and CronJobs, with desired against ready replicas |
| **Events**    | Warning and Normal events with their reason, count and involved object                  |
| **Storage**   | PersistentVolumes and claims, with capacity, storage class and bound state              |
| **Services**  | Services, their type and the endpoints currently backing them                           |

For the same reason no tab shows a pod's phase, its restart count, a node's
capacity or a cluster's version. If your Collector sends cluster metrics that
carry those numbers, you can chart them from the
[Metrics](/guides/metrics/overview) section.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No clusters reporting">
    The **Clusters** tab needs `k8s.cluster.name` on your metrics. If **Nodes**
    or **Pods** has rows and **Clusters** does not, the cluster name is the
    missing piece — add it as shown above. If every tab is empty, no metric with
    Kubernetes attributes has arrived; check the Collector is running and its
    metrics pipeline exports to aiAxonIQ.
  </Accordion>

  <Accordion title="No containers reporting">
    Container rows need metrics carrying `container.id`, and on this tab also
    `k8s.pod.name`. Containers on a plain Docker host with no Kubernetes
    attributes appear under Infrastructure instead — see
    [Infrastructure and Kubernetes](/guides/infrastructure/overview).
  </Accordion>

  <Accordion title="A namespace shows zero logs or spans">
    The counts come from logs and spans that carry `k8s.namespace.name`. Enable
    the Kubernetes attributes processor on the logs and traces pipelines as well
    as metrics, so all three signals are stamped.
  </Accordion>

  <Accordion title="CPU and memory show a dash">
    No sample of the metric that column reads arrived for that container in the
    window. See [Container CPU and memory](#container-cpu-and-memory) for the
    metric names.
  </Accordion>

  <Accordion title="The pod count is lower than I expected">
    The count is pods that reported in the selected window. Widen the range, and
    check that every node runs the Collector — a node without one reports
    nothing.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Send data from Kubernetes" icon="dharmachakra" href="/send-data/platforms/kubernetes">
    Install the Collector in your cluster.
  </Card>

  <Card title="Zero-code instrumentation on Kubernetes" icon="wand-magic-sparkles" href="/zero-code/kubernetes">
    Traces from workloads without code changes.
  </Card>
</CardGroup>