diff --git a/Topics/Software_Engineering/logging_to_mysql.md b/Topics/Software_Engineering/logging_to_mysql.md new file mode 100644 index 000000000..e497a6b0d --- /dev/null +++ b/Topics/Software_Engineering/logging_to_mysql.md @@ -0,0 +1,210 @@ +# Implement Logging Process to MySQL for Functions + +## Introduction + +In this guide, we'll explore how to implement a logging process for software functions into a MySQL database. Logging is crucial for monitoring, debugging, and security purposes in software engineering. We'll cover the basics, the setup required, and provide a step-by-step example. + +## Prerequisites + +- Basic knowledge of programming (Python used in examples) +- Access to a MySQL database +- Familiarity with SQL queries + +## Step 1: Setting Up Your Environment + +Ensure you have Python and MySQL installed on your system. You'll also need the `mysql-connector-python` package for Python. + +```bash +pip install mysql-connector-python +``` + +## Step 2: Create a Logging Table in MySQL + +The `logs` table is essential for storing application log messages, which are crucial for debugging, monitoring application health, and understanding user actions. + +Execute the following SQL query in your MySQL database to create a table for logging: + +```sql +CREATE TABLE logs ( + id INT AUTO_INCREMENT PRIMARY KEY, + timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + level VARCHAR(10), + message TEXT +); +``` + +logs_table + +- **id** (INT): An auto-incremented integer serving as the primary key for each log entry. +- **timestamp** (TIMESTAMP): The date and time when the log entry was created, automatically set to the current timestamp. +- **level** (VARCHAR): A string indicating the severity of the log, such as INFO, WARNING, or ERROR. +- **message** (TEXT): The actual log message text, detailing the event or error reported. + +## Step 3: Implementing Logging in Python + +### Define the Logger + +Create a Python file, e.g., logger.py, and define a logger and a handler to insert logs into MySQL. + +```python +import logging +import mysql.connector +from mysql.connector import Error + +class MySQLHandler(logging.Handler): + def __init__(self, config): + super().__init__() + self.connection = mysql.connector.connect(**config) + self.cursor = self.connection.cursor() + + def emit(self, record): + try: + log_entry = self.format(record) + self.cursor.execute("INSERT INTO logs (level, message) VALUES (%s, %s)", (record.levelname, log_entry)) + self.connection.commit() + except Error as e: + print("Error logging to MySQL", e) +``` + +### Configure the Logger + +Configure the logger with the MySQL handler. + +```python +logger = logging.getLogger(__name__) +logger.setLevel(logging.INFO) + +config = { + 'host': 'your_database_host', + 'database': 'your_database_name', + 'user': 'your_username', + 'password': 'your_password' +} + +mysql_handler = MySQLHandler(config=config) +logger.addHandler(mysql_handler) + +formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s') +mysql_handler.setFormatter(formatter) +``` + +## Usage Example with the `users` Table + +In this example, we have a `users` table in our MySQL database designed to store user information such as IDs, names, and email addresses. +The table structure is as follows: + +- **id** (INT): A unique identifier for each user, auto-incremented. +- **name** (VARCHAR): The name of the user. +- **email** (VARCHAR): The user's email address, which is unique across all users. + +### Creating the `users` Table + +First, ensure that your MySQL database contains the `users` table. Use the following SQL query to create it if necessary: + +```sql +CREATE TABLE users ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(100) NOT NULL, + email VARCHAR(100) NOT NULL UNIQUE +); +``` + +users_table + +### Inserting Sample Data + +Insert some sample data into the `users` table to work with: + +```sql +INSERT INTO users (name, email) VALUES ('Alice Smith', 'alice@example.com'); +INSERT INTO users (name, email) VALUES ('Bob Jones', 'bob@example.com'); +``` + +users_sample_data + +### The `get_user_info` Function + +The `get_user_info` function is designed to retrieve a user's information from the database given their user ID. +It uses logging to indicate the function's outcome, such as successful information retrieval, attempts to retrieve non-existent users, and database connection errors. + +### Python Implementation + +Below is the updated Python script that includes the `get_user_info` function: + +```python +import logging +import mysql.connector +from mysql.connector import Error + +# Configure the logger and MySQLHandler as previously described + +def get_user_info(user_id): + """Retrieves user information by user_id from the database.""" + try: + conn = mysql.connector.connect(**config) + cursor = conn.cursor() + cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,)) + user_info = cursor.fetchone() + conn.close() + + if user_info: + logger.info(f"Retrieved information for user ID {user_id}: {user_info}") + return user_info + else: + logger.warning(f"User with ID {user_id} not found.") + return None + except Error as e: + logger.error(f"Error connecting to MySQL database: {e}") + return None + +# Example usage +user_id = 1 # Example user ID +user_info = get_user_info(user_id) +``` + +### Explanation + +This script attempts to retrieve information for a user by their ID. It logs: + +- An **info** level message if the information is successfully retrieved, + +https://github.com/learning-software-engineering/learning-software-engineering.github.io/assets/90298039/bd2777b4-93d8-490a-88fe-eacf04d570a1 + +- A **warning** if no user matches the provided ID, and + +https://github.com/learning-software-engineering/learning-software-engineering.github.io/assets/90298039/fadc999f-04c5-4488-89a4-60fabdcb1f59 + +- An **error** if there is a problem connecting to the database. + +https://github.com/learning-software-engineering/learning-software-engineering.github.io/assets/90298039/66d5602e-b31b-4558-8098-e2ff8d6cc741 + +This approach demonstrates practical logging usage within an application, providing insights into operational status and issues. + +## Example Use Case for Both Tables + +Consider an application where user actions are logged for security and auditing purposes. In this scenario, +the `logs` table captures the events, and the `users` table provides context about who triggered those events. +For example, if an unauthorized access attempt is made, the `logs` table would record the event's specifics, +while the `users` table could help identify or rule out which user(s) were involved. + +## Conclusion + +Implementing a logging process into MySQL allows developers to effectively monitor and debug their applications. +By following the steps outlined above, you can set up a robust logging system tailored to your project's needs. + +## References + +- [MySQL Connector/Python Developer Guide](https://dev.mysql.com/doc/connector-python/en/) +- [Logging facility for Python — Python 3.12.2 documentation](https://docs.python.org/3/library/logging.html) + +This document is structured to facilitate readability and understanding, featuring code blocks for SQL, bash, and Python +to illustrate the setup and implementation process for logging to MySQL. Remember to adjust the configuration details to match your environment. + + + + + + + + +