Artissist Logger - Python Client

Platform-agnostic logging client for the Artissist platform.

Table of Contents

• Features
• Installation
• Quick Start
• API Guide
• Logger Types
• Context Management
• Events and Emojis
• Error Handling
• Metrics
• Adapters
• Synchronous Usage
• Configuration
• Development
• Integration Examples
• License

Features

• 🎯 Pre-defined Events: 25 built-in event types with emoji support
• 🎨 Emoji Integration: Configurable emoji prefixes for visual log scanning
• 📊 Structured Logging: Rich metadata, metrics, and error information
• 🔄 Context Management: Distributed tracing with correlation IDs
• 🔌 Adapter Pattern: Multiple output destinations (console, file, cloud)
• 🏭 Factory Pattern: Specialized loggers for different components
• ⚡ Async Support: Non-blocking logging with async/await
• 🛡️ Type Safety: Full type hints and runtime validation

Installation

pip install artissist-logger

Development Installation

pip install -e .[dev]

Quick Start

from artissist_logger import LoggerFactory, LogEvent

# Create a backend logger
logger = LoggerFactory.create_backend_logger(
    service="my-service",
    environment="development", 
    emojis=True  # Enable emojis for development
)

# Basic logging
await logger.info("Service starting up", event=LogEvent.SYSTEM_START)
await logger.error("Database connection failed", event=LogEvent.ERROR_OCCURRED)

# With structured data
await logger.info(
    "User authenticated successfully",
    event=LogEvent.USER_AUTH,
    metadata={"user_id": "user_123", "method": "oauth"},
    metrics={"auth_duration_ms": 150}
)

The Logger exposes convenience methods for each level (debug, info, warn, error, etc.). Use logger.log(level, message, **kwargs) only when the level must be chosen dynamically.

API Guide

Factory Functions

LoggerFactory.create_logger(service, environment, adapters, emojis=False, context=None, adapter_configs=None, emoji_resolver=None)

• service (str): Service name.
• environment (str): Deployment environment.
• adapters (list[str]): Adapter names ("console", "file").
• emojis (bool): Enable emoji prefixes.
• context (LoggerContext): Base context values.
• adapter_configs (dict): Adapter options.
  • console: colors, use_stderr
  • file: file_path, format, rotate, max_size_mb, max_files
• emoji_resolver (EmojiResolver): Custom emoji mappings.

LoggerFactory.create_frontend_logger(service, environment, emojis=False, context=None, adapters=None)

LoggerFactory.create_backend_logger(service, environment, emojis=False, context=None, adapters=None)

LoggerFactory.create_agent_logger(config) where config includes agent_id, agent_type, environment, emojis, context, and adapters

LoggerFactory.create_infrastructure_logger(component, environment, emojis=False, context=None, adapters=None)

Logger Methods

logger.debug|info|warn|error(message, *, event=None, custom_event=None, metadata=None, metrics=None, error=None, tags=None, context=None)

• event (LogEvent): Predefined event type.
• custom_event (str): Custom event key.
• metadata (dict): Arbitrary key/value pairs.
• metrics (LogMetrics): duration_ms, count, bytes_processed, cpu_usage, memory_usage, custom_metrics.
• error (ErrorInfo): type, message, stack_trace, context.
• tags (list[str]): Optional labels.
• context (LoggerContext): correlation_id, user_id, session_id, request_id, trace_id, span_id, plus custom fields.

Logger Types

Backend Logger

logger = LoggerFactory.create_backend_logger(
    service="api-server",
    environment="production",
    emojis=False  # Disabled for production
)

Agent Logger

logger = LoggerFactory.create_agent_logger(
    agent_id="conv_001",
    agent_type="conversation",
    environment="development",
    emojis=True
)

Infrastructure Logger

logger = LoggerFactory.create_infrastructure_logger(
    component="deployment-manager", 
    environment="production"
)

Context Management

Global Context

from artissist_logger import ContextManager, LoggerContext

# Set global context
ContextManager.set_context(LoggerContext(
    correlation_id="req_123",
    user_id="user_456"
))

# All subsequent logs will include this context
await logger.info("Processing request")  # Includes correlation_id and user_id

Scoped Context

# Temporary context for a specific operation
with ContextManager.context(user_id="user_789", operation="data_export"):
    await logger.info("Starting export")  # Includes user_id and operation
    await logger.info("Export completed")

Logger Context

