{"id":22222347,"url":"https://github.com/misiektoja/lol_monitor","last_synced_at":"2025-10-04T01:47:07.924Z","repository":{"id":235629662,"uuid":"791031684","full_name":"misiektoja/lol_monitor","owner":"misiektoja","description":"Real-time tracking of LoL (League of Legends) players activities","archived":false,"fork":false,"pushed_at":"2025-06-13T02:12:48.000Z","size":3977,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-15T22:53:35.122Z","etag":null,"topics":["leauge-of-legends","lol","lol-monitor","osint","pulsefire","python","riot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/misiektoja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-24T01:07:01.000Z","updated_at":"2025-07-07T16:24:14.000Z","dependencies_parsed_at":"2025-06-09T02:27:27.947Z","dependency_job_id":"121a1707-af33-4b46-b72c-9ce7336ea9f0","html_url":"https://github.com/misiektoja/lol_monitor","commit_stats":null,"previous_names":["misiektoja/lol_monitor"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/misiektoja/lol_monitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misiektoja%2Flol_monitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misiektoja%2Flol_monitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misiektoja%2Flol_monitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misiektoja%2Flol_monitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/misiektoja","download_url":"https://codeload.github.com/misiektoja/lol_monitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/misiektoja%2Flol_monitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276169640,"owners_count":25596952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-20T02:00:10.207Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["leauge-of-legends","lol","lol-monitor","osint","pulsefire","python","riot"],"created_at":"2024-12-02T23:18:04.445Z","updated_at":"2025-10-04T01:47:07.878Z","avatar_url":"https://github.com/misiektoja.png","language":"Python","funding_links":[],"categories":["[↑](#-table-of-contents) Gaming Platforms"],"sub_categories":["[↑](#-table-of-contents) GitHub"],"readme":"# lol_monitor\n\nlol_monitor is a tool for real-time monitoring of LoL (League of Legends) players' activities. \n\n\u003ca id=\"features\"\u003e\u003c/a\u003e\n## Features\n\n- Real-time tracking of LoL users' gaming activity (including detection when a user starts or finishes a match)\n- Most important statistics for finished matches:\n  - game mode\n  - victory or defeat\n  - kills, deaths, assists\n  - champion name\n  - achieved level\n  - role\n  - lane\n  - team members\n- Email notifications for different events (player starts or finishes a match, match summary, errors)\n- Saving all gaming activities with timestamps to a CSV file\n- Possibility to control the running copy of the script via signals\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"https://raw.githubusercontent.com/misiektoja/lol_monitor/refs/heads/main/assets/lol_monitor.png\" alt=\"lol_monitor_screenshot\" width=\"70%\"/\u003e\n\u003c/p\u003e\n\n\u003ca id=\"table-of-contents\"\u003e\u003c/a\u003e\n## Table of Contents\n\n1. [Requirements](#requirements)\n2. [Installation](#installation)\n   * [Install from PyPI](#install-from-pypi)\n   * [Manual Installation](#manual-installation)\n3. [Quick Start](#quick-start)\n4. [Configuration](#configuration)\n   * [Configuration File](#configuration-file)\n   * [Riot API Key](#riot-api-key)\n   * [SMTP Settings](#smtp-settings)\n   * [Storing Secrets](#storing-secrets)\n5. [Usage](#usage)\n   * [Monitoring Mode](#monitoring-mode)\n   * [Listing Mode](#listing-mode)\n   * [Email Notifications](#email-notifications)\n   * [CSV Export](#csv-export)\n   * [Check Intervals](#check-intervals)\n   * [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix)\n   * [Coloring Log Output with GRC](#coloring-log-output-with-grc)\n6. [Change Log](#change-log)\n7. [License](#license)\n\n\u003ca id=\"requirements\"\u003e\u003c/a\u003e\n## Requirements\n\n* Python 3.12 or higher\n* Libraries: [pulsefire](https://github.com/iann838/pulsefire), `requests`, `python-dateutil`, `python-dotenv`\n\nTested on:\n\n* **macOS**: Ventura, Sonoma, Sequoia\n* **Linux**: Raspberry Pi OS (Bullseye, Bookworm), Ubuntu 24, Rocky Linux 8.x/9.x, Kali Linux 2024/2025\n* **Windows**: 10, 11\n\nIt should work on other versions of macOS, Linux, Unix and Windows as well.\n\n\u003ca id=\"installation\"\u003e\u003c/a\u003e\n## Installation\n\n\u003ca id=\"install-from-pypi\"\u003e\u003c/a\u003e\n### Install from PyPI\n\n```sh\npip install lol_monitor\n```\n\n\u003ca id=\"manual-installation\"\u003e\u003c/a\u003e\n### Manual Installation\n\nDownload the *[lol_monitor.py](https://raw.githubusercontent.com/misiektoja/lol_monitor/refs/heads/main/lol_monitor.py)* file to the desired location.\n\nInstall dependencies via pip:\n\n```sh\npip install pulsefire requests python-dateutil python-dotenv\n```\n\nAlternatively, from the downloaded *[requirements.txt](https://raw.githubusercontent.com/misiektoja/lol_monitor/refs/heads/main/requirements.txt)*:\n\n```sh\npip install -r requirements.txt\n```\n\n\u003ca id=\"quick-start\"\u003e\u003c/a\u003e\n## Quick Start\n\n- Grab your [Riot API key](#riot-api-key) and track the gaming activities of the `riot_id_name#tag` in selected `region`:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -r \"your_riot_api_key\"\n```\n\nOr if you installed [manually](#manual-installation):\n\n```sh\npython3 lol_monitor.py \u003criot_id_name#tag\u003e \u003cregion\u003e -r \"your_riot_api_key\"\n```\n\nTo get the list of all supported command-line arguments / flags:\n\n```sh\nlol_monitor --help\n```\n\n\u003ca id=\"configuration\"\u003e\u003c/a\u003e\n## Configuration\n\n\u003ca id=\"configuration-file\"\u003e\u003c/a\u003e\n### Configuration File\n\nMost settings can be configured via command-line arguments.\n\nIf you want to have it stored persistently, generate a default config template and save it to a file named `lol_monitor.conf`:\n\n```sh\nlol_monitor --generate-config \u003e lol_monitor.conf\n\n```\n\nEdit the `lol_monitor.conf` file and change any desired configuration options (detailed comments are provided for each).\n\n\u003ca id=\"riot-api-key\"\u003e\u003c/a\u003e\n### Riot API Key\n\nGet the development Riot API key valid for 24 hours here: [https://developer.riotgames.com](https://developer.riotgames.com)\n\nIt is recommended to apply for persistent personal or production Riot API key here: [https://developer.riotgames.com/app-type](https://developer.riotgames.com/app-type)\n\nIt takes few days to get the approval.\n\nProvide the `RIOT_API_KEY` secret using one of the following methods:\n - Pass it at runtime with `-r` / `--riot-api-key`\n - Set it as an [environment variable](#storing-secrets) (e.g. `export RIOT_API_KEY=...`)\n - Add it to [.env file](#storing-secrets) (`RIOT_API_KEY=...`) for persistent use\n\nFallback:\n - Hard-code it in the code or config file\n\nIf 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](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).\n\n\u003ca id=\"smtp-settings\"\u003e\u003c/a\u003e\n### SMTP Settings\n\nIf you want to use email notifications functionality, configure SMTP settings in the `lol_monitor.conf` file. \n\nVerify your SMTP settings by using `--send-test-email` flag (the tool will try to send a test email notification):\n\n```sh\nlol_monitor --send-test-email\n```\n\n\u003ca id=\"storing-secrets\"\u003e\u003c/a\u003e\n### Storing Secrets\n\nIt is recommended to store secrets like `RIOT_API_KEY` or `SMTP_PASSWORD` as either an environment variable or in a dotenv file.\n\nSet environment variables using `export` on **Linux/Unix/macOS/WSL** systems:\n\n```sh\nexport RIOT_API_KEY=\"your_riot_api_key\"\nexport SMTP_PASSWORD=\"your_smtp_password\"\n```\n\nOn **Windows Command Prompt** use `set` instead of `export` and on **Windows PowerShell** use `$env`.\n\nAlternatively store them persistently in a dotenv file (recommended):\n\n```ini\nRIOT_API_KEY=\"your_riot_api_key\"\nSMTP_PASSWORD=\"your_smtp_password\"\n```\n\nBy default the tool will auto-search for dotenv file named `.env` in current directory and then upward from it. \n\nYou can specify a custom file with `DOTENV_FILE` or `--env-file` flag:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e --env-file /path/.env-lol_monitor\n```\n\n You can also disable `.env` auto-search with `DOTENV_FILE = \"none\"` or `--env-file none`:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e --env-file none\n```\n\nAs a fallback, you can also store secrets in the configuration file or source code.\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n## Usage\n\n\u003ca id=\"monitoring-mode\"\u003e\u003c/a\u003e\n### Monitoring Mode\n\nTo monitor specific user activity, just type player's LoL Riot ID \u0026 region as command-line arguments (`riot_id_name#tag` and `region` in the example below):\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e\n```\n\nIf you have not set`RIOT_API_KEY` secret, you can use `-r` flag:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -r \"your_riot_api_key\"\n```\n\nLoL Riot ID consists of Riot ID game name (`riot_id_name` in the example above) and tag line (`#tag`). \n\nFor the `region` you need to use the short form of it. You can find the list below:\n\n| Region short form | Description |\n| ----------- | ----------- |\n| eun1 | Europe Nordic \u0026 East (EUNE) |\n| euw1 | Europe West (EUW) |\n| tr1 | Turkey (TR1) |\n| ru | Russia |\n| na1 | North America (NA) - now the sole NA endpoint |\n| br1 | Brazil (BR) |\n| la1 | Latin America North (LAN) |\n| la2 | Latin America South (LAS) |\n| jp1 | Japan (JP) |\n| kr | Korea (KR) |\n| sg2 | Southeast Asia (SEA) - Singapore, Malaysia, Indonesia (+ Thailand \u0026 Philippines since Jan 9, 2025) |\n| tw2 | Taiwan, Hong Kong \u0026 Macao (TW/HK/MO) |\n| vn2 | Vietnam (VN) |\n| oc1 | Oceania (OC) |\n\nBy default, the tool looks for a configuration file named `lol_monitor.conf` in:\n - current directory \n - home directory (`~`)\n - script directory \n\n 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:\n\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e --config-file /path/lol_monitor_new.conf\n```\n\nThe tool runs until interrupted (`Ctrl+C`). Use `tmux` or `screen` for persistence.\n\nYou can monitor multiple LoL players by running multiple instances of the script.\n\nThe tool automatically saves its output to `lol_monitor_\u003criot_id_name\u003e.log` file. It can be changed in the settings via `LOL_LOGFILE` configuration option or disabled completely via `DISABLE_LOGGING` / `-d` flag.\n\n\u003ca id=\"listing-mode\"\u003e\u003c/a\u003e\n### Listing Mode\n\nThere 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:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -l -n 25\n```\n\nYou 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:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -l -m 20 -n 50\n```\n\nIf 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:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -l -m 5 -n 10 -b lol_games_riot_id_name.csv\n```\n\n\u003ca id=\"email-notifications\"\u003e\u003c/a\u003e\n### Email Notifications\n\nTo enable email notifications when user's playing status changes:\n- set `STATUS_NOTIFICATION` to `True`\n- or use the `-s` flag\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -s\n```\n\nTo disable sending an email on errors (enabled by default):\n- set `ERROR_NOTIFICATION` to `False`\n- or use the `-e` flag\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -e\n```\n\nMake sure you defined your SMTP settings earlier (see [SMTP settings](#smtp-settings)).\n\nExample email:\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"https://raw.githubusercontent.com/misiektoja/lol_monitor/refs/heads/main/assets/lol_monitor_email_notifications.png\" alt=\"lol_monitor_email_notifications\" width=\"80%\"/\u003e\n\u003c/p\u003e\n\n\u003ca id=\"csv-export\"\u003e\u003c/a\u003e\n### CSV Export\n\nIf you want to save all reported activities of the LoL user to a CSV file, set `CSV_FILE` or use `-b` flag:\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -b lol_games_riot_id_name.csv\n```\n\nThe file will be automatically created if it does not exist.\n\n\u003ca id=\"check-intervals\"\u003e\u003c/a\u003e\n### Check Intervals\n\nIf you want to customize polling intervals, use `-k` and `-c` flags (or corresponding configuration options):\n\n```sh\nlol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e -k 60 -c 120\n```\n\n* `LOL_ACTIVE_CHECK_INTERVAL`, `-k`: check interval when the user is in a game (seconds)\n* `LOL_CHECK_INTERVAL`, `-c`: check interval when the user is NOT in a game (seconds)\n\n\u003ca id=\"signal-controls-macoslinuxunix\"\u003e\u003c/a\u003e\n### Signal Controls (macOS/Linux/Unix)\n\nThe 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.\n\nList of supported signals:\n\n| Signal | Description |\n| ----------- | ----------- |\n| USR1 | Toggle email notifications when user's playing status changes (-s) |\n| TRAP | Increase the check timer for player activity when user is in game (by 30 seconds) |\n| ABRT | Decrease check timer for player activity when user is in game (by 30 seconds) |\n| HUP | Reload secrets from .env file |\n\nSend signals with `kill` or `pkill`, e.g.:\n\n```sh\npkill -USR1 -f \"lol_monitor \u003criot_id_name#tag\u003e \u003cregion\u003e\"\n```\n\nAs Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.\n\n\u003ca id=\"coloring-log-output-with-grc\"\u003e\u003c/a\u003e\n### Coloring Log Output with GRC\n\nYou can use [GRC](https://github.com/garabik/grc) to color logs.\n\nAdd to your GRC config (`~/.grc/grc.conf`):\n\n```\n# monitoring log file\n.*_monitor_.*\\.log\nconf.monitor_logs\n```\n\nNow copy the [conf.monitor_logs](https://raw.githubusercontent.com/misiektoja/lol_monitor/refs/heads/main/grc/conf.monitor_logs) to your `~/.grc/` and log files should be nicely colored when using `grc` tool.\n\nExample:\n\n```sh\ngrc tail -F -n 100 lol_monitor_\u003criot_id_name\u003e.log\n```\n\n\u003ca id=\"change-log\"\u003e\u003c/a\u003e\n## Change Log\n\nSee [RELEASE_NOTES.md](https://github.com/misiektoja/lol_monitor/blob/main/RELEASE_NOTES.md) for details.\n\n\u003ca id=\"license\"\u003e\u003c/a\u003e\n## License\n\nLicensed under GPLv3. See [LICENSE](https://github.com/misiektoja/lol_monitor/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisiektoja%2Flol_monitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmisiektoja%2Flol_monitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisiektoja%2Flol_monitor/lists"}