Tamga

A modern, high-performance logging utility for Python with multiple output formats and colorful console output.

🤖 AI Integration: For AI/LLM integration, see LLMs.txt or access documentation directly via Context7

tam·ga /ˈtæmɡə/ · noun An ancient Turkic symbol or seal used for marking ownership, identity, or lineage.

✨ Features

• 🎨 Beautiful Console Output - Colorful, formatted logs using Tailwind CSS colors
• ⚡ High Performance - Buffered writing system (10x faster than traditional logging)
• 📊 Multiple Outputs - Console, file, JSON, SQLite, MongoDB
• 🔄 Automatic Rotation - File size management with backup support
• 🧵 Thread-Safe - Safe for multi-threaded applications
• 🔔 Notifications - Multi-service notifications via Apprise (Discord, Slack, Email, SMS, and more)
• 🔍 Structured Logging - Key-value data support with all log methods

🚀 Quick Start

See examples/simple_usage.py for a full script.

```python from tamga import Tamga

Create logger with default settings

logger = Tamga()

Log messages

logger.info("Application started") logger.warning("Memory usage at 85%") logger.error("Failed to connect to API") logger.success("User registered successfully") logger.debug("Cache initialized with 1000 entries") ```

🧑‍💻 Examples

See examples/ for ready-to-run scripts:

• simple_usage.py — basic logging
• fastapi_webapp.py — FastAPI integration
• advanced_config.py — production config
• high_performance.py — high-speed big data logging demo

📦 Installation

bash pip install tamga # Basic installation pip install tamga[mongo] # With MongoDB support pip install tamga[notifications] # With notification support pip install tamga[all] # All features

🎯 Usage Examples

Basic Configuration

```python logger = Tamga( # Display settings coloredoutput=True, # Colored output showtime=True, # Include timestamp show_timezone=False, # Include timezone

# Output destinations
file_output=True,        # Log to file
file_path="app.log",     # Log file path
buffer_size=50,         # Buffer size for performance

) ```

Structured Logging

```python

Log with key-value data using any log method

logger.info("User action", userid="123", action="login", ipaddress="192.168.1.1", success=True )

Works with all log levels

logger.error("Database connection failed", host="localhost", port=5432, timeout=30, retry_count=3 )

logger.success("Payment processed", amount=99.99, currency="USD", method="creditcard", transactionid="tx_123" ) ```

Production Setup

```python logger = Tamga( # File rotation fileoutput=True, maxfilesizemb=50, # 50MB max file size enable_backup=True, # Create backups

# Performance
buffer_size=200,        # Larger buffer for production
console_output=False,    # Disable console for speed

# External services
mongo_output=True,
mongo_uri="mongodb://...",

# Multi-service notifications
notify_services=[
    "discord://webhook_id/webhook_token",
    "slack://tokenA/tokenB/tokenC/#alerts",
    "mailto://user:pass@smtp.gmail.com:587/?to=alerts@company.com",
    "twilio://SID:Token@+1234567890/+0987654321",
],
notify_levels=["CRITICAL", "ERROR", "NOTIFY"],

) ```

📋 Log Levels

| Level | Color | Method | Use Case | |-------|-------|---------|----------| | INFO | Sky | logger.info() | General information | | WARNING | Amber | logger.warning() | Warning messages | | ERROR | Rose | logger.error() | Error messages | | SUCCESS | Emerald | logger.success() | Success messages | | DEBUG | Indigo | logger.debug() | Debug information | | CRITICAL | Red | logger.critical() | Critical issues | | DATABASE | Green | logger.database() | Database operations | | NOTIFY | Purple | logger.notify() | Send notifications | | METRIC | Cyan | logger.metric() | Performance metrics | | TRACE | Gray | logger.trace() | Detailed trace info | | CUSTOM | Any | logger.custom() | Custom levels |

🔧 Advanced Features

Notifications

```python

Configure notification services (supports 80+ services via Apprise)

logger = Tamga( notifyservices=[ "discord://webhookid/webhooktoken", "slack://tokenA/tokenB/tokenC/#channel", ], notifylevels=["CRITICAL", "ERROR", "NOTIFY"], notifytitle="{appname}: {level} Alert", notifyformat="markdown", # text, markdown, or html )

Send notification

logger.notify("Payment received from user #123")

Critical logs also trigger notifications

logger.critical("Database connection lost") ```

Custom Log Levels

python logger.custom("Deploy completed", "DEPLOY", "purple") logger.custom("Payment received", "PAYMENT", "green")

Buffer Control

```python

Force write all buffered logs

logger.flush() ```

File Rotation

When log files reach max_file_size_mb, Tamga automatically: - Creates timestamped backups (if enabled) - Clears the original file - Continues logging seamlessly

📊 Performance

Tamga uses a buffered writing system that delivers significantly faster performance compared to traditional logging. The buffering mechanism provides optimal throughput for high-volume logging scenarios while maintaining thread safety.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package
• GitHub Repository
• Documentation
• Bug Reports

Made with ❤️ by Doğukan Ürker