# Create logger with permanent context
contextual_logger = logger.with_context(
    service_version="1.2.0",
    deployment_id="deploy_abc"
)

await contextual_logger.info("Service initialized")  # Includes service_version and deployment_id

Events and Emojis

Pre-defined Events

# System events
LogEvent.SYSTEM_START      # 🚀 System startup
LogEvent.ERROR_OCCURRED    # 🐛 Errors and exceptions
LogEvent.WARNING_ISSUED    # ⚠️  Warning conditions

# Business events  
LogEvent.USER_AUTH         # 👤 User authentication
LogEvent.PROJECT_LIFECYCLE # 📁 Project management
LogEvent.AI_INFERENCE      # 🧠 AI model operations

# Technical events
LogEvent.API_REQUEST       # 🔄 API calls
LogEvent.DATABASE_OPERATION # 💾 Database queries
LogEvent.PERFORMANCE_METRIC # ⚡ Performance measurements

Custom Events

from artissist_logger import EmojiResolver, EmojiMapping

# Create custom emoji mappings
resolver = EmojiResolver()
resolver.add_custom_mapping("payment_processed", EmojiMapping(
    emoji="💳", 
    description="Payment processing events"
))

logger = LoggerFactory.create_logger(
    service="payment-service",
    environment="development", 
    adapters=["console"],
    emojis=True,
    emoji_resolver=resolver
)

# Use custom event
await logger.info("Payment completed", custom_event="payment_processed")
# Output: 💳 Payment completed

Error Handling

from artissist_logger import ErrorInfo

try:
    # Some operation that might fail
    process_data()
except Exception as e:
    await logger.error(
        "Data processing failed",
        event=LogEvent.ERROR_OCCURRED,
        error=ErrorInfo(
            type=type(e).__name__,
            message=str(e),
            stack_trace=traceback.format_exc(),
            context={"batch_id": "batch_123"}
        )
    )

Metrics

from artissist_logger import LogMetrics

# Performance metrics
await logger.info(
    "Database query completed",
    event=LogEvent.DATABASE_OPERATION,
    metrics=LogMetrics(
        duration_ms=45.2,
        count=150,
        bytes_processed=1024000
    )
)

# Business metrics
await logger.info(
    "User signup completed", 
    event=LogEvent.BUSINESS_METRIC,
    metadata={"user_type": "premium"},
    metrics=LogMetrics(
        count=1,
        custom_metrics={"revenue_impact": 29.99}
    )
)

Adapters

Console Adapter

# Development console output with colors
LoggerFactory.create_logger(
    service="my-service",
    environment="development",
    adapters=["console"],
    adapter_configs={
        "console": {"colors": True, "use_stderr": False}
    }
)

File Adapter

# Production file logging with rotation
LoggerFactory.create_logger(
    service="my-service", 
    environment="production",
    adapters=["file"],
    adapter_configs={
        "file": {
            "file_path": "logs/service.log",
            "format": "json",
            "rotate": True,
            "max_size_mb": 50,
            "max_files": 10
        }
    }
)

Multiple Adapters

# Both console and file output
LoggerFactory.create_backend_logger(
    service="api-service",
    environment="production",
    adapters=["console", "file"]
)

Synchronous Usage

For non-async contexts:

# Synchronous convenience methods (fire-and-forget)
logger.info_sync("Service started", event=LogEvent.SYSTEM_START)
logger.error_sync("Connection failed", event=LogEvent.ERROR_OCCURRED)

Configuration

Environment Variables

export ARTISSIST_LOG_LEVEL=INFO
export ARTISSIST_LOG_EMOJIS=true
export ARTISSIST_LOG_FORMAT=json

Programmatic Configuration

config = {
    "service": "my-service",
    "environment": "production",
    "adapters": ["console", "file"],
    "emojis": False,
    "adapter_configs": {
        "console": {"colors": False},
        "file": {"file_path": "/var/log/my-service.log"}
    }
}

logger = LoggerFactory.create_logger(**config)

Development

Running Tests

pytest
pytest --cov=artissist_logger  # With coverage

Code Formatting

black artissist_logger/
mypy artissist_logger/
flake8 artissist_logger/

Build Package

python setup.py bdist_wheel

Integration Examples

See the examples/ directory for complete integration examples:

• FastAPI backend service
• Agent processing systems
• Infrastructure deployment logging
• Error handling patterns
• Performance monitoring

License

MIT License - see LICENSE file for details.