refactor: change file names

nit

nit

Author: adinhodovic

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff (tox)
+        entry: tox -e ruff
+        language: system
+        pass_filenames: false
+
+      - id: pylint
+        name: pylint (tox)
+        entry: tox -e pylint
+        language: system
+        pass_filenames: false

CONTRIBUTING.md

@@ -37,7 +37,7 @@ django-o11y/
 │   ├── conftest.py         # Shared fixtures, make_config() helper
 │   └── Dockerfile          # Multi-stage uv build for dev containers
 │
-├── docker-compose.dev.yml  # Local dev stack (Django + Celery + Redis + task generator)
+├── docker-compose.yml      # Local dev stack (Django + Celery + Redis + task generator)
 ├── Makefile                # Shortcuts: make dev, make o11y-stack, etc.
 └── docs/                   # Usage and configuration guides
 ```
@@ -113,6 +113,7 @@ make dev
 
 Before opening a PR:
 
+0. Run hooks with prek: `prek run --all-files` (config is in `.pre-commit-config.yaml`)
 1. Tests pass: `tox -e py312-django52`
 2. Lint clean: `tox -e ruff && tox -e pylint`
 3. Integration tests pass if you changed signal handlers or Celery setup: `tox -e integration`

Makefile

@@ -4,13 +4,13 @@ setup:
 	uv sync --all-extras
 
 dev:
-	docker compose -f docker-compose.dev.yml up --build --watch
+	docker compose up --build --watch
 
 dev-stop:
-	docker compose -f docker-compose.dev.yml stop
+	docker compose stop
 
 dev-logs:
-	docker compose -f docker-compose.dev.yml logs -f
+	docker compose logs -f
 
 o11y-stack:
 	DJANGO_SETTINGS_MODULE=tests.config.settings.local CELERY_BROKER_URL=$${CELERY_BROKER_URL:-redis://localhost:6379/0} DJANGO_O11Y_LOGGING_FILE_ENABLED=false DJANGO_O11Y_DEV_DB_NAME=$$PWD/dev_db.sqlite3 DJANGO_O11Y_STACK_LOG_DIR=$${DJANGO_O11Y_DEV_TMP_DIR:-/tmp/django-o11y-$${COMPOSE_PROJECT_NAME:-django-o11y}} python manage.py o11y stack start

docker-compose.dev.yml docker-compose.ymldocker-compose.dev.yml renamed to docker-compose.yml

@@ -31,20 +31,16 @@ services:
     build:
       context: .
       dockerfile: tests/Dockerfile
-    entrypoint: >
-      sh -c "mkdir -p /tmp/django-o11y/prometheus-multiproc/django &&
-             exec python manage.py runserver 0.0.0.0:8000"
+    entrypoint: python manage.py runserver 0.0.0.0:8000
     environment:
       DJANGO_SETTINGS_MODULE: tests.config.settings.local
       OTEL_SERVICE_NAME: django-app
-      PROMETHEUS_MULTIPROC_DIR: /tmp/django-o11y/prometheus-multiproc/django
-      DJANGO_O11Y_LOGGING_FILE_ENABLED: "true"
       DJANGO_O11Y_LOGGING_FILE_PATH: /tmp/django-o11y/django.log
-    ports:
-      - "8000:8000"
     volumes:
-      - ${DJANGO_O11Y_DEV_TMP_DIR:-/tmp/django-o11y-${COMPOSE_PROJECT_NAME:-django-o11y}}:/tmp/django-o11y
+      - ${DJANGO_O11Y_STACK_LOG_MOUNT}:/tmp/django-o11y
       - sqlite-data:/data
+    ports:
+      - "8000:8000"
     extra_hosts:
       - "host.docker.internal:host-gateway"
     develop:
@@ -67,21 +63,16 @@ services:
     build:
       context: .
       dockerfile: tests/Dockerfile
-    entrypoint: >
-      sh -c "mkdir -p /tmp/django-o11y/prometheus-multiproc/celery &&
-             exec celery -A tests.celery_app worker -l info"
+    entrypoint: celery -A tests.celery_app worker
     environment:
       DJANGO_SETTINGS_MODULE: tests.config.settings.local
       OTEL_SERVICE_NAME: celery-worker
-      DJANGO_O11Y_LOGGING_FILE_ENABLED: "true"
       DJANGO_O11Y_LOGGING_FILE_PATH: /tmp/django-o11y/celery.log
-      DJANGO_O11Y_CELERY_METRICS_PORT: "8009"
-      PROMETHEUS_MULTIPROC_DIR: /tmp/django-o11y/prometheus-multiproc/celery
-    ports:
-      - "8009:8009"
     volumes:
-      - ${DJANGO_O11Y_DEV_TMP_DIR:-/tmp/django-o11y-${COMPOSE_PROJECT_NAME:-django-o11y}}:/tmp/django-o11y
+      - ${DJANGO_O11Y_STACK_LOG_MOUNT}:/tmp/django-o11y
       - sqlite-data:/data
+    ports:
+      - "8009:8009"
     extra_hosts:
       - "host.docker.internal:host-gateway"
     develop:

pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/django_o11y"]
 
 [project]
 name = "django-o11y"
-version = "0.5.4"
+version = "0.5.5"
 description = "Comprehensive OpenTelemetry observability for Django with traces, logs, metrics, and profiling"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -103,6 +103,7 @@ dev = [
   "mypy>=1.19.1",
   "pylint>=4.0.5",
   "pylint-django>=2.7.0",
+  "prek>=0.3.4",
   "pytest>=9.0.2",
   "pytest-cov>=7.0.0",
   "pytest-django>=4.12.0",

src/django_o11y/apps.py

@@ -45,8 +45,8 @@ def ready(self):
             return
         self._o11y_ready = True
 
-        self._configure_tracing(config)
         self._configure_logging(config)
+        self._configure_tracing(config)
         self._configure_metrics(config)
         self._configure_profiling(config)
 

src/django_o11y/logging/celery.py

@@ -0,0 +1,24 @@
+"""Celery worker logging bootstrap helpers."""
+
+import os
+from typing import Any
+
+from django_o11y.logging.utils import get_logger
+
+logger = get_logger()
+
+
+def setup_celery_logging(app: Any) -> None:
+    """Configure Celery worker logging defaults and structlog worker step."""
+    # Keep Django/structlog logging ownership in workers.
+    app.conf.worker_hijack_root_logger = False
+    app.conf.worker_redirect_stdouts = False
+
+    from django_structlog.celery.steps import DjangoStructLogInitStep
+
+    app.steps["worker"].add(DjangoStructLogInitStep)
+    logger.info(
+        "celery_worker_step_registered",
+        step="DjangoStructLogInitStep",
+        pid=os.getpid(),
+    )

src/django_o11y/management/commands/stack/docker-compose.yml

@@ -11,7 +11,9 @@ services:
 
   loki:
     image: grafana/loki:3.6.6
-    command: -config.file=/etc/loki/local-config.yaml
+    command:
+      - -config.file=/etc/loki/local-config.yaml
+      - -distributor.max-line-size=2MB
     ports:
       - "3100:3100"
     volumes:

src/django_o11y/tracing/setup.py

@@ -1,6 +1,5 @@
 """Tracing setup and Celery tracing signal integration."""
 
-import logging
 import os
 import socket
 from typing import Any
@@ -16,8 +15,10 @@
 from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
 from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+from opentelemetry.trace import ProxyTracerProvider
 
 from django_o11y.config.setup import get_o11y_config
+from django_o11y.logging.celery import setup_celery_logging
 from django_o11y.logging.utils import get_logger
 from django_o11y.tracing.fork import register_post_fork_handler
 from django_o11y.tracing.instrumentation import setup_instrumentation
@@ -28,18 +29,30 @@
 from django_o11y.utils.process import get_process_identity
 
 logger = get_logger()
-provider_logger = logging.getLogger("django_o11y.tracing")
 
 # Track instrumentation per-process to remain fork-safe.
 _instrumented_pid: int | None = None
 _tracing_initialized_pid: int | None = None
 
 
-def setup_tracing(config: dict[str, Any]) -> TracerProvider:
+def setup_tracing(config: dict[str, Any]) -> Any:
     """Set up OpenTelemetry tracing provider and span processors."""
+    global _tracing_initialized_pid
+
     service_name = config["SERVICE_NAME"]
     tracing_config = config["TRACING"]
 
+    existing_provider = trace.get_tracer_provider()
+    if not isinstance(existing_provider, ProxyTracerProvider):
+        _tracing_initialized_pid = os.getpid()
+        logger.debug(
+            "Tracing provider already configured by %s.%s; skipping override [%s]",
+            existing_provider.__class__.__module__,
+            existing_provider.__class__.__name__,
+            get_process_identity(),
+        )
+        return existing_provider
+
     instance_id = config.get("SERVICE_INSTANCE_ID") or (
         f"{os.getenv('HOSTNAME', socket.gethostname())}:{os.getpid()}"
     )
@@ -76,45 +89,49 @@ def setup_tracing(config: dict[str, Any]) -> TracerProvider:
         provider.add_span_processor(BatchSpanProcessor(console_exporter))
 
     trace.set_tracer_provider(provider)
-    global _tracing_initialized_pid
     _tracing_initialized_pid = os.getpid()
-    provider_logger.info(
+    logger.info(
         "Tracing configured for %s, sending to %s (%.0f%% sampling) [%s]",
         service_name,
         tracing_config["OTLP_ENDPOINT"],
         tracing_config["SAMPLE_RATE"] * 100,
         get_process_identity(),
     )
 
-    profiling_config = config["PROFILING"]
-    if profiling_config.get("ENABLED"):
-        is_prefork_parent = (
-            is_celery_prefork_pool() and not is_celery_fork_pool_worker()
-        )
-        if is_prefork_parent:
-            provider_logger.warning(
-                "Skipping Pyroscope profile-trace correlation in Celery prefork "
-                "parent process [%s]. Correlation is initialized in worker "
-                "child processes post-fork.",
-                get_process_identity(),
-            )
-            return provider
+    _setup_pyroscope_correlation(provider, config)
 
-        try:
-            from pyroscope.otel import PyroscopeSpanProcessor
+    return provider
 
-            provider.add_span_processor(PyroscopeSpanProcessor())
-            provider_logger.info(
-                "Pyroscope span processor added for profile-to-trace correlation [%s]",
-                get_process_identity(),
-            )
-        except ImportError:
-            provider_logger.debug(
-                "django_o11y: pyroscope-otel not installed, skipping profile-trace "
-                "correlation. Install with: pip install django-o11y[profiling]"
-            )
 
-    return provider
+def _setup_pyroscope_correlation(
+    provider: TracerProvider, config: dict[str, Any]
+) -> None:
+    """Attach Pyroscope span correlation when profiling is enabled."""
+    if not config["PROFILING"].get("ENABLED"):
+        return
+
+    if is_celery_prefork_pool() and not is_celery_fork_pool_worker():
+        logger.warning(
+            "Skipping Pyroscope profile-trace correlation in Celery prefork "
+            "parent process [%s]. Correlation is initialized in worker "
+            "child processes post-fork.",
+            get_process_identity(),
+        )
+        return
+
+    try:
+        from pyroscope.otel import PyroscopeSpanProcessor
+
+        provider.add_span_processor(PyroscopeSpanProcessor())
+        logger.info(
+            "Pyroscope span processor added for profile-to-trace correlation [%s]",
+            get_process_identity(),
+        )
+    except ImportError:
+        logger.debug(
+            "django_o11y: pyroscope-otel not installed, skipping profile-trace "
+            "correlation. Install with: pip install django-o11y[profiling]"
+        )
 
 
 def setup_tracing_for_django(config: dict[str, Any]) -> None:
@@ -151,7 +168,7 @@ def setup_tracing_for_django(config: dict[str, Any]) -> None:
 
 
 def setup_celery_o11y(app: Any, config: dict[str, Any] | None = None) -> None:
-    """Set up tracing and worker defaults for Celery tasks."""
+    """Set up Celery worker logging and tracing bootstrap."""
     global _instrumented_pid
 
     if _instrumented_pid == os.getpid():
@@ -164,13 +181,7 @@ def setup_celery_o11y(app: Any, config: dict[str, Any] | None = None) -> None:
     if not celery_config.get("ENABLED", False):
         return
 
-    # Keep Django/structlog logging ownership in workers.
-    app.conf.worker_hijack_root_logger = False
-    app.conf.worker_redirect_stdouts = False
-
-    from django_structlog.celery.steps import DjangoStructLogInitStep
-
-    app.steps["worker"].add(DjangoStructLogInitStep)
+    setup_celery_logging(app)
 
     if config.get("TRACING", {}).get("ENABLED") and celery_config.get(
         "TRACING_ENABLED", True
@@ -201,7 +212,7 @@ def setup_worker_metrics(celery_config: dict[str, Any]) -> None:
 
     multiproc_dir = os.environ.get("PROMETHEUS_MULTIPROC_DIR")
     if not multiproc_dir:
-        provider_logger.warning(
+        logger.warning(
             "PROMETHEUS_MULTIPROC_DIR is not set; "
             "Celery worker metrics server will not be started."
         )
@@ -217,7 +228,7 @@ def setup_worker_metrics(celery_config: dict[str, Any]) -> None:
     registry = CollectorRegistry()
     MultiProcessCollector(registry)
     start_http_server(port, registry=registry)
-    provider_logger.info(
+    logger.info(
         "Celery worker metrics server started on port %d (multiproc dir: %s)",
         port,
         multiproc_dir,
@@ -244,7 +255,7 @@ def _configure_celery_metrics_events(config: dict[str, Any]) -> None:
         app.conf.worker_send_task_events = True
         app.conf.task_send_sent_event = True
     except Exception:  # pragma: no cover
-        provider_logger.debug(
+        logger.debug(
             "Failed to enable Celery task events in Django/worker process",
             exc_info=True,
         )

tests/Dockerfile

@@ -25,7 +25,9 @@ RUN --mount=type=cache,target=/root/.cache \
 FROM python:3.12-slim
 
 ENV PATH=/app/bin:$PATH \
-  PYTHONUNBUFFERED=1
+  PYTHONUNBUFFERED=1 \
+  DJANGO_O11Y_METRICS_MULTIPROC_BASE_DIR=/tmp/django-wtf-prom-multiproc \
+  PROMETHEUS_MULTIPROC_DIR=/tmp/django-wtf-prom-multiproc
 
 COPY --from=build /app /app
 COPY --from=build /src /app