search

AstraExt / astra-monitor

Resource Monitor for GNOME shell
GNU General Public License v3.0
320 stars 18 forks source link

readme

Astra Monitor

Table of Contents

Overview

Astra Monitor is a cutting-edge, fully customizable, and performance-focused monitoring extension for GNOME's top bar. It's an all-in-one solution for those seeking to keep a close eye on their system's performance metrics, like CPU, GPU, RAM, disk usage, network statistics, and sensor readings. Currently in its early stages of development, Astra Monitor is constantly evolving with an eye towards future enhancements and additional features.

Key Features:

Check the COMPARISON.md file for a detailed comparative analysis of Astra Monitor features, performance and benchmarks vs similar projects within our domain.

Screenshots:

NOTE: The screenshots below are from an outdated version of the extension and may not reflect the current release.

High Customization Level

Example 1:
Screenshot1
Example 2:
Screenshot2
Example 3:
Screenshot3

Rich Menu Information

Screenshot9 Screenshot10 Screenshot11

Detailed Resource Information

Screenshot4 Screenshot5 Screenshot7

Screenshot6 Screenshot8

Roadmap

As Astra Monitor is in beta stage of development, we have an ambitious roadmap planned:

Beta
3/6		 Release
0/5
Q3 2024 Q4 2024 Q1 2025 Q2 2025
✅
Root Process Monitoring
(storage)		 ⌛
Help & Doc		 🔲
Themes		 🔲
User Custom Commands
✅
Network Process Monitoring		 🔲
Battery Monitoring
🔲
Continuous Monitoring Mode


To check our FULL Roadmap, including past releases, please refer to the ROADMAP.md file.

Your feedback is invaluable in shaping Astra Monitor's development journey. Do you have any new features to suggest? We are very happy to receive suggestions. The best way to see new features become reality as quickly as possible is through direct contributions or donations. Donations will result in more development time dedicated to the project. If you would like to contribute, please refer to the contribution guidelines.

Installation

Astra Monitor can be installed on any Linux distribution supporting GNOME version 45.0 or higher.

GNOME Extensions Manager

Most distributions with GNOME support the installation of extensions directly from the GNOME Extensions website. Check if your distro already has the GNOME Extensions Manager app installed. If not, you can install it from your package manager / software center.

Using the GNOME Extensions Website

Follow these simple steps:

  1. Visit the GNOME Shell Extensions page.
  2. Search for "Astra Monitor".
  3. Click on the extension and follow the on-screen instructions to install.

NixOS

If you are using NixOS, you can install Astra Monitor adding the following to your configuration.nix:

{ config, pkgs, ... }:

{
  environment.systemPackages = with pkgs; [
    gnomeExtensions.astra-monitor
  ];
}

Requirements

Astra Monitor works out of the box with no additional dependencies. However, some optional dependencies can enhance the data displayed by the extension. These tools and the impact of their absence are clearly listed in the preferences panel of the extension.

Screenshot13

Libgtop

If you want to use Libgtop as a data source you may need to install the libgtop package. This package is not required for the extension to work, but it is recommended for a better experience.

Here is a non-exhaustive list of how to install libgtop on some popular Linux distributions:

Ubuntu/Debian

sudo apt install gir1.2-gtop-2.0

Fedora

sudo dnf install libgtop2-devel

Arch / Manjaro

sudo pacman -Syu libgtop

openSUSE

sudo zypper install libgtop-devel

NixOS

On NixOS, you may need to add the following to your configuration.nix:

environment.variables = {
    GI_TYPELIB_PATH = "/run/current-system/sw/lib/girepository-1.0";
};
environment.systemPackages = with pkgs; [
    libgtop
];

Nethogs

Nethogs is an optional dependency for the extension. It is required to monitor network I/O activity of processes. If you want to use this feature, you may need to install nethogs package. Nethogs requires root access, which can be achieved in two ways:

  1. On-demand: Click the network top processes header to grant permission and start nethogs with elevated privileges for about 60 seconds.
  2. Always-on: Grant nethogs the necessary capabilities (cap_net_admin and cap_net_raw=ep) to run as a privileged service. The extension will automatically detect and use it in this configuration.

