docs: write README.md

README.md

@@ -1,3 +1,167 @@
-# bunyan-formatter
+# Bunyan Formatter
 
-Describe your project here.
+<!-- toc -->
+
+- [Description](#description)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Examples](#examples)
+  * [Basic Logging](#basic-logging)
+  * [Error Logging with Exception](#error-logging-with-exception)
+  * [Custom Fields](#custom-fields)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- tocstop -->
+
+A custom formatter for Python's logging module that outputs logs in the Bunyan
+JSON format.
+
+## Description
+
+This package provides a `BunyanFormatter` class that formats log records into
+the Bunyan JSON format. Bunyan is a lightweight JSON logger for Node.js, but
+this formatter allows you to use the same log format in Python projects.
+
+Key features:
+
+- Outputs logs in JSON format
+- Includes project name, hostname, file path, line number, and other metadata
+- Supports various log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- Handles both project and external file paths
+
+## Installation
+
+To install the Bunyan Formatter package, run:
+
+```bash
+pip install bunyan-formatter
+```
+
+## Usage
+
+Here's a basic example of how to use the Bunyan Formatter in your Python project:
+
+```python
+import logging
+from bunyan_formatter import BunyanFormatter
+
+# Create a logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+# Create a handler and set the formatter
+handler = logging.StreamHandler()
+formatter = BunyanFormatter(project_name="MyProject", project_root="/path/to/my/project")
+handler.setFormatter(formatter)
+
+# Add the handler to the logger
+logger.addHandler(handler)
+
+# Now you can use the logger
+logger.debug("This is a debug message")
+logger.info("This is an info message")
+logger.warning("This is a warning message")
+logger.error("This is an error message")
+logger.critical("This is a critical message")
+```
+
+## Examples
+
+### Basic Logging
+
+```python
+logger.info("User logged in", extra={"username": "john_doe"})
+```
+
+Output:
+
+```json
+{
+  "v": 0,
+  "name": "MyProject",
+  "msg": "User logged in",
+  "level": 30,
+  "levelname": "INFO",
+  "hostname": "your-hostname",
+  "target": "__main__",
+  "line": 10,
+  "file": "main.py",
+  "extra": {
+    "username": "john_doe"
+  }
+}
+```
+
+### Error Logging with Exception
+
+```python
+try:
+    result = 1 / 0
+except ZeroDivisionError as e:
+    logger.exception("An error occurred", exc_info=True)
+```
+
+Output:
+
+```json
+{
+  "v": 0,
+  "name": "MyProject",
+  "msg": "An error occurred",
+  "level": 50,
+  "levelname": "ERROR",
+  "hostname": "your-hostname",
+  "target": "__main__",
+  "line": 15,
+  "file": "main.py",
+  "err": {
+    "message": "division by zero",
+    "name": "ZeroDivisionError",
+    "stack": [
+      // Stack trace here
+    ]
+  }
+}
+```
+
+### Custom Fields
+
+You can add custom fields to your log entries:
+
+```python
+logger.info("Order processed", extra={
+    "order_id": 12345,
+    "customer_id": 67890,
+    "total_amount": 100.00
+})
+```
+
+Output:
+
+```json
+{
+  "v": 0,
+  "name": "MyProject",
+  "msg": "Order processed",
+  "level": 30,
+  "levelname": "INFO",
+  "hostname": "your-hostname",
+  "target": "__main__",
+  "line": 20,
+  "file": "main.py",
+  "extra": {
+    "order_id": 12345,
+    "customer_id": 67890,
+    "total_amount": 100.0
+  }
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please submit pull requests or issues on our GitHub repository.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.