bunyan-formatter/README.md

Bunyan Formatter

• Description
• Installation
• Usage
• Examples
  • Basic Logging
  • Error Logging with Exception
  • Custom Fields
• Contributing
• License

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:

pip install bunyan-formatter

Usage

Here's a basic example of how to use the Bunyan Formatter in your Python project:

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

logger.info("User logged in", extra={"username": "john_doe"})

Output:

{
  "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

try:
    result = 1 / 0
except ZeroDivisionError as e:
    logger.exception("An error occurred", exc_info=True)

Output:

{
  "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:

logger.info("Order processed", extra={
    "order_id": 12345,
    "customer_id": 67890,
    "total_amount": 100.00
})

Output:

{
  "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.