=================================
Standalone Debian Package Install
=================================

For SR-IOV/GIM hypervisor hosts, see :doc:`deb-package-sriov` instead.

System Requirements
===================

Before installing the AMD GPU Metrics Exporter, you need to install the "AMDGPU" driver from the Radeon repository.
Please ensure that your system meets the following requirements:

- **Operating System**: Ubuntu 22.04 or Ubuntu 24.04
- **ROCm / AMDGPU Driver**: ROCm 6.2.0 or later (includes the compatible AMDGPU driver)

Installation
===================

Step 1: Install System Prerequisites
------------------------------------

1. Install Linux headers and modules:

   .. code-block:: bash

      sudo apt update
      sudo apt install "linux-headers-$(uname -r)" "linux-modules-extra-$(uname -r)"

2. Add user to required groups:

   .. code-block:: bash

      sudo usermod -a -G render,video $LOGNAME 

Step 2: Install AMDGPU Driver
------------------------------

.. note::
   For the most up-to-date information on installing dkms drivers please see the `ROCm Install Quick Start <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html>`_ page.

1. Download the driver from the Radeon repository (`repo.radeon.com <https://repo.radeon.com/amdgpu-install>`_) for your operating system. For example, to install ROCm 7.2.3 on Ubuntu 22.04:

   .. code-block:: bash

      wget https://repo.radeon.com/amdgpu-install/7.2.3/ubuntu/jammy/amdgpu-install_7.2.3.70203-1_all.deb
      sudo apt install ./amdgpu-install_7.2.3.70203-1_all.deb
      sudo apt update

   For other ROCm versions, browse `repo.radeon.com/amdgpu-install <https://repo.radeon.com/amdgpu-install>`_ to find the correct ``.deb`` for your OS.

2. Install the driver:

   .. code-block:: bash

      sudo apt install amdgpu-dkms
      sudo reboot

3. Load the driver module:

   .. code-block:: bash

      sudo modprobe amdgpu

Step 3: Install the APT Prerequisites for Metrics Exporter
-----------------------------------------------------------

1. Update the package list and install necessary tools, keyrings and keys:

   .. code-block:: bash

      # Install necessary tools  
      sudo apt update
      sudo apt install vim wget gpg

      # Create the keyrings directory with the appropriate permissions:
      sudo mkdir --parents --mode=0755 /etc/apt/keyrings

      # Download the ROCm GPG key and add it to the keyrings:
      wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null

2. Edit the sources list to add the Device Metrics Exporter repository:

   .. tab-set::

      .. tab-item:: ubuntu 22.04

         .. code-block:: bash

            deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/device-metrics-exporter/apt/1.5.2 jammy main

      .. tab-item:: ubuntu 24.04

         .. code-block:: bash

            deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/device-metrics-exporter/apt/1.5.2 noble main


3. Update the package list again:

   .. code-block:: bash

      sudo apt update

Step 4: Install Metrics Exporter
------------------------------------------------------

1. Install the Device Metrics Exporter:

   .. code-block:: bash

      sudo apt install amdgpu-exporter

2. Enable and start services:

   .. code-block:: bash

      sudo systemctl enable amd-metrics-exporter.service
      sudo systemctl start amd-metrics-exporter.service

3. Check service status:

   .. code-block:: bash

      sudo systemctl status amd-metrics-exporter.service

.. note::
   Before performing GPU driver unload/upgrade or partition operations, services must be stopped. See the `Service Management for Driver and Partition Operations`_ section for detailed instructions.

Metrics Exporter Default Settings
====================================

- **Metrics endpoint:** ``http://localhost:5000/metrics``
- **Configuration file:** ``/etc/metrics/config.json``
- **GPU Agent socket:** ``/var/run/gpuagent.sock`` (Unix Domain Socket)

The Exporter HTTP port is configurable via the `ServerPort` field in the configuration file.

Metrics Exporter Custom Configuration
======================================

Changing configuration config.json
----------------------------------

If you need to customize ports or settings:


