Structlog Logging Specialist

Structlog Logging Specialist

Compact skill for implementing structured logging with Structlog in HuleEdu services.

When to Use

Activate when the user:

• Needs to configure Structlog for a new or existing service
• Wants to propagate correlation IDs through logs
• Asks about async-safe context variables
• Needs to integrate logging with error handling
• Wants to understand production vs development logging
• Mentions Structlog, structured logging, correlation context, or log context
• Needs to bind context variables to logs

Core Capabilities

• Structlog Configuration: Production (JSON) vs Development (colored console) setup
• Correlation Propagation: HTTP request → logs, Kafka events → logs, cross-service tracing
• Context Variables: Async-safe context binding with bind_contextvars
• Logger Creation: Service-specific logger instances
• Event Logging: Structured logging for Kafka event processing
• Error Integration: Automatic correlation context in error handlers
• JSON Output: Production-ready JSON logs for Loki aggregation
• Context7 Integration: Fetch latest Structlog documentation

Quick Workflow

1. Configure Structlog at service startup with environment-specific settings
2. Create logger instances for modules/components
3. Bind correlation context at request/event boundaries
4. Log with structured key-value pairs
5. Clear context when done (async boundaries)
6. Verify JSON output in production logs

Configuration Pattern

from huleedu_service_libs.logging_utils import configure_service_logging

# In app.py or main startup
configure_service_logging(
    service_name="spellchecker_service",
    environment=settings.ENVIRONMENT,  # "production" or "development"
    log_level=settings.LOG_LEVEL,      # "INFO", "DEBUG", etc.
)

Logger Usage Pattern

from huleedu_service_libs.logging_utils import create_service_logger

# Create logger for module
logger = create_service_logger("spellchecker_service.event_processor")

# Log with context
logger.info(
    "Processing event",
    correlation_id=str(correlation_id),
    event_id=str(event_id),
    essay_id=essay_id,
)

Context Binding Pattern

from structlog.contextvars import bind_contextvars, clear_contextvars

# Bind context at request/event boundary
bind_contextvars(
    correlation_id=str(envelope.correlation_id),
    event_id=str(envelope.event_id),
    event_type=envelope.event_type,
)

# All logs now include bound context automatically
logger.info("Processing started")  # Includes correlation_id, event_id, event_type

# Clear when done
clear_contextvars()

Reference Documentation

• Detailed Configuration & Patterns: See reference.md in this directory
• Real-World Logging Examples: See examples.md in this directory
• Logging Library: /libs/huleedu_service_libs/src/huleedu_service_libs/logging_utils.py
• Correlation Utilities: /libs/huleedu_service_libs/src/huleedu_service_libs/error_handling/correlation.py