Here's how to grant the necessary capabilities to nethogs on most distros:

  1. First, locate the nethogs binary:

    which nethogs

  2. Grant the capabilities using setcap:

    sudo setcap cap_net_admin,cap_net_raw=ep $(which nethogs)

  3. Verify the capabilities were set correctly:

    getcap $(which nethogs)

    You should see output similar to:

    /usr/sbin/nethogs = cap_net_admin,cap_net_raw=ep

Note: The exact path to nethogs may vary depending on your system. Adjust the commands accordingly if which nethogs returns a different path.

After granting these capabilities, restart GNOME Shell and Astra Monitor will automatically detect and use nethogs without requiring elevated privileges each time.

NixOS

On NixOS, to grant the capabilities to nethogs, you may need to add the following to your configuration.nix:

environment.systemPackages = with pkgs; [
    nethogs
];

security.wrappers = {
    nethogs = {
        source = "${pkgs.nethogs}/bin/nethogs";
        capabilities = "cap_net_admin=ep cap_net_raw=ep";
        owner = "root";
        group = "root";
        permissions = "u+rx,g+x,o+x";
    };
};

Note: This is an example configuration and may vary depending on your specific NixOS setup. Adjust the configuration as needed for your system.

Usage

Once installed, Astra Monitor can be accessed and configured directly from the GNOME extensions tool. You can customize what system resources to monitor and how the information is displayed, tailoring the experience to your need.

Licensing

Astra Monitor is licensed under the GNU General Public License v3.0 (GPL-3.0), a widely used free software license that guarantees end users the freedom to run, study, share, and modify the software.

Translations

Astra Monitor is currently available in English, German, Czech and Russian. If you would like to contribute with a translation, please refer to these guidelines:

  1. Fork the repository: Fork the repository and clone it to your local machine.
  2. Create/Update the translation file: Create or update the translation file for your language. Translation files are located in po folder. The file name is the language code (e.g. it.po for Italian). You can use Poedit to edit the translation files.
  3. Compile the translation file: Compile the translation file using the ./i18n.sh script.
  4. Test the translation: Test the translation by running the extension with the ./test.sh script or by packing it with the ./pack.sh script and installing it.
  5. Submit a pull request: Submit a pull request with your changes.

NOTE: TypeScript compilation is required to generate JavaScript files from the source code. Be sure to have TypeScript installed or search online how to install it on your system.

Building and Testing

Astra Monitor is written in TypeScript and uses the GNOME Shell Extension API.

You may run npm install, yarn install with Yarn or nnpm install using NNPM, to install all dependencies.

Various scripts are provided to facilitate packing and testing of the extension. These scripts are located in the root directory of the project and can be run from there. They are used solely with the scope of facilitating my own development process. Feel free to use or modify them to suit your needs.

Scripts

Contributing

Contributions to Astra Monitor are highly encouraged and appreciated. We welcome all forms of contributions, from bug reporting to feature suggestions, and direct code contributions. To contribute:

  1. Report Bugs/Request Features: Use the GitHub issues page to report bugs or suggest new features.
  2. Code Contributions: Feel free to make changes and submit a pull request.
  3. Feedback: Share your experience and suggestions to help improve Astra Monitor.

Please refer to our contribution guidelines for more detailed instructions.

Donations

Astra Monitor is a free and open-source project: we rely on the support of our community. Donations are a vital part of sustaining our project's growth and success. Your contributions enable us to dedicate more time to development and bring the community's most requested features to life.

How Your Donations Help

How to Donate

You can donate through your preferred platform. Any amount is greatly appreciated and makes a significant impact.

Buy us a coffee, and help us keep Astra Monitor alive and thriving!

Become a Patron to support our project and more!

Donate through Ko-Fi, and help our community grow!

Acknowledgments

Astra Monitor is a project inspired by the concepts of iStat Menus and TopHat by Todd Kulesza, adapted and evolved for the GNOME environment. This extension is a tribute to the innovation in system monitoring tools and is driven by the passion and contributions of the open-source community.

Star History

Star History Chart