Hardware inventory

Overview

Once a fleet of physical servers grows past a handful, nobody can say from memory which disks are in which chassis, which memory modules were replaced last quarter, or where the server with the failing controller physically stands. The answer usually lives in a spreadsheet that is a few replacements out of date.

Hardware inventory solves this. The monitoring agent already running on your bare-metal servers reports what is installed in them, and the platform keeps that picture current: a hardware card for every server, a fleet you can search by the parts inside it, and a record of every component that arrived, left, or moved.

The data is collected on bare-metal servers only — the agent does not inventory virtual machines, and virtual machines never appear in this section. Every server is re-examined every 5 minutes, so a disk replaced this morning is already on the card by the time you look for it.

The feature lives in the project’s side menu under Infrastructure: the Physical Servers page holds the fleet and the hardware, the Datacenters page holds the racks the servers stand in.

What is collected

For each bare-metal server the agent reports:

• The server itself — system, motherboard, BIOS, and chassis: manufacturer, model, version, serial numbers.
• Processors and memory — CPU sockets and DIMM slots, occupied and empty, with the module installed in each.
• Storage — RAID and HBA controllers, the RAID volumes on them, and every physical disk, including the ones hidden behind a controller and invisible to the operating system.
• Network cards, discrete GPUs, and power supplies.
• Seats — PCIe expansion slots, SATA ports, and drive bays, so an empty seat is as visible as an occupied one.

The exact set depends on the server: the agent passes through what the hardware reports about itself, and a machine that reports less will show less. For the full list of what the agent sends, see Hardware and inventory.

What you get

• A hardware card per server — everything installed, seat by seat, with the storage laid out from the controller down to the disk.
• Fleet-wide search by installed hardware — which servers hold a disk of this model and a controller of that one.
• Change history — when a component appeared, when it disappeared, and which server it moved to.
• Physical placement — datacenters, racks, and the units a server occupies, with a rack elevation you can read at a glance.
• API access — the same data as a read-only HTTP API, for scripts and external asset systems.

Important: archiving a project permanently destroys its inventory — components, slots, installation history, datacenters, racks, and placements, including the placements of network devices in those datacenters (the devices themselves are kept). Unarchiving does not bring any of it back. The hardware itself is re-collected from the next agent report, but the datacenters, racks, and placements have to be created again by hand.

Quick Start

1. Make sure hardware inventory has been enabled by the administrator.
2. Install the monitoring agent on the bare-metal server the usual way. Nothing else has to be configured: the agent recognizes physical hardware and starts reporting the inventory on its own.
3. Wait for the first collection cycle — about 5 minutes. Until it completes, the server’s card reads Hardware inventory has not been synced yet.
4. Open Infrastructure → Physical Servers in the project’s side menu.
5. Click the server’s name to open its hardware card.

If the server does not appear, see Troubleshooting.

Core Concepts

Component, slot, and installation

A component is one physical piece of hardware: a processor, a memory module, a disk, a storage controller, a network card, a GPU, a power supply.

A component belongs to the project rather than to a server. The platform recognizes the same physical part wherever it turns up, so a disk pulled out of one server and put into another is seen as the same disk moving, not as one disk vanishing and another one appearing.

A slot is a seat on a particular server: a CPU socket, a DIMM slot, a drive bay, an expansion slot, a power supply bay. A slot exists whether or not anything is in it, which is how the platform can tell you that four of eight DIMM slots are free.

An installation is the fact that a given component sat in a given slot of a given server between two points in time. The open installation is what is in the server now; the closed ones are its history. One component cannot be installed in two servers at the same time.

Component lifecycle

Every component carries a status:

A component that moves to another server does not become Removed — its installation on the old server is closed, and a new one opens on the new server.

A component can sit in Suspect missing for a long time, because the wait is counted in inventories that actually brought news, not in minutes on the clock. That is what the manual Mark as removed action is for.

Data freshness

Freshness describes a server’s data rather than any single part, and it is a separate question from the lifecycle: a component can be Present on a server whose data is three days old.

On the Physical Servers page the Data column carries one of these badges:

While a server’s data is stale or incomplete, the platform does not remove the components that stopped being reported: a missing part is far more likely to mean a missing report than a missing disk.

Placement

Placement is what you describe by hand: which datacenter a server is in, which rack, which units it occupies, and which face of the rack it is bolted to. Nothing here is discovered automatically — no server reports where it stands.

Both physical servers and network devices can be placed, and equipment can also be placed at the datacenter level, without a rack. The platform will not let two pieces of equipment occupy the same unit on the same face, and will not let a piece stick out above the top of the rack.

Taking equipment out of a rack does not erase where it used to be: the placement history is kept.

The Physical Servers Page

The page lists every bare-metal server in the project with its placement and the state of its data:

A server that has not been placed reads Not placed across the three placement columns.

The Show historical data switch above the table is on by default. This page is an inventory of the fleet, not a health screen: a server whose agent went quiet a week ago is still a server you own, so it stays in the list with a historical badge instead of disappearing. Turn the switch off to see only servers that reported within the last two hours.

The list is sorted by name and paginated at 50 servers per page; the total count is shown above the table.

There is no export on this page. To pull the inventory out of the platform, use the API (see API access to the inventory).

Searching for servers by installed hardware

Two ways to narrow the list, and they work together.

By name. The Server name box matches any part of the name, not just its beginning: eb-0 finds web-01. At least 2 characters.

By the hardware inside. Turn on the Advanced search switch to reveal the Components block. Each condition is a triple — Component type, Field, Value — and Add condition gives you another one, up to five.

Conditions are ANDed, and each one is about its own component. “A disk with serial number 123 and a controller with model PERC” finds the servers that hold both parts, not a single part that is somehow both. Leaving Component type as Any type searches components of every type for that field.

Which fields exist depends on the component type, and the form only offers the fields the chosen type actually carries:

Important: a disk has no Manufacturer field. Disks report either a generic vendor string or nothing at all, so the brand is part of the model instead — SAMSUNG MZQLB1T9HAJR-00007. To find every disk from a given vendor, search by Model. This is why Manufacturer disappears from the field list as soon as you choose Disk.

Text values match a substring and need at least 2 characters; a condition whose value is shorter is quietly ignored rather than made into an error, so half-typed rows never throw away the rest of your search. Conditions match only the hardware installed right now — to ask where a part used to be, use the timeline on the server’s card or the API.

The search lives in the address bar, so a useful query can be bookmarked or passed to a colleague. Reset all clears every condition and the name box.

The Server Hardware Card

Clicking a server’s name opens its card. Along the top, next to the server’s name, sit the status badges: Not synced, Inventory stale, Partial inventory, No location — each appears only when it applies.

The card is read top to bottom:

• System, Baseboard, BIOS, Chassis — the server’s own identity: manufacturer, model or version, serial number. These are properties of the machine, not components, so they have no lifecycle and no history.
• CPU, Memory, Disks, GPU, and NIC — a row of counters with no heading of its own: CPU sockets populated of total, memory slots populated of total with the installed capacity, the number of disks and their total capacity, GPUs (when the server has any), and the number of network cards.
• Physical Location — datacenter, rack, and position, with the rack name linking to its elevation.
• Components — everything installed now, grouped by type: CPU, Memory, Controller, Storage, NIC, GPU, PSU. Each group has the columns that make sense for it — cores and frequency for processors, capacity and part number for memory, media type and WWN for disks, MAC for network cards. Components that have already been removed are not listed; their record is in the timeline.
• Timeline — the server’s change history (see Change history).
• Storage Topology and OS Storage Stack — how the storage is put together (see Storage).
• Slot Details — every seat on the server, grouped into CPU Sockets, DIMM Slots, Storage Locations, Expansion Slots, Onboard Devices, and Power Supplies. An unoccupied seat reads Empty; a seat the agent could not report on reads N/R.
• Last scan — when the agent last reported this server.

Storage

Two blocks describe the storage, from opposite ends.

Storage Topology is the hardware view. Each storage controller is shown with the RAID volumes configured on it — name, RAID level, capacity — and beneath them the physical disks attached to that controller, each with its bay number and its device name in the operating system. Disks that hang off no controller are grouped separately: NVMe drives as Direct PCIe, onboard SATA drives as Onboard.

This is the view that shows the disks the operating system cannot see. A drive behind a RAID controller is invisible to the OS, but it is right here, with a serial number you can quote to your hardware supplier. Disks and volumes in trouble are badged — Failed, Predictive, Degraded, Rebuilding — so a dying drive is visible without opening anything else, and a controller with a backup battery shows its BBU state next to its name.

OS Storage Stack is the same storage read the other way: what each block device the operating system uses is actually built from. An LVM volume built from an MD RAID array, built from partitions, built from disks — the whole chain, so you can trace a filesystem down to the physical drives that carry it.

These two blocks are the only part of the card that the API does not return.

Change history

The Timeline block next to the components list is the server’s history, newest first, with three kinds of entry:

• Installed — the component appeared in this seat.
• Removed — the component left and did not turn up anywhere else.
• Moved — the component left one seat and appeared in another. Both seats are shown, and when the destination is a different server, so is its name.

The pills above the list filter it: All, Removed, Moved.

A move is recorded as one event rather than a removal followed by an installation, so a disk migrating between servers reads as one line rather than two unrelated ones.

Marking a component as removed

