# What Is the marin-node Module? Fleet Observability in Marin

> Discover the marin-node module for Marin observability. Gain insights into cluster capacity and per-node details with Grafana-powered visualization for your entire fleet.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: deep-dive
- Published: 2026-08-27

---

**The `marin-node` module aggregates, visualizes, and links node-level information across the entire Marin fleet, powering the Grafana-based Marin Infra Panel with cluster capacity views and per-node drill-down capabilities.**

The `marin-node` module serves as the observability backbone for node-level monitoring in the Marin repository. It bridges raw metrics from node agents with the Grafana-based Marin Infra Panel, giving operators a unified interface to track CPU, memory, and GPU utilization across every compute node in the deployment.

## How the marin-node Module Aggregates Fleet-Wide Node Data

The primary function of the `marin-node` module is to consolidate **node-level metrics** into accessible visualizations for the entire fleet. It exposes three critical views: *cluster capacity*, *node details*, and *node-pool* aggregations. These views enable operators to monitor resource utilization and health status without accessing individual machines directly.

In [`infra/grafana/marin-infra-panel/src/components/ClusterCapacity.tsx`](https://github.com/marin-community/marin/blob/main/infra/grafana/marin-infra-panel/src/components/ClusterCapacity.tsx), the module renders live data cards for each node, displaying CPU, memory, and GPU utilization collected from the node-agent. This component serves as the main entry point for fleet-wide resource monitoring.

## Routing Architecture: From Fleet View to Individual Nodes

A key feature of the `marin-node` module is its **drill-down routing capability**. Each node name in the ClusterCapacity interface links to a specific Grafana dashboard URL that filters metrics by cluster and node name.

The following TypeScript code from [`ClusterCapacity.tsx`](https://github.com/marin-community/marin/blob/main/ClusterCapacity.tsx) constructs these navigation URLs:

```typescript
// ClusterCapacity.tsx – creates a detail link for each node
const detailUrl = `/d/marin-nodes?var-cluster=${encodeURIComponent(node.cluster)}&var-node=${encodeURIComponent(node.node)}`;
<a href={detailUrl} className={css`font-family:${theme.typography.fontFamilyMonospace};font-weight:600;`}>
  {node.node}
</a>

```

This routing pattern enables operators to click any node name and immediately view the filtered `/d/marin-nodes` dashboard pre-scoped to that specific machine.

## Grafana Dashboard Definitions

The `marin-node` module includes several JSON dashboard definitions stored in `infra/grafana/dashboards/`. These files define the visual interface for node monitoring:

- [`nodes.json`](https://github.com/marin-community/marin/blob/main/nodes.json) – Defines the "Marin Nodes" dashboard with panels for CPU utilization, memory usage, and GPU packing efficiency.
- [`node_pools.json`](https://github.com/marin-community/marin/blob/main/node_pools.json) – Aggregates metrics across node pools for capacity planning.
- [`cluster_capacity.json`](https://github.com/marin-community/marin/blob/main/cluster_capacity.json) – Provides the top-level fleet view that links into individual node dashboards.

The [`nodes.json`](https://github.com/marin-community/marin/blob/main/nodes.json) file specifies the dashboard UID as `marin-nodes` and configures templating variables that match the URL parameters generated by the frontend:

```json
// infra/grafana/dashboards/nodes.json – defines the "Node details" dashboard
{
  "uid": "marin-nodes",
  "title": "Marin Nodes",
  "panels": [
    { "type": "graph", "targets": [{ "expr": "node_cpu_utilization_percent" }] }
  ],
  "templating": {
    "list": [
      { "name": "cluster", "type": "query", "datasource": "Prometheus", "query": "label_values(node_cluster)" },
      { "name": "node",    "type": "query", "datasource": "Prometheus", "query": "label_values(node)" }
    ]
  }
}

```

The templating variables `cluster` and `node` directly consume the URL parameters set by the ClusterCapacity component, ensuring seamless context switching between fleet and individual node views.

## Summary

- The `marin-node` module provides comprehensive **node-level observability** for Marin deployments, aggregating metrics from node agents across the entire fleet.
- It implements **dynamic routing** in [`ClusterCapacity.tsx`](https://github.com/marin-community/marin/blob/main/ClusterCapacity.tsx) to generate Grafana dashboard URLs with cluster and node filters.
- The module ships with **pre-configured dashboard JSON** files ([`nodes.json`](https://github.com/marin-community/marin/blob/main/nodes.json), [`node_pools.json`](https://github.com/marin-community/marin/blob/main/node_pools.json), [`cluster_capacity.json`](https://github.com/marin-community/marin/blob/main/cluster_capacity.json)) that define the Marin Infra Panel's visual interface.
- Together, these components enable operators to monitor resource utilization and drill down from fleet-wide capacity views to individual node metrics.

## Frequently Asked Questions

### What is the primary purpose of the marin-node module?

The `marin-node` module aggregates, visualizes, and links node-level information across the Marin fleet. It powers the Grafana-based Marin Infra Panel, exposing cluster capacity, node details, and node-pool views while enabling drill-down navigation from fleet overviews to individual machine metrics.

### How does the marin-node module route users to specific node dashboards?

The module constructs parameterized URLs in [`infra/grafana/marin-infra-panel/src/components/ClusterCapacity.tsx`](https://github.com/marin-community/marin/blob/main/infra/grafana/marin-infra-panel/src/components/ClusterCapacity.tsx) using `encodeURIComponent` to sanitize node and cluster names. These URLs point to `/d/marin-nodes` with `var-cluster` and `var-node` query parameters that Grafana's templating system uses to filter displayed metrics.

### What metrics does the marin-node module visualize?

The module visualizes live **CPU utilization**, **memory usage**, and **GPU packing efficiency** collected from node agents. These metrics appear in the ClusterCapacity component and detailed Grafana dashboards defined in [`infra/grafana/dashboards/nodes.json`](https://github.com/marin-community/marin/blob/main/infra/grafana/dashboards/nodes.json).

### Where are the marin-node module dashboard definitions stored?

Dashboard definitions reside in `infra/grafana/dashboards/` within the Marin repository. Key files include [`nodes.json`](https://github.com/marin-community/marin/blob/main/nodes.json) (individual node metrics), [`node_pools.json`](https://github.com/marin-community/marin/blob/main/node_pools.json) (pool aggregations), and [`cluster_capacity.json`](https://github.com/marin-community/marin/blob/main/cluster_capacity.json) (top-level fleet view), all referenced by the Marin Infra Panel's routing logic.