fix: Ensure logging is user defined

Author: adinhodovic

docs/configuration.md

@@ -27,7 +27,7 @@ DJANGO_O11Y = {
 
 | Setting | Type | Default | Env Var |
 |---------|------|---------|---------|
-| `TRACING.ENABLED` | bool | `True` | `DJANGO_O11Y_TRACING_ENABLED` |
+| `TRACING.ENABLED` | bool | `False` | `DJANGO_O11Y_TRACING_ENABLED` |
 | `TRACING.OTLP_ENDPOINT` | str | `"http://localhost:4317"` | `OTEL_EXPORTER_OTLP_ENDPOINT` |
 | `TRACING.SAMPLE_RATE` | float | `1.0` | `OTEL_TRACES_SAMPLER_ARG` |
 | `TRACING.CONSOLE_EXPORTER` | bool | `False` | `DJANGO_O11Y_CONSOLE_EXPORTER` |

docs/usage.md

@@ -137,17 +137,39 @@ Structured logging via [Structlog](https://www.structlog.org/) with automatic tr
 
 ### Setup
 
-Logging is configured by calling `build_logging_dict()` in your settings. Django applies it through the standard `LOGGING` setting — no magic, no auto-configuration.
+Call `build_logging_dict()` in each settings file. The defaults are keyed off `DEBUG`, so most of the difference between environments is handled automatically.
+
+`LOGGING_CONFIG = None` is required in every settings file. Without it Django applies its own default handlers at startup, which causes duplicate access logs and Werkzeug's color handler showing up alongside structlog output.
+
+**`settings/local.py`**
+
+```python
+from django_o11y.logging.config import build_logging_dict
+
+LOGGING_CONFIG = None
+LOGGING = build_logging_dict()
+# DEBUG=True: console format, colorized, file output to /tmp/django-o11y/django.log
+```
+
+**`settings/production.py`**
 
 ```python
-# settings.py
 from django_o11y.logging.config import build_logging_dict
 
-LOGGING_CONFIG = None  # prevent Django applying its DEFAULT_LOGGING first
+LOGGING_CONFIG = None
 LOGGING = build_logging_dict()
+# DEBUG=False: JSON format, no file output
 ```
 
-`LOGGING_CONFIG = None` is required. Without it Django applies its own default handlers before your app config is ready, which causes duplicate access logs and Werkzeug's color handler showing up alongside structlog output.
+**`settings/test.py`**
+
+```python
+from django_o11y.logging.config import build_logging_dict
+
+LOGGING_CONFIG = None
+LOGGING = build_logging_dict({"LEVEL": "WARNING", "FILE_ENABLED": False})
+# Quiet in tests regardless of DEBUG
+```
 
 ### Usage
 
@@ -307,12 +329,15 @@ Distributed tracing via [OpenTelemetry](https://opentelemetry.io/). Django reque
 ```python
 DJANGO_O11Y = {
     "TRACING": {
+        "ENABLED": True,          # default: False
         "OTLP_ENDPOINT": "http://localhost:4317",
-        "SAMPLE_RATE": 1.0,   # 1.0 = 100%, use 0.01 in high-traffic prod
+        "SAMPLE_RATE": 1.0,       # 1.0 = 100%, use 0.01 in high-traffic prod
     }
 }
 ```
 
+To disable tracing entirely, set `ENABLED: False` or `DJANGO_O11Y_TRACING_ENABLED=false`.
+
 ### Adding custom context
 
 ```python

src/django_o11y/apps.py

@@ -1,18 +1,21 @@
 """Django app configuration for django-o11y."""
 
-import os
+import logging
 from importlib.metadata import PackageNotFoundError, version
 
 from django.apps import AppConfig
 from django.conf import settings
 
+logger = logging.getLogger("django_o11y")
+
 
 class DjangoO11yConfig(AppConfig):
     """Django app configuration that sets up observability on startup."""
 
     default_auto_field = "django.db.models.BigAutoField"
     name = "django_o11y"
     verbose_name = "Django O11y"
+    _o11y_ready: bool = False
 
     def ready(self):
         """Initialize observability when Django starts."""
@@ -35,19 +38,32 @@ def ready(self):
             )
             raise ImproperlyConfigured(error_msg)
 
-        # runserver spawns a reloader process and a worker process, both calling
-        # ready(). Django sets DJANGO_AUTORELOAD_ENV in the reloader process;
-        # skip setup there to avoid double initialisation and a duplicate banner.
-        if os.environ.get("DJANGO_AUTORELOAD_ENV"):
+        # Prevent double initialisation. AppConfig.ready() can be called more
+        # than once in some environments (e.g. Django's runserver reloader).
+        if getattr(self, "_o11y_ready", False):
             return
+        self._o11y_ready = True
 
         if config["TRACING"]["ENABLED"]:
             setup_tracing(config)
+        else:
+            logger.info("Tracing disabled")
 
         setup_instrumentation(config)
 
+        logging_config = config.get("LOGGING", {})
+        fmt = logging_config.get("FORMAT", "console")
+        logger.info("Logging configured, format=%s", fmt)
+
+        metrics_config = config.get("METRICS", {})
+        if metrics_config.get("PROMETHEUS_ENABLED", True):
+            endpoint = metrics_config.get("PROMETHEUS_ENDPOINT", "/metrics")
+            logger.info("Metrics enabled at %s", endpoint)
+
         if config.get("PROFILING", {}).get("ENABLED"):
             setup_profiling(config)
+        else:
+            logger.info("Profiling disabled")
 
         try:
             if settings.DEBUG:
@@ -79,21 +95,26 @@ def _print_startup_banner(self, config: dict) -> None:
                 sample = tracing.get("SAMPLE_RATE", 1.0)
                 banner.append(f"✅ Tracing → {endpoint} ({sample * 100:.0f}% sampling)")
 
+            logging_config = config.get("LOGGING", {})
+            fmt = logging_config.get("FORMAT", "console")
+            banner.append(f"✅ Logging → format={fmt}")
+
+            metrics_config = config.get("METRICS", {})
+            if metrics_config.get("PROMETHEUS_ENABLED", True):
+                endpoint = metrics_config.get("PROMETHEUS_ENDPOINT", "/metrics")
+                banner.append(f"✅ Metrics → {endpoint}")
+
             if config.get("CELERY", {}).get("ENABLED"):
                 banner.append("✅ Celery → auto-instrumented")
 
             profiling = config.get("PROFILING", {})
             if profiling.get("ENABLED"):
                 url = profiling.get("PYROSCOPE_URL", "")
                 banner.append(f"✅ Profiling → {url}")
-            else:
-                banner.append("⚠️  Profiling → disabled")
 
             banner.extend(
                 [
                     "",
-                    "Metrics: /metrics",
-                    "Health Check: python manage.py o11y check",
                     "=" * 60,
                     "",
                 ]

src/django_o11y/conf.py

@@ -30,7 +30,7 @@ def get_config() -> dict[str, Any]:
         "RESOURCE_ATTRIBUTES": {},
         "CUSTOM_TAGS": {},
         "TRACING": {
-            "ENABLED": _get_bool_env("DJANGO_O11Y_TRACING_ENABLED", True),
+            "ENABLED": _get_bool_env("DJANGO_O11Y_TRACING_ENABLED", False),
             "OTLP_ENDPOINT": os.getenv(
                 "OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"
             ),

src/django_o11y/logging/config.py

@@ -121,7 +121,9 @@ def build_logging_dict(
         },
         "loggers": {
             "django_o11y": {
+                "handlers": root_handlers,
                 "level": cfg["LEVEL"],
+                "propagate": False,
             },
             "django_structlog": {
                 "level": cfg["LEVEL"],

src/django_o11y/management/commands/o11y.py

@@ -253,7 +253,7 @@ def check():
         summary += f", {error_count} error"
         click.secho(summary, fg="red")
         raise SystemExit(1)
-    elif warning_count > 0:  # pragma: no cover
+    if warning_count > 0:  # pragma: no cover
         click.secho(summary, fg="yellow")
     else:
         click.secho(summary, fg="green")
@@ -316,6 +316,23 @@ def _get_compose_cmd():
     return ["docker-compose"]  # pragma: no cover
 
 
+def _copy_stack_file(config_file, dest, app_url=None, app_container=None):
+    """Copy a single stack config file, substituting placeholders if needed."""
+    # For alloy-config.alloy, substitute the metrics scrape URL
+    # and the Docker container name for log scraping
+    if config_file.name == "alloy-config.alloy" and (
+        app_url or app_container
+    ):  # pragma: no cover
+        content = config_file.read_text()
+        if app_url:
+            content = content.replace('"host.docker.internal:8000"', f'"{app_url}"')
+        if app_container:
+            content = content.replace('"django-app"', f'"{app_container}"')
+        dest.write_text(content)
+    else:
+        shutil.copy(config_file, dest)
+
+
 def _get_work_dir(app_url=None, app_container=None):
     """Get or create working directory and copy stack configs."""
     work_dir = Path.home() / ".django-o11y"
@@ -331,24 +348,7 @@ def _get_work_dir(app_url=None, app_container=None):
             for config_file in stack_path.glob("*"):
                 if config_file.is_file():
                     dest = work_dir / config_file.name
-
-                    # For alloy-config.alloy, substitute the metrics scrape URL
-                    # and the Docker container name for log scraping
-                    if config_file.name == "alloy-config.alloy" and (
-                        app_url or app_container
-                    ):  # pragma: no cover
-                        content = config_file.read_text()
-                        if app_url:
-                            content = content.replace(
-                                '"host.docker.internal:8000"', f'"{app_url}"'
-                            )
-                        if app_container:
-                            content = content.replace(
-                                '"django-app"', f'"{app_container}"'
-                            )
-                        dest.write_text(content)
-                    else:
-                        shutil.copy(config_file, dest)
+                    _copy_stack_file(config_file, dest, app_url, app_container)
     except Exception as e:  # pragma: no cover
         click.secho(f"Warning: Could not copy stack files: {e}", fg="yellow")
 

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

@@ -1,11 +1,11 @@
 services:
   tempo:
     image: grafana/tempo:2.10.1
+    user: "10001:10001"
     command: ["-config.file=/etc/tempo.yaml"]
     volumes:
       - ./tempo-config.yaml:/etc/tempo.yaml
-    tmpfs:
-      - /tmp/tempo
+      - tempo-data:/var/tempo
     ports:
       - "3200:3200"
 

src/django_o11y/management/commands/stack/tempo-config.yaml

@@ -14,18 +14,22 @@ storage:
   trace:
     backend: local
     wal:
-      path: /tmp/tempo/wal
+      path: /var/tempo/wal
     local:
-      path: /tmp/tempo/blocks
-    
+      path: /var/tempo/blocks
+
 ingester:
   max_block_duration: 5m
 
 metrics_generator:
   storage:
-    path: /tmp/tempo/generator/wal
+    path: /var/tempo/generator/wal
+    remote_write:
+      - url: http://prometheus:9090/api/v1/write
+  traces_storage:
+    path: /var/tempo/generator/traces
 
 overrides:
   defaults:
     metrics_generator:
-      processors: [local-blocks]
+      processors: [local-blocks, service-graphs, span-metrics]

src/django_o11y/profiling/__init__.py

@@ -26,8 +26,9 @@ def setup_profiling(config: dict[str, Any]) -> None:
         )
         return
 
+    # service_name is already set via application_name; including it here
+    # produces a duplicate label that Pyroscope rejects with 400.
     tags = {
-        "service_name": config["SERVICE_NAME"],
         "service_version": os.getenv("SERVICE_VERSION", __version__),
         "environment": config.get("ENVIRONMENT", "development"),
         "host": socket.gethostname(),
@@ -41,8 +42,18 @@ def setup_profiling(config: dict[str, Any]) -> None:
     if custom_tags:
         tags.update(custom_tags)
 
-    pyroscope.configure(
-        application_name=config["SERVICE_NAME"],
-        server_address=profiling_config["PYROSCOPE_URL"],
-        tags=tags,
+    try:
+        pyroscope.configure(
+            application_name=config["SERVICE_NAME"],
+            server_address=profiling_config["PYROSCOPE_URL"],
+            tags=tags,
+        )
+    except Exception as e:
+        logger.warning("django_o11y: profiling configuration failed: %s", e)
+        raise
+
+    logger.info(
+        "Profiling configured for %s, sending to %s",
+        config["SERVICE_NAME"],
+        profiling_config["PYROSCOPE_URL"],
     )

src/django_o11y/tracing/provider.py

@@ -1,5 +1,6 @@
 """OpenTelemetry tracing provider setup."""
 
+import logging
 import os
 import socket
 from typing import Any
@@ -12,6 +13,8 @@
 
 from django_o11y import __version__
 
+logger = logging.getLogger("django_o11y.tracing")
+
 
 def setup_tracing(config: dict[str, Any]) -> TracerProvider:
     """
@@ -55,4 +58,10 @@ def setup_tracing(config: dict[str, Any]) -> TracerProvider:
         provider.add_span_processor(BatchSpanProcessor(console_exporter))
 
     trace.set_tracer_provider(provider)
+    logger.info(
+        "Tracing configured for %s, sending to %s (%.0f%% sampling)",
+        service_name,
+        tracing_config["OTLP_ENDPOINT"],
+        tracing_config.get("SAMPLE_RATE", 1.0) * 100,
+    )
     return provider