1. Edit the amd-metrics-exporter service file:

   .. code-block:: bash

      sudo vi /lib/systemd/system/amd-metrics-exporter.service

2. Update the `ExecStart` line to read in the config.json file:

   .. code-block:: bash

      ExecStart=/usr/local/bin/amd-metrics-exporter -amd-metrics-config /etc/metrics/config.json

3. Reload systemd:

   .. code-block:: bash

      sudo systemctl daemon-reload

Custom Socket Configuration - Change GPU Agent Socket Path (Advanced)
---------------------------------------------------------------------

By default, GPU Agent uses Unix Domain Socket at ``/var/run/gpuagent.sock`` for communication with the metrics exporter.

To change the socket path:

1. Edit the GPU Agent service file:

   .. code-block:: bash

      sudo vi /lib/systemd/system/gpuagent.service

2. Update `ExecStart` with custom socket path:

   .. code-block:: bash

      ExecStart=/usr/local/bin/gpuagent -s /path/to/custom.sock

3. Edit the Metrics Exporter service file:

   .. code-block:: bash

      sudo vi /lib/systemd/system/amd-metrics-exporter.service

4. Update `ExecStart` to use the same socket path:

   .. code-block:: bash

      ExecStart=/usr/local/bin/amd-metrics-exporter -s /path/to/custom.sock

5. Restart both services:

   .. code-block:: bash
      
      sudo systemctl restart gpuagent.service
      sudo systemctl restart amd-metrics-exporter.service
      sudo systemctl daemon-reload

Change Metrics Exporter Port
----------------------------

1. Edit the configuration file:

   .. code-block:: bash

      sudo vi /etc/metrics/config.json

2. Update `ServerPort` to your desired port

3. Restart Metrics Exporter service:

   .. code-block:: bash
      sudo systemctl restart amd-metrics-exporter.service
      sudo systemctl daemon-reload

Stop Metrics Exporter
---------------------

To stop the Metrics Exporter service, run:
   .. code-block:: bash

      sudo systemctl stop amd-metrics-exporter.service
      sudo systemctl stop gpuagent.service 
      sudo systemctl daemon-reload

Confirm Metrics Exporter is Running
------------------------------------

To confirm that the Metrics Exporter is running and accessible, you can use the following command:

   .. code-block:: bash

      systemctl status amd-metrics-exporter.service
      systemctl status gpuagent.service

Service Management for Driver and Partition Operations
------------------------------------------------------

The GPU Metrics Exporter and GPU Agent services must be stopped before performing the following operations:

- GPU driver unload or upgrade
- GPU partition configuration changes

**Required Steps:**

1. **Stop Services**: See `Stop Metrics Exporter`_ section for instructions on stopping both services
2. **Perform driver upgrade or partition operations**
3. **Restart Services**: Use the enable and start commands from `Step 4: Install Metrics Exporter`_
4. **Verify Services**: See `Confirm Metrics Exporter is Running`_ section to verify both services are running correctly

Removing Metrics Exporter and other components
------------------------------------------------

To remove this application, follow these commands in reverse order:

1. Uninstall the Metrics Exporter:

   - Ensure the .deb package is removed:

     .. code-block:: bash

        sudo dpkg -r amdgpu-exporter
        sudo apt-get purge amdgpu-exporter

2. (Optional) If you would also like to uninstall the AMDGPU Driver:

   - Uninstall any associated DKMS packages:

     .. code-block:: bash

        sudo dpkg -r amdgpu-install

   - Unload the driver module:

     .. code-block:: bash

        sudo modprobe -r amdgpu

3. (Optional) If you would also like to remove the system prerequisites that were installed:

   - Remove Linux header and module packages:

     .. code-block:: bash

        sudo apt remove linux-headers-$(uname -r)
        sudo apt remove linux-modules-extra-$(uname -r)

   - Remove the user from groups:

     .. code-block:: bash

        sudo gpasswd -d $LOGNAME render
        sudo gpasswd -d $LOGNAME video