Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/misiektoja/steam_monitor

Real-time tracking of Steam players activities
https://github.com/misiektoja/steam_monitor

osint python steam steam-api steam-monitor

Last synced: 3 months ago
JSON representation

Real-time tracking of Steam players activities

Awesome Lists containing this project

README 

          
# steam_monitor



steam_monitor is a tool for real-time monitoring of **Steam players' activities**.





## Features



- **Real-time tracking** of Steam users' gaming activity (including detection when a user gets online/offline or plays games)

- **Basic statistics for user activity** (such as how long in different states, how long a game is played, overall time and the number of played games in the session etc.)

- **Detailed user information** display mode providing comprehensive Steam profile insights including list of **recently played & top games**, **recent achievements**, **total XP**, **earned badges**, **ban status** and **list of friends**

- **Steam level and total XP change tracking**

- **Friends list change tracking** (friends count and when available - added/removed friends)

- **Email notifications** for different events (when a player gets online/away/snooze/offline, starts/finishes/changes a game, Steam level and total XP changes, friends list changes or errors occur)

- **Saving all user activities and profile changes** with timestamps to a **CSV file**

- Possibility to **control the running copy** of the script via signals

- **Functional, procedural Python** (minimal OOP)





   steam_monitor_screenshot






## Table of Contents



1. [Requirements](#requirements)

2. [Installation](#installation)

   * [Install from PyPI](#install-from-pypi)

   * [Manual Installation](#manual-installation)

   * [Upgrading](#upgrading)

3. [Quick Start](#quick-start)

4. [Configuration](#configuration)

   * [Configuration File](#configuration-file)

   * [Steam Web API key](#steam-web-api-key)

   * [User Privacy Settings](#user-privacy-settings)

   * [SMTP Settings](#smtp-settings)

   * [Storing Secrets](#storing-secrets)

5. [Usage](#usage)

   * [Detailed User Information Display Mode](#detailed-user-information-display-mode)

   * [Monitoring Mode](#monitoring-mode)

   * [Email Notifications](#email-notifications)

   * [CSV Export](#csv-export)

   * [Check Intervals](#check-intervals)

   * [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix)

   * [Coloring Log Output with GRC](#coloring-log-output-with-grc)

6. [Change Log](#change-log)

7. [License](#license)





## Requirements



* Python 3.6 or higher

* Libraries: [steam](https://github.com/ValvePython/steam), `requests`, `python-dateutil`, `python-dotenv`



Tested on:



* **macOS**: Ventura, Sonoma, Sequoia, Tahoe

* **Linux**: Raspberry Pi OS (Bullseye, Bookworm, Trixie), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2024/2025

* **Windows**: 10, 11



It should work on other versions of macOS, Linux, Unix and Windows as well.





## Installation





### Install from PyPI



```sh

pip install steam_monitor

```





### Manual Installation



Download the *[steam_monitor.py](https://raw.githubusercontent.com/misiektoja/steam_monitor/refs/heads/main/steam_monitor.py)* file to the desired location.



Install dependencies via pip:



```sh

pip install "steam[client]" requests python-dateutil python-dotenv

```



Alternatively, from the downloaded *[requirements.txt](https://raw.githubusercontent.com/misiektoja/steam_monitor/refs/heads/main/requirements.txt)*:



```sh

pip install -r requirements.txt

```





### Upgrading



To upgrade to the latest version when installed from PyPI:



```sh

pip install steam_monitor -U

```



If you installed manually, download the newest *[steam_monitor.py](https://raw.githubusercontent.com/misiektoja/steam_monitor/refs/heads/main/steam_monitor.py)* file to replace your existing installation.





## Quick Start



- Grab your [Steam Web API key](#steam-web-api-key) and track the `steam_user_id` gaming activities:



```sh

steam_monitor  -u "your_steam_web_api_key"

```



Or if you installed [manually](#manual-installation):



```sh

python3 steam_monitor.py  -u "your_steam_web_api_key"

```



To get the list of all supported command-line arguments / flags:



```sh

steam_monitor --help

```





## Configuration





### Configuration File



Most settings can be configured via command-line arguments.



If you want to have it stored persistently, generate a default config template and save it to a file named `steam_monitor.conf`:



```sh

steam_monitor --generate-config > steam_monitor.conf



```



Edit the `steam_monitor.conf` file and change any desired configuration options (detailed comments are provided for each).





### Steam Web API key



You can get the Steam Web API key here: [http://steamcommunity.com/dev/apikey](http://steamcommunity.com/dev/apikey)



Provide the `STEAM_API_KEY` secret using one of the following methods:

 - Pass it at runtime with `-u` / `--steam-api-key`

 - Set it as an [environment variable](#storing-secrets) (e.g. `export STEAM_API_KEY=...`)

 - Add it to [.env file](#storing-secrets) (`STEAM_API_KEY=...`) for persistent use



Fallback:

 - Hard-code it in the code or config file



If you store the `STEAM_API_KEY` in a dotenv file you can update its value and send a `SIGHUP` signal to the process to reload the file with the new API key without restarting the tool. More info in [Storing Secrets](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).





### User Privacy Settings



In order to monitor Steam user activity, proper privacy settings need to be enabled on the monitored user account.



The user should go to [Steam Privacy Settings](https://steamcommunity.com/my/edit/settings).



The value in **My Profile → Game details** should be set to **Friends Only** or **Public**.





### SMTP Settings



If you want to use email notifications functionality, configure SMTP settings in the `steam_monitor.conf` file.



Verify your SMTP settings by using `--send-test-email` flag (the tool will try to send a test email notification):



```sh

steam_monitor --send-test-email

```





### Storing Secrets



It is recommended to store secrets like `STEAM_API_KEY` or `SMTP_PASSWORD` as either an environment variable or in a dotenv file.



Set environment variables using `export` on **Linux/Unix/macOS/WSL** systems:



```sh

export STEAM_API_KEY="your_steam_web_api_key"

export SMTP_PASSWORD="your_smtp_password"

```



On **Windows Command Prompt** use `set` instead of `export` and on **Windows PowerShell** use `$env`.



Alternatively store them persistently in a dotenv file (recommended):



```ini

STEAM_API_KEY="your_steam_web_api_key"

SMTP_PASSWORD="your_smtp_password"

```



By default the tool will auto-search for dotenv file named `.env` in current directory and then upward from it.



You can specify a custom file with `DOTENV_FILE` or `--env-file` flag:



```sh

steam_monitor  --env-file /path/.env-steam_monitor

```



 You can also disable `.env` auto-search with `DOTENV_FILE = "none"` or `--env-file none`:



```sh

steam_monitor  --env-file none

```



As a fallback, you can also store secrets in the configuration file or source code.





## Usage





### Detailed User Information Display Mode



To display comprehensive Steam profile information for a user without starting monitoring, type the player's Steam64 ID (`steam_user_id` in the example below) and use the `-i` / `--info` flag:



```sh

steam_monitor  -i

```



Or with a Steam community URL:



```sh

steam_monitor -r "https://steamcommunity.com/id/steam_username/" -i

```



If you have not set `STEAM_API_KEY` secret, you can use `-u` flag:



```sh

steam_monitor  -i -u "your_steam_web_api_key"

# or

steam_monitor -r "https://steamcommunity.com/id/steam_username/" -i -u "your_steam_web_api_key"

```



This mode displays detailed information including:

- Steam64 ID, display name, real name

- Country/region

- Current status and profile visibility

- Account creation date

- Profile URL

- Steam level, badges earned and XP statistics

- Ban status (VAC, Community, Economy)

- Friends count

- Top games by lifetime hours

- Recently played games with playtime statistics

- Hours played in the last 2 weeks



Optionally, you can also display **recently earned achievements** using the `--achievements` flag:



```sh

steam_monitor  -i --achievements                    # show recent achievements (default: 10)

steam_monitor  -i --achievements -n 20              # show up to 20 recent achievements

steam_monitor  -i --achievements --achievements-all-games  # check all owned games instead of only recently played

```



Recent achievements show game name, achievement name, description (if available) and earn time.



**How it works:**

- By default, the tool checks achievements from the user's recently played games (up to 15 games).

- If the recently played games list is empty or hidden, it automatically falls back to checking all owned games.

- Use `--achievements-all-games` to force checking all owned games instead of only recently played games. This is useful for users who haven't played recently, as their recently played list may be limited and older games with achievements might be missed.

- Achievements are sorted by unlock time (most recent first) and limited to the number specified with `-n` (default: 10).



The visibility of achievements depends on the user's Steam privacy settings for game details. If game details are set to "Private", achievements may not be accessible.



The tool displays this information and then exits (does not start monitoring).





### Monitoring Mode



To monitor specific user activity, just type the player's Steam64 ID (`steam_user_id` in the example below):



```sh

steam_monitor 

```



If you have not set `STEAM_API_KEY` secret, you can use `-u` flag:



```sh

steam_monitor  -u "your_steam_web_api_key"

```



If you do not know the user's Steam64 ID, but you know the Steam profile/community URL (which can be customized by the user), you can also run the tool with `-r` flag which will automatically resolve it to Steam64 ID:



```sh

steam_monitor -r "https://steamcommunity.com/id/steam_username/"

```



When monitoring starts, the tool displays user information including Steam64 ID, display name, real name (if available), country/region, current status, profile visibility, account creation date and profile URL.



By default, the tool looks for a configuration file named `steam_monitor.conf` in:

 - current directory

 - home directory (`~`)

 - script directory



 If you generated a configuration file as described in [Configuration](#configuration), but saved it under a different name or in a different directory, you can specify its location using the `--config-file` flag:



```sh

steam_monitor  --config-file /path/steam_monitor_new.conf

```



The tool runs until interrupted (`Ctrl+C`). Use `tmux` or `screen` for persistence.



You can monitor multiple Steam players by running multiple instances of the script.



The tool automatically saves its output to `steam_monitor_.log` file. The log file name can be changed via `ST_LOGFILE` configuration option and its suffix via `FILE_SUFFIX` / `-y` flag. Logging can be disabled completely via `DISABLE_LOGGING` / `-d` flag.



The tool also saves the timestamp and last status (after every change) to the `steam__last_status.json` file, so the last status is available after the restart of the tool.



To track when the user's **Steam level and total XP** changes:

- set `STEAM_LEVEL_XP_CHECK` to `True`

- or use the `--check-level-xp` flag



To track changes in the user's **friends list** (count and when available - added/removed friends):

- set `FRIENDS_CHECK` to `True`

- or use the `--check-friends` flag





### Email Notifications



To enable email notifications when a user gets online or offline:

- set `ACTIVE_INACTIVE_NOTIFICATION` to `True`

- or use the `-a` flag



```sh

steam_monitor  -a

```



To be informed when a user starts, stops or changes the played game:

- set `GAME_CHANGE_NOTIFICATION` to `True`

- or use the `-g` flag



```sh

steam_monitor  -g

```



To get email notifications about any changes in user status (online/away/snooze/offline):

- set `STATUS_NOTIFICATION` to `True`

- or use the `-s` flag



```sh

steam_monitor  -s

```



To get email notifications when the user's **Steam level and total XP** changes:

- set `STEAM_LEVEL_XP_NOTIFICATION` to `True`

- or use the `--notify-level-xp` flag



It requires Steam level and total XP tracking (`STEAM_LEVEL_XP_CHECK` / `--check-level-xp`) to be enabled.



```sh

steam_monitor  --check-level-xp --notify-level-xp

```



To get email notifications when the user's **friends list** changes:

- set `FRIENDS_NOTIFICATION` to `True`

- or use the `--notify-friends` flag



It requires friends tracking (`FRIENDS_CHECK` / `--check-friends`) to be enabled.



```sh

steam_monitor  --check-friends --notify-friends

```



To disable sending an email on errors (enabled by default):

- set `ERROR_NOTIFICATION` to `False`

- or use the `-e` flag



```sh

steam_monitor  -e

```



Make sure you defined your SMTP settings earlier (see [SMTP settings](#smtp-settings)).



Example email:





   steam_monitor_email_notifications






### CSV Export



If you want to save all reported activities of the Steam user to a CSV file, set `CSV_FILE` or use `-b` flag:



```sh

steam_monitor  -b steam_user_id.csv

```



The file will be automatically created if it does not exist.



If you want to save **profile-related changes** (Steam level changes, total XP changes, friends count changes and individual added/removed friends) to a **separate CSV file**, set `PROFILE_CSV_FILE` or use the `--profile-csv-file` flag:



```sh

steam_monitor  --profile-csv-file steam_user_id_profile.csv

```



Each row contains a timestamp, event type and associated values (for example: old/new Steam level or XP, friends count delta or one friend per row for added/removed friends, when available).





### Check Intervals



If you want to customize polling intervals, use `-k` and `-c` flags (or corresponding configuration options):



```sh

steam_monitor  -k 30 -c 120

```



* `STEAM_ACTIVE_CHECK_INTERVAL`, `-k`: check interval when the user is online, away or snooze (seconds)

* `STEAM_CHECK_INTERVAL`, `-c`: check interval when the user is offline (seconds)





### Signal Controls (macOS/Linux/Unix)



The tool has several signal handlers implemented which allow to change behavior of the tool without a need to restart it with new configuration options / flags.



List of supported signals:



| Signal | Description |

| ----------- | ----------- |

| USR1 | Toggle email notifications when user gets online or offline (-a) |

| USR2 | Toggle email notifications when user starts/stops/changes the game (-g) |

| CONT | Toggle email notifications for all user status changes (online/away/snooze/offline) (-s) |

| URG | Toggle email notifications for Steam level/XP changes (--notify-level-xp) |

| PIPE | Toggle email notifications for friends list changes (--notify-friends) |

| TRAP | Increase the check timer for player activity when user is online/away/snooze (by 30 seconds) |

| ABRT | Decrease check timer for player activity when user is online/away/snooze (by 30 seconds) |

| HUP | Reload secrets from .env file |



Send signals with `kill` or `pkill`, e.g.:



```sh

pkill -USR1 -f "steam_monitor "

```



As Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.





### Coloring Log Output with GRC



You can use [GRC](https://github.com/garabik/grc) to color logs.



Add to your GRC config (`~/.grc/grc.conf`):



```

# monitoring log file

.*_monitor_.*\.log

conf.monitor_logs

```



Now copy the [conf.monitor_logs](https://raw.githubusercontent.com/misiektoja/steam_monitor/refs/heads/main/grc/conf.monitor_logs) to your `~/.grc/` and log files should be nicely colored when using `grc` tool.



Example:



```sh

grc tail -F -n 100 steam_monitor_.log

```





## Change Log



See [RELEASE_NOTES.md](https://github.com/misiektoja/steam_monitor/blob/main/RELEASE_NOTES.md) for details.





## License



Licensed under GPLv3. See [LICENSE](https://github.com/misiektoja/steam_monitor/blob/main/LICENSE).