lol_monitor is a tool for real-time monitoring of LoL (League of Legends) players' activities.

• Real-time tracking of LoL users' gaming activity (including detection when a user starts or finishes a match)
• Most important statistics for finished matches:
  • game mode
  • victory or defeat
  • kills, deaths, assists
  • champion name
  • achieved level
  • role
  • lane
  • team members
• Email notifications for different events (player starts or finishes a match, match summary, errors)
• Saving all gaming activities with timestamps to a CSV file
• Possibility to control the running copy of the script via signals

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

• Python 3.12 or higher
• Libraries: pulsefire, 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.

pip install lol_monitor

Download the lol_monitor.py file to the desired location.

Install dependencies via pip:

pip install pulsefire requests python-dateutil python-dotenv

Alternatively, from the downloaded requirements.txt:

pip install -r requirements.txt

• Grab your Riot API key and track the gaming activities of the riot_id_name#tag in selected region:

lol_monitor <riot_id_name#tag> <region> -r "your_riot_api_key"

Or if you installed manually:

python3 lol_monitor.py <riot_id_name#tag> <region> -r "your_riot_api_key"

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

lol_monitor --help

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 lol_monitor.conf:

lol_monitor --generate-config > lol_monitor.conf

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

Get the development Riot API key valid for 24 hours here: https://developer.riotgames.com

It is recommended to apply for persistent personal or production Riot API key here: https://developer.riotgames.com/app-type

It takes few days to get the approval.

Provide the RIOT_API_KEY secret using one of the following methods:

• Pass it at runtime with -r / --riot-api-key
• Set it as an environment variable (e.g. export RIOT_API_KEY=...)
• Add it to .env file (RIOT_API_KEY=...) for persistent use

Fallback:

• Hard-code it in the code or config file

If you store the RIOT_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).

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

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

lol_monitor --send-test-email

It is recommended to store secrets like RIOT_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 RIOT_API_KEY="your_riot_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):

RIOT_API_KEY="your_riot_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:

lol_monitor <riot_id_name#tag> <region> --env-file /path/.env-lol_monitor

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

lol_monitor <riot_id_name#tag> <region> --env-file none

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

To monitor specific user activity, just type player's LoL Riot ID & region as command-line arguments (riot_id_name#tag and region in the example below):

lol_monitor <riot_id_name#tag> <region>

If you have not setRIOT_API_KEY secret, you can use -r flag:

lol_monitor <riot_id_name#tag> <region> -r "your_riot_api_key"

LoL Riot ID consists of Riot ID game name (riot_id_name in the example above) and tag line (#tag).

For the region you need to use the short form of it. You can find the list below:

By default, the tool looks for a configuration file named lol_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:

lol_monitor <riot_id_name#tag> <region> --config-file /path/lol_monitor_new.conf

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

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

The tool automatically saves its output to lol_monitor_<riot_id_name>.log file. It can be changed in the settings via LOL_LOGFILE configuration option or disabled completely via DISABLE_LOGGING / -d flag.

There is also another mode of the tool which prints and/or saves the recent matches for the user (-l flag). You can also add -n to define how many recent matches you want to display/save; by default, it shows the last 2 matches:

lol_monitor <riot_id_name#tag> <region> -l -n 25

You can also define the range of matches to display/save by specifying the minimal match to display (-m flag). So for example, to display recent matches in the range of 20-50:

lol_monitor <riot_id_name#tag> <region> -l -m 20 -n 50

If you specify the -b flag (with a CSV file name) together with the -l flag, it will not only display the recent matches, but also save them to the specified CSV file. For example, to display and save recent matches in the range of 5-10 for the user:

lol_monitor <riot_id_name#tag> <region> -l -m 5 -n 10 -b lol_games_riot_id_name.csv

To enable email notifications when user's playing status changes:

• set STATUS_NOTIFICATION to True
• or use the -s flag

lol_monitor <riot_id_name#tag> <region> -s

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

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

lol_monitor <riot_id_name#tag> <region> -e

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

Example email:

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

lol_monitor <riot_id_name#tag> <region> -b lol_games_riot_id_name.csv

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

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

lol_monitor <riot_id_name#tag> <region> -k 60 -c 120

• LOL_ACTIVE_CHECK_INTERVAL, -k: check interval when the user is in a game (seconds)
• LOL_CHECK_INTERVAL, -c: check interval when the user is NOT in a game (seconds)

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:

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

pkill -USR1 -f "lol_monitor <riot_id_name#tag> <region>"

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

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 lol_monitor_<riot_id_name>.log

See RELEASE_NOTES.md for details.

Licensed under GPLv3. See LICENSE.