/

Tags

Tags

Tags allow you to organize and categorize logs by feature, component, or domain. They make it easy to filter logs and understand which parts of your application are involved in specific operations.

Adding Tags

Use the with_tags() method to add one or more tags to a log entry:

Python
from bytehide_logs import Log

# Single tag
Log.with_tags("payment").info("Payment processing started")

# Multiple tags
Log.with_tags("payment", "stripe").info("Charging card via Stripe")

# Tags with context
Log.with_tags("database", "query") \
    .with_context("table", "users") \
    .info("User record fetched")

Tag Categories

Organize your application using consistent tag categories:

Authentication & Authorization

Python
# Login/logout operations
Log.with_tags("auth", "login").info("User login attempt")
Log.with_tags("auth", "logout").info("User session terminated")

# Permission checks
Log.with_tags("auth", "permission").warning("Insufficient permissions for operation")
Log.with_tags("auth", "token").info("Token refreshed")

Payment Processing

Python
Log.with_tags("payment", "checkout").info("Checkout initiated")
Log.with_tags("payment", "card").info("Card validated")
Log.with_tags("payment", "stripe").info("Payment submitted to Stripe")
Log.with_tags("payment", "refund").info("Refund processed")

Data Operations

Python
Log.with_tags("database", "query").info("SELECT executed")
Log.with_tags("database", "migration").info("Schema migration completed")
Log.with_tags("cache", "redis").info("Cache invalidated")
Log.with_tags("search", "elasticsearch").info("Index updated")

External Services

Python
Log.with_tags("service", "email").info("Welcome email sent")
Log.with_tags("service", "sms").warning("SMS delivery failed")
Log.with_tags("service", "api").info("Third-party API called")
Log.with_tags("service", "webhook").info("Webhook received and processed")

Business Domain

Python
Log.with_tags("order", "fulfilled").info("Order shipped")
Log.with_tags("inventory", "stock").info("Inventory updated")
Log.with_tags("customer", "profile").info("Customer profile modified")
Log.with_tags("reporting", "analytics").info("Analytics event recorded")

Multiple Tags for Complex Operations

Combine tags to describe operations spanning multiple domains:

Python
def process_order(order_id):
    """Process an order involving multiple systems."""
    
    # Validate order
    Log.with_tags("order", "validation").info(f"Validating order {order_id}")
    validate_order(order_id)
    
    # Update inventory
    Log.with_tags("order", "inventory").info(f"Reducing inventory for order {order_id}")
    reduce_inventory(order_id)
    
    # Process payment
    Log.with_tags("order", "payment", "stripe") \
        .with_context("order_id", order_id) \
        .info("Processing payment")
    process_payment(order_id)
    
    # Send confirmation
    Log.with_tags("order", "notification", "email") \
        .info("Order confirmation email sent")
    send_confirmation_email(order_id)
    
    Log.with_tags("order", "complete") \
        .info(f"Order {order_id} processed successfully")

Fluent Tag Chaining

Chain multiple operations with consistent tags:

Python
base_log = Log.with_tags("user_profile")

base_log.info("Loading user profile")
base_log.with_context("field", "name").info("Updating name")
base_log.with_context("field", "email").info("Updating email")
base_log.info("Profile changes saved")

Tag-Based Filtering and Analysis

Tags enable powerful log queries:

Python
# Find all payment-related operations
# Query: tag:payment

# Find failed stripe operations
# Query: tag:stripe AND level:error

# Find slow database queries
# Query: tag:database tag:query AND duration > 1000

Use lowercase and hyphens for consistency:

Python
# Good - lowercase, descriptive
Log.with_tags("payment-gateway", "card-validation").info("Card validated")

# Avoid - mixed case
Log.with_tags("PaymentGateway", "CardValidation").info("Card validated")

# Good - specific categories
Log.with_tags("auth", "oauth").info("OAuth token received")

# Avoid - vague tags
Log.with_tags("stuff").info("Something happened")

Tag Patterns

Establish tag patterns for your organization:

Python
# Pattern: [domain]-[action]
Log.with_tags("user-create").info("New user registered")
Log.with_tags("user-delete").info("User account deleted")
Log.with_tags("post-publish").info("Blog post published")
Log.with_tags("post-archive").info("Blog post archived")

# Pattern: [service]-[operation]
Log.with_tags("email-send").info("Email queued")
Log.with_tags("email-bounce").warning("Email bounced")
Log.with_tags("sms-send").info("SMS delivered")

# Pattern: [component]-[event]
Log.with_tags("middleware-request").info("Request received")
Log.with_tags("middleware-response").info("Response sent")

Tags with Error Handling

Use tags to categorize errors:

Python
def fetch_external_data(url):
    """Fetch data with categorized error logging."""
    try:
        response = requests.get(url, timeout=5)
        Log.with_tags("external-api", "success").info(f"Data fetched from {url}")
        return response.json()
    except requests.Timeout:
        Log.with_tags("external-api", "timeout").warning(f"Timeout fetching {url}")
    except requests.ConnectionError as e:
        Log.with_tags("external-api", "connection").error(f"Connection failed", exception=e)
    except Exception as e:
        Log.with_tags("external-api", "error").error(f"Unexpected error", exception=e)

Complete Example

Python
from bytehide_logs import Log

def handle_payment_webhook(payload):
    """Handle payment webhook with comprehensive tagging."""
    
    Log.with_tags("webhook", "payment").info("Payment webhook received")
    
    try:
        # Verify webhook signature
        Log.with_tags("webhook", "payment", "verification") \
            .info("Verifying webhook signature")
        verify_webhook_signature(payload)
        
        # Find associated order
        Log.with_tags("webhook", "payment", "lookup") \
            .info("Looking up order for payment")
        order = find_order(payload["order_id"])
        
        # Update order status
        Log.with_tags("webhook", "payment", "order-status") \
            .info("Updating order status")
        order.status = "paid"
        order.save()
        
        # Trigger fulfillment
        Log.with_tags("webhook", "payment", "fulfillment") \
            .info("Triggering order fulfillment")
        trigger_fulfillment(order.id)
        
        Log.with_tags("webhook", "payment", "complete") \
            .info("Payment webhook processed successfully")
            
    except Exception as e:
        Log.with_tags("webhook", "payment", "error") \
            .error("Payment webhook processing failed", exception=e)
        raise

Next Steps

Previous
Metadata & Context
Next
Exception Handling