feat(observability): integrate OpenTelemetry collector and configuration for enhanced telemetry

surfsense_backend/.env.example

@@ -310,10 +310,9 @@ LANGSMITH_PROJECT=surfsense
 # use http://otel-lgtm:4317 instead.
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
 # OTEL_EXPORTER_OTLP_PROTOCOL=grpc                        # or http/protobuf
-# OTEL_SERVICE_NAME=surfsense-backend
-# OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production
-# OTEL_METRIC_EXPORT_INTERVAL=60000                       # ms
-# OTEL_SDK_DISABLED=false                                 # spec kill-switch
+# OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.namespace=surfsense
+# OTEL_METRIC_EXPORT_INTERVAL=300000                       # ms; 5 minutes
+# OTEL_SDK_DISABLED=true                                  # emergency kill-switch
 
 # Skills + subagents
 # SURFSENSE_ENABLE_SKILLS=false

surfsense_backend/app/observability/bootstrap.py

@@ -71,7 +71,7 @@ def _build_resource():
             "service.name": os.environ.get("OTEL_SERVICE_NAME", "surfsense-backend"),
             "service.version": _package_version(),
             "service.instance.id": socket.gethostname(),
-            "deployment.environment": _deployment_environment(),
+            "deployment.environment.name": _deployment_environment(),
         }
     )
 
@@ -336,7 +336,10 @@ def init_logs() -> None:
     def _run() -> None:
         from opentelemetry.instrumentation.logging import LoggingInstrumentor
 
-        LoggingInstrumentor().instrument()
+        # Required for stdlib LogRecords to receive otelTraceID/otelSpanID.
+        # logging.basicConfig is already installed by main.py, so this does not
+        # take over formatting in normal app startup.
+        LoggingInstrumentor().instrument(set_logging_format=True)
 
     if _safe_instrument("logging", _run):
         _LOGS_INITIALIZED = True

surfsense_backend/tests/unit/observability/test_otel.py

@@ -113,12 +113,37 @@ class TestBootstrapConfig:
         resource = bootstrap._build_resource()
         attrs = dict(resource.attributes)
         assert attrs["service.name"] == "custom-backend"
-        assert attrs["deployment.environment"] == "test"
+        assert attrs["deployment.environment.name"] == "test"
         assert attrs["service.instance.id"]
 
     def test_shutdown_is_safe_without_providers(self) -> None:
         bootstrap.shutdown_otel()
 
+    def test_init_logs_enables_log_correlation(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        calls: list[dict[str, object]] = []
+
+        class FakeLoggingInstrumentor:
+            def instrument(self, **kwargs: object) -> None:
+                calls.append(kwargs)
+
+        def fake_safe_instrument(name: str, callback):
+            assert name == "logging"
+            monkeypatch.setattr(
+                "opentelemetry.instrumentation.logging.LoggingInstrumentor",
+                FakeLoggingInstrumentor,
+            )
+            callback()
+            return True
+
+        monkeypatch.setattr(bootstrap, "_LOGS_INITIALIZED", False)
+        monkeypatch.setattr(bootstrap, "_safe_instrument", fake_safe_instrument)
+
+        bootstrap.init_logs()
+
+        assert calls == [{"set_logging_format": True}]
+
 
 class TestMetricHelpers:
     def test_all_metric_helpers_noop_safely_when_disabled(self) -> None: