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.)
• Email notifications for different events (when a player gets online/away/snooze/offline, starts/finishes/changes a game or errors occur)
• Saving all user activities with timestamps to a CSV file
• Possibility to control the running copy of the script via signals

Table of Contents

1. Requirements
2. Installation
   • Install from PyPI
   • Manual Installation
3. Quick Start
4. Configuration
   • Configuration File
   • Steam Web API key
   • User Privacy Settings
   • SMTP Settings
   • Storing Secrets
5. Usage
   • Monitoring Mode
   • Email Notifications
   • CSV Export
   • Check Intervals
   • Signal Controls (macOS/Linux/Unix)
   • Coloring Log Output with GRC
6. Change Log
7. License

Requirements

• Python 3.6 or higher
• Libraries: steam, requests, python-dateutil, python-dotenv

Tested on:

• macOS: Ventura, Sonoma, Sequoia
• Linux: Raspberry Pi OS (Bullseye, Bookworm), Ubuntu 24, 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

pip install steam_monitor

Manual Installation

Download the steam_monitor.py file to the desired location.

Install dependencies via pip:

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

Alternatively, from the downloaded requirements.txt:

pip install -r requirements.txt

Quick Start

• Grab your Steam Web API key and track the steam_user_id gaming activities:

steam_monitor <steam_user_id> -u "your_steam_web_api_key"

Or if you installed manually:

python3 steam_monitor.py <steam_user_id> -u "your_steam_web_api_key"

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

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:

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

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 (e.g. export STEAM_API_KEY=...)
• Add it to .env file (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 and Signal Controls (macOS/Linux/Unix).

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.

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):

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:

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):

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:

steam_monitor <steam_user_id> --env-file /path/.env-steam_monitor

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

steam_monitor <steam_user_id> --env-file none

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

Usage

Monitoring Mode

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

steam_monitor <steam_user_id>

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

steam_monitor <steam_user_id> -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:

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

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, but saved it under a different name or in a different directory, you can specify its location using the --config-file flag:

steam_monitor <steam_user_id> --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_<user_steam_id/file_suffix>.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_<user_display_name>_last_status.json file, so the last status is available after the restart of the tool.

Email Notifications

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

• set ACTIVE_INACTIVE_NOTIFICATION to True
• or use the -a flag

steam_monitor <steam_user_id> -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

steam_monitor <steam_user_id> -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

steam_monitor <steam_user_id> -s

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

• set ERROR_NOTIFICATION to False
• or use the -e flag

steam_monitor <steam_user_id> -e

Make sure you defined your SMTP settings earlier (see SMTP settings).

Example email:

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:

steam_monitor <steam_user_id> -b steam_user_id.csv

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

Check Intervals

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

steam_monitor <steam_user_id> -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)
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.:

pkill -USR1 -f "steam_monitor <steam_user_id>"

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 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 to your ~/.grc/ and log files should be nicely colored when using grc tool.

Example:

grc tail -F -n 100 steam_monitor_<user_steam_id/file_suffix>.log

Change Log

See RELEASE_NOTES.md for details.

License

Licensed under GPLv3. See LICENSE.