When the agent stops reporting a component, the component stays on the card badged Suspect missing, with the note “The agent stopped reporting this component”. This is deliberate: a part that went quiet is not necessarily a part that went away.

If you know the part really is gone — you pulled it yourself — use the Mark as removed action next to the component. Confirm, and the component leaves the card; the removal is recorded in the timeline.

The action is available to project administrators and project users, the same people who may edit the server. It works only on a component in Suspect missing: a component the agent still reports would simply come back on the next collection cycle.

Datacenters, Racks, and Positions

Infrastructure → Datacenters is where you describe the physical world. On the left is a tree of datacenters, their racks, and the equipment placed in them; on the right are the details of whatever you select.

A datacenter has a name, an address, and a description.

A rack belongs to a datacenter and has a name, a room, a row, a position, a height in units (42 by default), and a description.

A rack’s page draws its elevation: units from the top down, with Front and Rear tabs and a free-unit counter (Free: 12U / 42U). Occupied units carry the name of the equipment in them; a free unit is a link — click it and the placement form opens with the position and face already filled in. The equipment in the rack is also listed as a table beside the elevation.

Placing equipment asks for:

• the equipment itself, chosen from the Servers and Network devices groups;
• the rack, or — datacenter level — to record that the equipment is in this datacenter without saying where;
• Position (U) — the lowest unit the equipment occupies;
• Height (U) — how many units it takes;
• Face — Front or Rear.

Later you can Move the equipment to another position or Remove from rack to take it out.

A datacenter that still holds racks or equipment cannot be deleted, and neither can a rack that still holds equipment. Empty them first.

Access and API

Who can see the section

Infrastructure appears in a project’s side menu when the administrator has enabled hardware inventory in the platform settings. This is one platform-wide setting, not a per-project one: enabling it turns the section on for every project.

Any member of the project can browse the inventory and the placement. Creating and changing datacenters, racks, and placements — and marking a component as removed — is available to project administrators and project users.

API access to the inventory

The same inventory is available as a read-only HTTP API: servers and their hardware, components across the fleet, installation history, datacenters, racks, and placements, plus CSV export of the inventory, which the interface does not offer.

The token needs the Hardware inventory permission, and two rules apply to it:

• It can only be granted to a project-scoped token. A workspace-wide or system-wide token cannot carry it.
• It cannot share a token with metrics, logs, or traces. The inventory needs a token of its own.

Tokens are created in the project settings, in the API Tokens section — see Project API Tokens.

The endpoints, their parameters, and their responses are described in Hardware Inventory. The Storage Topology and OS Storage Stack blocks of the hardware card are not exposed through the API.

Troubleshooting

The server is missing from the Physical Servers list

The list holds physical servers only, so first make sure the machine is one: virtual machines are not inventoried and never appear here.

If it is a physical server, check in order:

1. The agent has not reported yet. A server appears only after its first inventory reaches the platform. Give it about 5 minutes after the agent starts.
2. The Show historical data switch is off. With the switch off, a server whose last inventory is older than two hours is filtered out. Turn it back on.
3. A search condition is still applied. The name box and the component conditions survive page reloads and bookmarks. Click Reset all.
4. The server is blacklisted. Blacklisted servers are excluded from the inventory entirely.

The server is listed but its hardware card is empty

The card reads Hardware inventory has not been synced yet when the platform has not yet processed a full inventory for this server. Data appears after the first collection cycle, within about 5 minutes.

The card shows the “Inventory stale” badge while the agent is alive

The badge means the last inventory arrived more than two hours ago — or never. The agent may well be sending metrics normally while its inventory reporting fails, for example when it cannot read the hardware information it needs. Check the Last scan date at the bottom of the card: if it is old, the inventory specifically is not getting through.

The server is badged “incomplete”

The agent collected part of the inventory and could not collect the rest — typically because RAID utilities or SMBIOS data were unavailable to it. What is on the card is real, but it may not be everything the server contains.

While a server’s data is incomplete, the platform will not remove components that stopped being reported, so nothing is lost while you sort the access out.

A component is stuck in “Suspect missing”

The platform waits for three consecutive inventories without the component before declaring it gone, and that wait is counted in inventories that brought news. A server whose hardware is not changing produces little news, so the count can advance slowly or not at all, and the component keeps its badge.

If you know the part is gone, use Mark as removed on the component. If the part is still in the server, check whether the agent can read it at all — a component that becomes unreadable behaves exactly like a component that was pulled.

Searching by disk manufacturer returns nothing

Disks have no Manufacturer field: the vendor string a disk reports is generic or empty, so the brand is stored as part of the model. Search by Model instead — SAMSUNG matches SAMSUNG MZQLB1T9HAJR-00007.

The Infrastructure section is missing from the side menu

Hardware inventory has not been enabled by the administrator. It is a platform-wide setting; ask your administrator to turn it on.