xbox_monitor

xbox_monitor is a tool for real-time monitoring of Xbox Live players' activities.

Features

• Real-time tracking of Xbox Live users' gaming activity (including detection when a user gets online or offline and played games)
• Basic statistics for user activity (how long in different states, how long a game is played, overall time and number of played games in the session etc.)
• Email notifications for different events (player gets online, away or offline and starts, finishes or changes a game, errors)
• Saving all user activities with timestamps to a CSV file
• Built-in OAuth2 authentication
• 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
   • Azure AD App Credentials
   • User Privacy Settings
   • Time Zone
   • 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.8 or higher
• Libraries: xbox-webapi, requests, python-dateutil, httpx, pytz, tzlocal, 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 xbox_monitor

Manual Installation

Download the xbox_monitor.py file to the desired location.

Install dependencies via pip:

pip install xbox-webapi requests python-dateutil httpx pytz tzlocal python-dotenv

Alternatively, from the downloaded requirements.txt:

pip install -r requirements.txt

Quick Start

• Grab your Azure app credentials and track the xbox_gamer_tag gaming activities:

xbox_monitor <xbox_gamer_tag> -u "your_ms_application_client_id" -w "your_ms_application_secret_value"

Or if you installed manually:

python3 xbox_monitor.py <xbox_gamer_tag> -u "your_ms_application_client_id" -w "your_ms_application_secret_value"

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

xbox_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 xbox_monitor.conf:

xbox_monitor --generate-config > xbox_monitor.conf

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

Azure AD App Credentials

Log in to Azure AD and register new app.

• Name your app (e.g. xbox_monitor)
• For account type select Personal Microsoft accounts only
• For redirect URL select Web type and put: http://localhost/auth/callback

Then copy value of Application (client) ID to MS_APP_CLIENT_ID.

Then next to Client credentials click Add a certificate or secret.

Add a new client secret with long expiration date (like 2 years) and some description (e.g. xbox_monitor_secret).

Copy the contents from Value column to MS_APP_CLIENT_SECRET.

After performing authentication the token will be saved into the default xbox_tokens.json file in current working dir (you can change it via MS_AUTH_TOKENS_FILE).

Provide the MS_APP_CLIENT_ID and MS_APP_CLIENT_SECRET secrets using one of the following methods:

• Pass it at runtime with -u / --ms-app-client-id and -w / --ms-app-client-secret
• Set it as an environment variable (e.g. export MS_APP_CLIENT_ID=...; export MS_APP_CLIENT_SECRET=...)
• Add it to .env file (MS_APP_CLIENT_ID=... and MS_APP_CLIENT_SECRET=...) for persistent use

Fallback:

• Hard-code it in the code or config file

If you store the MS_APP_CLIENT_ID and MS_APP_CLIENT_SECRET in a dotenv file you can update their values and send a SIGHUP signal to the process to reload the file with the new secret values without restarting the tool. More info in Storing Secrets and Signal Controls (macOS/Linux/Unix).

User Privacy Settings

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

The user should go to Xbox profile privacy & online safety settings.

The value in Others can see if you're online (and preferably also Others can see your Xbox profile details) should be set to Friends or Everyone.

Time Zone

By default, time zone is auto-detected using tzlocal. You can set it manually in xbox_monitor.conf:

LOCAL_TIMEZONE='Europe/Warsaw'

You can get the list of all time zones supported by pytz like this:

python3 -c "import pytz; print('\n'.join(pytz.all_timezones))"

SMTP Settings

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

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

xbox_monitor --send-test-email

Storing Secrets

It is recommended to store secrets like MS_APP_CLIENT_ID, MS_APP_CLIENT_SECRET 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 MS_APP_CLIENT_ID="your_ms_application_client_id"
export MS_APP_CLIENT_SECRET="your_ms_application_secret_value"
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):

MS_APP_CLIENT_ID="your_ms_application_client_id"
MS_APP_CLIENT_SECRET="your_ms_application_secret_value"
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:

xbox_monitor <xbox_gamer_tag> --env-file /path/.env-xbox_monitor

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

xbox_monitor <xbox_gamer_tag> --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 Xbox Live gamer tag (xbox_gamer_tag in the example below):

xbox_monitor <xbox_gamer_tag>

If you have not set MS_APP_CLIENT_ID and MS_APP_CLIENT_SECRET secrets, you can use -u and -w flags:

xbox_monitor <xbox_gamer_tag> -u "your_ms_application_client_id" -w "your_ms_application_secret_value"

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

xbox_monitor <xbox_gamer_tag> --config-file /path/xbox_monitor_new.conf

The first time the tool is executed it will perform OAuth2 authentication using the data you provided.

It will generate a URL you need to paste in your web browser and authorize the tool.

The request in your web browser will be redirected to localhost. You will receive an error indicating a connection failure. Ignore this and simply copy the part after ?code= in the callback URL and paste it into the tool.

The tool will save the token to a file specified in MS_AUTH_TOKENS_FILE configuration option, so it can be reused in case the tool is restarted (with no need to authenticate again).

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

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

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

The tool also saves the timestamp and last status (after every change) to xbox_<gamer_tag>_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

xbox_monitor <xbox_gamer_tag> -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

xbox_monitor <xbox_gamer_tag> -g

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

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

xbox_monitor <xbox_gamer_tag> -s

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

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

xbox_monitor <xbox_gamer_tag> -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 Xbox Live user to a CSV file, set CSV_FILE or use -b flag:

xbox_monitor <xbox_gamer_tag> -b xbox_gamer_tag.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):

xbox_monitor <xbox_gamer_tag> -k 30 -c 120

• XBOX_ACTIVE_CHECK_INTERVAL, -k: check interval when the user is online or away (seconds)
• XBOX_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/offline) (-s)
TRAP	Increase the check timer for player activity when user is online (by 30 seconds)
ABRT	Decrease check timer for player activity when user is online (by 30 seconds)
HUP	Reload secrets from .env file

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

pkill -USR1 -f "xbox_monitor <xbox_gamer_tag>"

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 xbox_monitor_<gamer_tag>.log

Change Log

See RELEASE_NOTES.md for details.

License

Licensed under GPLv3. See LICENSE.