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

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, 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 constructs these navigation URLs:

// 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 – Defines the "Marin Nodes" dashboard with panels for CPU utilization, memory usage, and GPU packing efficiency.
• node_pools.json – Aggregates metrics across node pools for capacity planning.
• cluster_capacity.json – Provides the top-level fleet view that links into individual node dashboards.

The nodes.json file specifies the dashboard UID as marin-nodes and configures templating variables that match the URL parameters generated by the frontend:

// 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 to generate Grafana dashboard URLs with cluster and node filters.
• The module ships with pre-configured dashboard JSON files (nodes.json, node_pools.json, 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 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.

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 (individual node metrics), node_pools.json (pool aggregations), and cluster_capacity.json (top-level fleet view), all referenced by the Marin Infra Panel's routing logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}