PHTNAI Logger

Enterprise-grade generic logger service for PHTNAI with structured logging, context management, and multiple handler support.

🏆 Enterprise Standards (100% Complete)

15/15 Enterprise standards fully implemented:

Security Tools (HIGH PRIORITY) ✅

• detect-secrets - Prevent secret commits (pre-commit hook)
• Bandit - Security linting (hardcoded secrets, injection risks)
• Safety - Dependency vulnerability audit (CVE detection)

Code Quality (HIGH PRIORITY) ✅

• Ruff - PRIMARY linter (10-100x faster than Flake8)
• Black - Code formatting
• isort - Import sorting
• MyPy - Strict type checking

Testing & Validation ✅

• Pytest - 678+ comprehensive tests
• 90%+ Code Coverage - Full coverage enforcement
• Pydantic v2 - Type-safe configuration models

CI/CD & Automation ✅

• GitHub Actions - Multi-version testing (3.9-3.12)
• Pre-commit Hooks - Automatic enforcement
• Automated Releases - Semantic versioning + PyPI

Documentation ✅

• Sphinx - Auto-generated API docs
• 3 Comprehensive Guides - Contributing, Development, Troubleshooting
• 14 Architecture Diagrams - PlantUML diagrams

See Enterprise Standards Documentation for complete details.

Features

• 🎯 Structured Logging: Built-in support for JSON formatted logs
• 📝 Context Management: Manage request-scoped logging context
• 🔌 Multiple Handlers: Extensible handler architecture
• 📊 Type-Safe: Full type hints for IDE support
• 🧪 Well-Tested: 100% test coverage with pytest
• 📦 Enterprise-Ready: Production-grade packaging with Poetry
• 🚀 Auto-Publishing: Automated version bumping and PyPI publishing via CI/CD
• ☁️ Multi-Cloud Kubernetes: Auto-detection for AWS EKS, Azure AKS, Google GKE, generic K8s
• 📊 Pod Metrics: Automatic capture of memory, CPU, network, disk, container, security, scheduling metrics
• 🤖 Auto-Triggered Handlers: Eliminate error handling boilerplate with auto-triggered service handlers
• 🌍 Write Once, Run Anywhere: Same code works on all cloud providers and local development

Visual Architecture

See docs/diagrams/ for PlantUML diagrams:

• features_coverage.puml - Complete feature map with advantages and cloud coverage
• library_overview.puml - High-level product overview and value proposition
• value_matrix.puml - Feature coverage matrix and capabilities
• architecture.puml - Complete system architecture with all components

Installation

Install from PyPI:

pip install phtnai-logger

Or using Poetry:

poetry add phtnai-logger

Quick Start

from phtnai_logger import Logger

# Create a logger
logger = Logger("my-service")

# Log messages
logger.info("Application started")
logger.warning("This is a warning")
logger.error("An error occurred")

# Add context
logger.set_context("user_id", "user123")
logger.set_context("request_id", "req456")

# Log with context
logger.info("User action performed")

# Clear context
logger.clear_context()

Configuration

Configure via environment variables:

export PHTNAI_LOGGER_NAME="my-service"
export PHTNAI_LOGGER_LEVEL="DEBUG"
export PHTNAI_LOG_FILE="/var/log/app.log"

Or programmatically:

from phtnai_logger.config import LoggerConfig

config = LoggerConfig(
    name="my-service",
    level="DEBUG",
    log_file="/var/log/app.log"
)

JSON Logging

Use JSON formatter for structured logs:

import logging
from phtnai_logger import Logger
from phtnai_logger.utils.formatter import JSONFormatter

logger = Logger("my-service")
handler = logging.StreamHandler()
formatter = JSONFormatter()
handler.setFormatter(formatter)
logger._logger.addHandler(handler)

logger.info("User logged in", user_id="user123")

Cloud-Native Logging with Fluent Bit

For containerized environments (Docker/Kubernetes), use stdout logging to enable automatic log capture:

from phtnai_logger import Logger

# Create logger
logger = Logger("my-service")

# Setup stdout logging (JSON format for log aggregators)
logger.setup_stdout_logging(json_format=True)

# All logs go to stdout
logger.info("Payment processed", user_id="u123", amount=99.99)
# Output: {"timestamp": "...", "level": "INFO", "message": "Payment processed", ...}

Fluent Bit Configuration:

[INPUT]
    Name              tail
    Path              /var/log/containers/*.log
    Parser            docker
    Tag               container.*

[FILTER]
    Name       parser
    Match      container.*
    Key_Name   log
    Parser     json

[OUTPUT]
    Name  es
    Match *
    Host  elasticsearch:9200

Benefits:

• ✅ No file I/O overhead
• ✅ Container-native logging pattern
• ✅ Fluent Bit automatically captures stdout
• ✅ Works with ELK, Datadog, CloudWatch, Splunk

See Fluent Bit Integration Guide for Docker/Kubernetes examples.

Development

Setup

# Clone repository
git clone https://github.com/phtnai/phtnai-logger.git
cd phtnai-logger

# Install with development dependencies
poetry install

# Install pre-commit hooks
pre-commit install

Testing

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test file
poetry run pytest tests/unit/test_core.py

Code Quality

# Format code
poetry run black src tests

# Sort imports
poetry run isort src tests

# Lint code
poetry run flake8 src tests

# Type checking
poetry run mypy src

Building

# Build distribution
poetry build

# The wheel will be in dist/ directory

CI/CD Pipeline

This project uses GitHub Actions for:

1. Testing: Runs on Python 3.9-3.12 on every push/PR
2. Linting: Black, isort, flake8, mypy checks
3. Publishing: Automated semantic versioning and PyPI publishing

Version Bumping

Versions are bumped automatically based on commit messages:

• fix: ... → PATCH version (0.0.X)
• feat: ... → MINOR version (0.X.0)
• BREAKING CHANGE: ... → MAJOR version (X.0.0)

Example:

git commit -m "feat: add custom formatter support"
git push origin main
# Automatically bumps version and publishes to PyPI

Publishing

To publish to PyPI, add PYPI_API_TOKEN secret to GitHub repository settings.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions