pyvider-telemetry 0.0.4

Pyvider Telemetry: An opinionated, developer-friendly telemetry wrapper for Python.

🐍📡 pyvider-telemetry

Beautiful, performant, structured logging for Python.

Modern structured logging built on structlog with emoji-enhanced visual parsing and semantic Domain-Action-Status patterns.

---

Make your logs beautiful and meaningful! pyvider-telemetry transforms your application logging with visual emoji prefixes, semantic Domain-Action-Status patterns, and high-performance structured output. Perfect for development debugging, production monitoring, and everything in between.

🤔 Why pyvider-telemetry?

• 🎨 Visual Log Parsing: Emoji prefixes based on logger names and semantic context make logs instantly scannable
• 📊 Semantic Structure: Domain-Action-Status (DAS) pattern brings meaning to your log events
• ⚡ High Performance: Benchmarked >1000 msg/sec with optimized processor chains and emoji caching
• 🔧 Zero Configuration: Works beautifully out of the box, configurable via environment variables or code
• 🎯 Developer Experience: Thread-safe, async-ready, with comprehensive type hints for Python 3.13+

✨ Features

• 🎨 Emoji-Enhanced Logging:

  • Logger Name Prefixes: 🔑 User authentication successful (auth module)
  • Domain-Action-Status: [🔑][➡️][✅] Login completed (auth-login-success)
  • Custom TRACE Level: Ultra-verbose debugging with 👣 visual markers

• 📈 Production Ready:

  • High Performance: >1000 messages/second throughput
  • Thread Safe: Concurrent logging from multiple threads
  • Async Support: Native async/await compatibility
  • Memory Efficient: Optimized emoji caching and processor chains

• ⚙️ Flexible Configuration:

  • Multiple Formats: JSON for production, key-value for development
  • Module-Level Filtering: Different log levels per component
  • Environment Variables: Zero-code configuration options
  • Service Identification: Automatic service name injection

• 🏗️ Modern Python:

  • Python 3.13+ Exclusive: Latest language features and typing
  • Built with attrs: Immutable, validated configuration objects
  • Structlog Foundation: Industry-standard structured logging

🚀 Installation

Requires Python 3.13 or later.

pip install pyvider-telemetry

💡 Quick Start

Basic Usage

from pyvider.telemetry import setup_telemetry, logger

# Initialize with sensible defaults
setup_telemetry()

# Start logging immediately
logger.info("Application started", version="1.0.0")
logger.debug("Debug information", component="auth")
logger.error("Something went wrong", error_code="E123")

# Create component-specific loggers
auth_logger = logger.get_logger("auth.service")
auth_logger.info("User login attempt", user_id=12345)
# Output: 🔑 User login attempt user_id=12345

Semantic Domain-Action-Status Logging

# Use domain, action, status for semantic meaning
logger.info("User authentication",
           domain="auth", action="login", status="success",
           user_id=12345, ip="192.168.1.100")
# Output: [🔑][➡️][✅] User authentication user_id=12345 ip=192.168.1.100

logger.error("Database connection failed",
            domain="database", action="connect", status="error",
            host="db.example.com", timeout_ms=5000)
# Output: [🗄️][🔗][🔥] Database connection failed host=db.example.com timeout_ms=5000

Custom Configuration

from pyvider.telemetry import setup_telemetry, TelemetryConfig, LoggingConfig

config = TelemetryConfig(
    service_name="my-microservice",
    logging=LoggingConfig(
        default_level="INFO",
        console_formatter="json",           # JSON for production
        module_levels={
            "auth": "DEBUG",                # Verbose auth logging
            "database": "ERROR",            # Only DB errors
            "external.api": "WARNING",      # Minimal third-party noise
        }
    )
)

setup_telemetry(config)

Environment Variable Configuration

export PYVIDER_SERVICE_NAME="my-service"
export PYVIDER_LOG_LEVEL="INFO"
export PYVIDER_LOG_CONSOLE_FORMATTER="json"
export PYVIDER_LOG_MODULE_LEVELS="auth:DEBUG,db:ERROR"

from pyvider.telemetry import setup_telemetry, TelemetryConfig

# Automatically loads from environment
setup_telemetry(TelemetryConfig.from_env())

Exception Logging

try:
    risky_operation()
except Exception:
    logger.exception("Operation failed",
                    operation="user_registration",
                    user_id=123)
    # Automatically includes full traceback

Ultra-Verbose TRACE Logging

from pyvider.telemetry import setup_telemetry, logger, TelemetryConfig, LoggingConfig

# Enable TRACE level for deep debugging
config = TelemetryConfig(
    logging=LoggingConfig(default_level="TRACE")
)
setup_telemetry(config)

logger.trace("Entering function", function="authenticate_user")
logger.trace("Token validation details",
            token_type="bearer", expires_in=3600)

📊 Performance

pyvider-telemetry is designed for high-throughput production environments:

Scenario	Performance	Notes
Basic Logging	>1,200 msg/sec	Key-value format with emojis
JSON Output	>600 msg/sec	Structured production format
Multithreaded	>900 msg/sec	10 threads concurrent logging
TRACE Level	>1,100 msg/sec	Ultra-verbose debugging

Run benchmarks yourself:

python scripts/benchmark_performance.py

🎨 Emoji Reference

Domain Emojis (Primary)

• 🔑 auth, 🗄️ database, 🌐 network, ⚙️ system
• 🛎️ server, 🙋 client, 🔐 security, 📄 file
• See full matrix: PYVIDER_SHOW_EMOJI_MATRIX=true python -c "from pyvider.telemetry.logger.emoji_matrix import show_emoji_matrix; show_emoji_matrix()"

Action Emojis (Secondary)

• ➡️ login, 🔗 connect, 📤 send, 📥 receive
• 🔍 query, 📝 write, 🗑️ delete, ⚙️ process

Status Emojis (Tertiary)

• ✅ success, ❌ failure, 🔥 error, ⚠️ warning
• ⏳ attempt, 🔁 retry, 🏁 complete, ⏱️ timeout

🔧 Advanced Usage

Async Applications

import asyncio
from pyvider.telemetry import setup_telemetry, logger, shutdown_pyvider_telemetry

async def main():
    setup_telemetry()

    # Your async application code
    logger.info("Async app started")

    # Graceful shutdown
    await shutdown_pyvider_telemetry()

asyncio.run(main())

Production Configuration

production_config = TelemetryConfig(
    service_name="production-service",
    logging=LoggingConfig(
        default_level="INFO",               # Don't spam with DEBUG
        console_formatter="json",           # Machine-readable
        module_levels={
            "security": "DEBUG",            # Always verbose for security
            "performance": "WARNING",       # Only perf issues
            "third_party": "ERROR",         # Minimal external noise
        }
    )
)

📚 Documentation

For comprehensive API documentation, configuration options, and advanced usage patterns, see:

📖 Complete API Reference

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

🙏 Acknowledgements

pyvider-telemetry builds upon these excellent open-source libraries:

• structlog - The foundation for structured logging
• attrs - Powerful data classes and configuration management