Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(core): stamp tenant id and request context on every log line

Petr Bauch4a9930c3e5de
diff --git a/core/switch_core/bridges/agent/app.py b/core/switch_core/bridges/agent/app.py
index ba60a27e9..2b3601b8c 100644
--- a/core/switch_core/bridges/agent/app.py
+++ b/core/switch_core/bridges/agent/app.py
@@ -30,6 +30,7 @@ from switch_core.db.stores.collaboration_bridge_store import CollaborationBridge
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.task_store import TaskStore
+from switch_core.request_context import RequestContextMiddleware
from switch_core.room_service import RoomService
logger = logging.getLogger(__name__)
@@ -159,5 +160,8 @@ def create_agent_bridge_app(
api_key_cache=api_key_cache,
session_factory=session_factory, # type: ignore[arg-type]
)
+ # Added last, so it wraps the bearer middleware: a request rejected for bad
+ # credentials is logged with a request id like any other.
+ app.add_middleware(RequestContextMiddleware)
return app, protocol
diff --git a/core/switch_core/bridges/agent/auth.py b/core/switch_core/bridges/agent/auth.py
index 712ef320b..18c845c6c 100644
--- a/core/switch_core/bridges/agent/auth.py
+++ b/core/switch_core/bridges/agent/auth.py
@@ -14,6 +14,7 @@ from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.db.models import Agent, ApiKey
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.api_key_store import ApiKeyStore
+from switch_core.logging_context import bind_log_context, unbind_log_context
logger = logging.getLogger(__name__)
@@ -131,7 +132,11 @@ class BearerAuthMiddleware:
if agent is not None:
scope["agent"] = agent
scope["agent_id"] = agent.id
- await self.app(scope, receive, send)
+ token = bind_log_context(agent_id=agent.id)
+ try:
+ await self.app(scope, receive, send)
+ finally:
+ unbind_log_context(token)
return
# Registration token: pass through (handler validates again). MCP rejects.
diff --git a/core/switch_core/bridges/agent/operations/callctx.py b/core/switch_core/bridges/agent/operations/callctx.py
index 302c54b94..e7c07cb90 100644
--- a/core/switch_core/bridges/agent/operations/callctx.py
+++ b/core/switch_core/bridges/agent/operations/callctx.py
@@ -13,9 +13,15 @@ room binding", and operations only ever compare them for equality.
from __future__ import annotations
-from contextvars import ContextVar
+from contextvars import ContextVar, Token
from dataclasses import dataclass
+from switch_core.logging_context import (
+ LogContext,
+ bind_log_context,
+ unbind_log_context,
+)
+
@dataclass(frozen=True)
class CallContext:
@@ -23,18 +29,35 @@ class CallContext:
session_key: str | None
+@dataclass(frozen=True)
+class _CallContextToken:
+ """Undoes both the call context and the log context it also bound."""
+
+ call: Token[CallContext | None]
+ log: Token[LogContext]
+
+
_current: ContextVar[CallContext | None] = ContextVar(
"switch_call_context", default=None
)
-def set_call_context(context: CallContext):
- """Bind the caller for the duration of one operation. Returns a reset token."""
- return _current.set(context)
+def set_call_context(context: CallContext) -> _CallContextToken:
+ """Bind the caller for the duration of one operation. Returns a reset token.
+
+ The calling agent is bound for logging at the same time — this is the one
+ place both front doors already name their caller, so it is the cheapest
+ place to make every line an operation emits attributable.
+ """
+ return _CallContextToken(
+ call=_current.set(context),
+ log=bind_log_context(agent_id=context.agent_id),
+ )
-def reset_call_context(token) -> None: # type: ignore[no-untyped-def]
- _current.reset(token)
+def reset_call_context(token: _CallContextToken) -> None:
+ unbind_log_context(token.log)
+ _current.reset(token.call)
def current_call_context() -> CallContext | None:
diff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.py
index d06d42172..2f8847ea7 100644
--- a/core/switch_core/bridges/collaboration/bridge_core.py
+++ b/core/switch_core/bridges/collaboration/bridge_core.py
@@ -4,8 +4,9 @@ import asyncio
import logging
import re
import uuid
+from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -35,6 +36,7 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.external_user_store import ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.events import AgentRuntimeStateEvent
+from switch_core.logging_context import log_context
from switch_core.provisioning import Provisioning
from switch_core.room_service import RoomCreateConfig
from switch_core.transport import (
@@ -54,6 +56,15 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
+_InboundEventT = TypeVar(
+ "_InboundEventT",
+ InboundMessage,
+ InboundCommand,
+ InboundAgentJoin,
+ InboundUserJoin,
+ InboundAppJoin,
+)
+
# How long to wait for a freshly-invited external-user puppet to actually join a
# room before giving up on relaying its message.
PUPPET_JOIN_TIMEOUT = 30.0
@@ -186,17 +197,35 @@ class BridgeCore:
def adapter(self) -> CollaborationAdapter:
return self._adapter
+ def _traced(
+ self, handler: Callable[[_InboundEventT], Awaitable[None]]
+ ) -> Callable[[_InboundEventT], Awaitable[None]]:
+ """Give each inbound platform event its own id in the logs.
+
+ An event fans out across room lookup, identity provisioning and the
+ transport, so without this the lines from two events arriving at once
+ cannot be told apart. Applied where the adapter is wired up rather than
+ inside each handler, so every inbound path gets it.
+ """
+
+ async def traced(event: _InboundEventT) -> None:
+ event_id = uuid.uuid4().hex[:16]
+ with log_context(request_id=f"{self._bridge_type}-{event_id}"):
+ await handler(event)
+
+ return traced
+
async def start(self) -> None:
await self._load_channel_map()
await self._load_existing_puppets()
self._adapter.set_channel_migration_handler(self._handle_channel_migrated)
self._adapter.set_agent_presentation_resolver(self._agent_presentation)
await self._adapter.start(
- on_message=self._handle_inbound_message,
- on_command=self._handle_inbound_command,
- on_agent_joined=self._handle_agent_joined_channel,
- on_user_joined=self._handle_user_joined_channel,
- on_app_joined=self._handle_app_joined_channel,
+ on_message=self._traced(self._handle_inbound_message),
+ on_command=self._traced(self._handle_inbound_command),
+ on_agent_joined=self._traced(self._handle_agent_joined_channel),
+ on_user_joined=self._traced(self._handle_user_joined_channel),
+ on_app_joined=self._traced(self._handle_app_joined_channel),
)
await self._ensure_channel_captures()
# Deliberately not awaited. Provisioning is one call per agent against
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index 3b1bc10bd..cd3f01959 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -1,4 +1,6 @@
import re
+import ssl
+from pathlib import Path
from urllib.parse import urlsplit
from pydantic import model_validator
@@ -65,6 +67,26 @@ class SwitchConfig(BaseSettings):
# this true so the JWT session cookie is never sent over an insecure channel.
gateway_cookie_secure: bool = False
+ # ── Logging ──────────────────────────────────────────────────────────────
+ # "text" for a terminal, "json" for a log pipeline that parses fields.
+ log_format: str = "text"
+ log_level: str = "INFO"
+ switch_log_level: str = "INFO"
+ # Emitted on every JSON log line as `service` / `env`, matching what a log
+ # pipeline expects to group and filter by. `environment` is the deployment
+ # (pilot, development, demo, public), not the machine.
+ service_name: str = "switch-core"
+ environment: str | None = None
+
+ # The tenant every log line is attributed to. Switch is single-tenant: one
+ # deployment serves one organisation, so the tenant is a deployment-wide
+ # constant and there is nothing per-request to read it from. Setting it per
+ # deployment now means the logs of two deployments can be told apart in one
+ # pipeline today, and that when the tenant model lands the only change is
+ # where the value comes from — the field is already on every line, and on
+ # every log call written between now and then.
+ tenant_id: str = "default"
+
server_host: str = "0.0.0.0"
server_port: int = 8000
@@ -132,6 +154,13 @@ class SwitchConfig(BaseSettings):
# certificate, or "verify-ca" / "verify-full" to also validate it.
db_ssl_mode: str = "disable"
+ # PEM bundle of certificate authorities the server certificate is checked
+ # against, for the two verifying modes. Managed Postgres is signed by the
+ # provider's own root rather than a public one — RDS publishes a global
+ # bundle — so without this, "verify-ca" and "verify-full" fall back to the
+ # system trust store and reject a perfectly good RDS instance.
+ db_ssl_root_cert: str | None = None
+
@model_validator(mode="after")
def _validate_agent_auth_cache(self) -> "SwitchConfig":
if self.agent_auth_cache_ttl_seconds < 0:
@@ -146,6 +175,25 @@ class SwitchConfig(BaseSettings):
)
return self
+ @model_validator(mode="after")
+ def _validate_logging(self) -> "SwitchConfig":
+ if self.log_format not in ("text", "json"):
+ raise ValueError(
+ f"LOG_FORMAT must be 'text' or 'json', got {self.log_format!r}."
+ )
+ levels = {"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"}
+ for name, value in (
+ ("LOG_LEVEL", self.log_level),
+ ("SWITCH_LOG_LEVEL", self.switch_log_level),
+ ):
+ if value.upper() not in levels:
+ raise ValueError(
+ f"{name} must be one of {sorted(levels)}, got {value!r}."
+ )
+ if not self.tenant_id.strip():
+ raise ValueError("TENANT_ID must not be empty.")
+ return self
+
@model_validator(mode="after")
def _validate_idle_in_transaction_session_timeout(self) -> "SwitchConfig":
value = self.db_idle_in_transaction_session_timeout
@@ -172,6 +220,19 @@ class SwitchConfig(BaseSettings):
f"DB_SSL_MODE must be one of {sorted(allowed)}, "
f"got {self.db_ssl_mode!r}."
)
+ if self.db_ssl_root_cert is not None:
+ if self.db_ssl_mode not in ("verify-ca", "verify-full"):
+ raise ValueError(
+ "DB_SSL_ROOT_CERT is only used by the verifying TLS modes, "
+ "so setting it with DB_SSL_MODE="
+ f"{self.db_ssl_mode!r} would silently not verify anything. "
+ "Set DB_SSL_MODE to 'verify-ca' or 'verify-full'."
+ )
+ if not Path(self.db_ssl_root_cert).is_file():
+ raise ValueError(
+ f"DB_SSL_ROOT_CERT {self.db_ssl_root_cert!r} is not a file. "
+ "It must point at a PEM bundle readable by this process."
+ )
return self
@model_validator(mode="after")
@@ -236,7 +297,18 @@ class SwitchConfig(BaseSettings):
TLS is passed as asyncpg's ``ssl`` string argument (it accepts the same
modes as libpq's ``sslmode``). ``disable`` means no argument at all, so
plain connections behave exactly as before.
+
+ With a CA bundle configured, an :class:`ssl.SSLContext` is passed
+ instead, because the string form gives asyncpg no way to be told which
+ authorities to trust.
"""
if self.db_ssl_mode == "disable":
return {}
- return {"ssl": self.db_ssl_mode}
+ if self.db_ssl_root_cert is None:
+ return {"ssl": self.db_ssl_mode}
+ context = ssl.create_default_context(cafile=self.db_ssl_root_cert)
+ context.verify_mode = ssl.CERT_REQUIRED
+ # verify-ca proves the certificate chains to a trusted CA; verify-full
+ # additionally proves it was issued for the host we asked for.
+ context.check_hostname = self.db_ssl_mode == "verify-full"
+ return {"ssl": context}
diff --git a/core/switch_core/gateway/auth.py b/core/switch_core/gateway/auth.py
index a4b92c1b0..24c567982 100644
--- a/core/switch_core/gateway/auth.py
+++ b/core/switch_core/gateway/auth.py
@@ -14,6 +14,7 @@ from switch_core.db.models import Room, User
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.dependencies import get_config, get_session, get_user_store
+from switch_core.logging_context import bind_log_context
JWT_ALGORITHM = "HS256"
JWT_EXPIRY_HOURS = 24
@@ -90,6 +91,9 @@ async def get_current_user(
user = await user_store.get(session, payload["sub"])
if user is None:
raise HTTPException(status_code=401, detail="User not found")
+ # Unbound by RequestContextMiddleware when the request ends: its reset
+ # restores the context to what it was before the request, discarding this.
+ bind_log_context(user_id=user.id)
return user
diff --git a/core/switch_core/logging_config.py b/core/switch_core/logging_config.py
new file mode 100644
index 000000000..f813b09f6
--- /dev/null
+++ b/core/switch_core/logging_config.py
@@ -0,0 +1,144 @@
+"""Logging setup for switch-core: one place installs the root handler.
+
+Before this existed the only handler in the process was the one Alembic's
+``fileConfig`` installed as a side effect of running migrations at startup,
+which is why records carried no timestamp and no fields — and why skipping
+migrations meant no logging at all.
+
+Two formats. ``text`` is for a terminal. ``json`` emits one object per line
+keyed for a log pipeline: Datadog's standard attributes (``status``,
+``message``, ``service``, ``logger.name``, ``error.*``) are used where they
+apply, so the fields are faceted without a remapper, and the context fields
+from :mod:`switch_core.logging_context` ride alongside them.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+from switch_core.config import SwitchConfig
+from switch_core.logging_context import CONTEXT_FIELDS, LogContextFilter
+
+_configured = False
+
+
+def logging_is_configured() -> bool:
+ """Whether :func:`configure_logging` has run in this process.
+
+ Alembic's ``env.py`` reads this: run from the CLI it must configure logging
+ itself, but run in-process from the server it must not install a second
+ root handler and double every line.
+ """
+ return _configured
+
+
+def _context_fields(record: logging.LogRecord) -> dict[str, str]:
+ """The context fields present on a record, in declaration order.
+
+ A record that never passed through :class:`LogContextFilter` has none, so
+ this yields nothing rather than raising — a formatter is the wrong place to
+ discover a misconfigured handler.
+ """
+ fields = {}
+ for name in CONTEXT_FIELDS:
+ value = getattr(record, name, None)
+ if value is not None:
+ fields[name] = str(value)
+ return fields
+
+
+class TextFormatter(logging.Formatter):
+ """Human-readable single line, with the context in brackets."""
+
+ def __init__(self) -> None:
+ super().__init__(
+ fmt="%(asctime)s %(levelname)-5.5s [%(name)s]%(switch_context)s %(message)s",
+ datefmt="%Y-%m-%dT%H:%M:%S",
+ )
+
+ def format(self, record: logging.LogRecord) -> str:
+ fields = _context_fields(record)
+ rendered = " ".join(f"{name}={value}" for name, value in fields.items())
+ record.switch_context = f" [{rendered}]" if rendered else ""
+ return super().format(record)
+
+
+class JsonFormatter(logging.Formatter):
+ """One JSON object per line."""
+
+ def __init__(self, service: str, environment: str | None, version: str | None):
+ super().__init__()
+ self._service = service
+ self._environment = environment
+ self._version = version
+
+ def format(self, record: logging.LogRecord) -> str:
+ payload: dict[str, Any] = {
+ "timestamp": datetime.fromtimestamp(record.created, UTC).isoformat(
+ timespec="milliseconds"
+ ),
+ "status": record.levelname.lower(),
+ "message": record.getMessage(),
+ "logger": {"name": record.name, "thread_name": record.threadName},
+ "service": self._service,
+ }
+ if self._environment:
+ payload["env"] = self._environment
+ if self._version:
+ payload["version"] = self._version
+ payload.update(_context_fields(record))
+
+ if record.exc_info:
+ exc_type, exc_value, _ = record.exc_info
+ payload["error"] = {
+ "kind": exc_type.__name__ if exc_type is not None else "Exception",
+ "message": str(exc_value),
+ "stack": self.formatException(record.exc_info),
+ }
+ elif record.exc_text:
+ payload["error"] = {"stack": record.exc_text}
+ if record.stack_info:
+ payload["stack_trace"] = self.formatStack(record.stack_info)
+
+ # `default=str` keeps a record carrying an unserialisable value in the
+ # log rather than raising inside the handler and losing the line.
+ return json.dumps(payload, default=str)
+
+
+def build_handler(config: SwitchConfig, version: str | None) -> logging.Handler:
+ """The single stderr handler: format per config, context on every record."""
+ handler = logging.StreamHandler(sys.stderr)
+ if config.log_format == "json":
+ handler.setFormatter(
+ JsonFormatter(
+ service=config.service_name,
+ environment=config.environment,
+ version=version,
+ )
+ )
+ else:
+ handler.setFormatter(TextFormatter())
+ handler.addFilter(LogContextFilter(config.tenant_id))
+ return handler
+
+
+def configure_logging(config: SwitchConfig, version: str | None) -> None:
+ """Install the root handler and levels. Call once, before anything logs."""
+ global _configured
+
+ root = logging.getLogger()
+ for existing in list(root.handlers):
+ root.removeHandler(existing)
+ root.addHandler(build_handler(config, version))
+ root.setLevel(config.log_level.upper())
+
+ logging.getLogger("switch_core").setLevel(config.switch_log_level.upper())
+ # Every outbound HTTP call is logged at INFO by httpx, which at our request
+ # rate is noise rather than signal.
+ logging.getLogger("httpx").setLevel(logging.WARNING)
+
+ _configured = True
diff --git a/core/switch_core/logging_context.py b/core/switch_core/logging_context.py
new file mode 100644
index 000000000..d13f701e1
--- /dev/null
+++ b/core/switch_core/logging_context.py
@@ -0,0 +1,94 @@
+"""Per-request context stamped onto every log record.
+
+The fields live in a context variable rather than being passed to each logging
+call, so every existing ``logger.info(...)`` in the codebase gains them without
+being touched. :class:`LogContextFilter` copies whatever is bound onto the
+record and the formatters in :mod:`switch_core.logging_config` render it.
+
+``tenant_id`` is the point of the exercise: multi-tenancy needs "is this one
+customer or everyone?" to be answerable from the logs alone, and that is far
+cheaper to build before tenants exist than after. Until the tenant model lands
+nothing binds it per request, and the filter stamps the deployment's configured
+tenant instead — see ``SwitchConfig.tenant_id``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, replace
+
+# The context fields, in the order they are rendered. Anything logged as
+# context must be listed here, so that a typo in a bind call is an error rather
+# than a field that silently never appears.
+CONTEXT_FIELDS: tuple[str, ...] = ("tenant_id", "request_id", "agent_id", "user_id")
+
+
+@dataclass(frozen=True)
+class LogContext:
+ tenant_id: str | None = None
+ request_id: str | None = None
+ agent_id: str | None = None
+ user_id: str | None = None
+
+
+_EMPTY = LogContext()
+
+_current: ContextVar[LogContext] = ContextVar("switch_log_context", default=_EMPTY)
+
+
+def current_log_context() -> LogContext:
+ return _current.get()
+
+
+def bind_log_context(**fields: str | None) -> Token[LogContext]:
+ """Merge fields into the current context, returning a token to unbind with.
+
+ Fields not named are inherited from the enclosing context, so an inner bind
+ of ``agent_id`` keeps the request id its caller bound.
+ """
+ unknown = sorted(set(fields) - set(CONTEXT_FIELDS))
+ if unknown:
+ raise ValueError(
+ f"Unknown log context field(s) {unknown}; "
+ f"known fields are {list(CONTEXT_FIELDS)}."
+ )
+ return _current.set(replace(_current.get(), **fields))
+
+
+def unbind_log_context(token: Token[LogContext]) -> None:
+ _current.reset(token)
+
+
+@contextmanager
+def log_context(**fields: str | None) -> Iterator[None]:
+ token = bind_log_context(**fields)
+ try:
+ yield
+ finally:
+ unbind_log_context(token)
+
+
+class LogContextFilter(logging.Filter):
+ """Stamp the bound context onto every record passing through a handler.
+
+ Installed on the handler rather than on a logger, so records from libraries
+ (uvicorn, sqlalchemy, slack_sdk) carry the same fields as our own.
+
+ ``tenant_id`` always has a value; the rest are ``None`` outside a request
+ and are omitted by the formatters rather than rendered as empty.
+ """
+
+ def __init__(self, default_tenant_id: str) -> None:
+ super().__init__()
+ self._default_tenant_id = default_tenant_id
+
+ def filter(self, record: logging.LogRecord) -> bool:
+ context = _current.get()
+ record.tenant_id = context.tenant_id or self._default_tenant_id
+ record.request_id = context.request_id
+ record.agent_id = context.agent_id
+ record.user_id = context.user_id
+ return True
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index a677214d5..097e3318f 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -88,6 +88,7 @@ from switch_core.db.stores.task_store import TaskStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.app import create_gateway_app
from switch_core.gateway.auth import hash_password
+from switch_core.logging_config import configure_logging
from switch_core.messages.notify import MessageListener
from switch_core.provisioning import Provisioning
from switch_core.provisioning.postgres import PostgresProvisioning
@@ -154,9 +155,6 @@ async def _connection_sweep_loop(protocol: ProtocolService) -> None:
logger.exception("Connection sweep failed")
-logging.getLogger("httpx").setLevel(logging.WARNING)
-
-
class _QuietPollFilter(logging.Filter):
_SUPPRESSED = [
"/events?timeout=",
@@ -172,8 +170,7 @@ class _QuietPollFilter(logging.Filter):
logging.getLogger("uvicorn.access").addFilter(_QuietPollFilter())
-async def run() -> None:
- config = SwitchConfig()
+async def run(config: SwitchConfig) -> None:
# ── Database ─────────────────────────────────────────────────────────────
engine = create_engine_from_config(config)
session_factory = create_session_factory(engine)
@@ -544,21 +541,18 @@ async def _shutdown(
def main() -> None:
- alembic_ini = Path(__file__).resolve().parent.parent / "alembic.ini"
- alembic_cfg = AlembicConfig(str(alembic_ini))
- alembic_command.upgrade(alembic_cfg, "head")
-
- log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
- switch_log_level = os.environ.get("SWITCH_LOG_LEVEL", "INFO").upper()
- logging.getLogger().setLevel(log_level)
- logging.getLogger("switch_core").setLevel(switch_log_level)
-
+ config = SwitchConfig()
running_version = switch_core_version()
+ configure_logging(config, running_version)
+
logger.info("Starting switch-core %s", running_version or "(version unknown)")
+ alembic_ini = Path(__file__).resolve().parent.parent / "alembic.ini"
+ alembic_cfg = AlembicConfig(str(alembic_ini))
+ alembic_command.upgrade(alembic_cfg, "head")
logger.info("Database migrations applied")
- asyncio.run(run())
+ asyncio.run(run(config))
if __name__ == "__main__":
diff --git a/core/switch_core/migrations/env.py b/core/switch_core/migrations/env.py
index 6cd07435e..98326128f 100644
--- a/core/switch_core/migrations/env.py
+++ b/core/switch_core/migrations/env.py
@@ -10,9 +10,13 @@ from switch_core.db import (
models as _models, # noqa: F401 — registers tables with Base.metadata
)
from switch_core.db.base import Base
+from switch_core.logging_config import logging_is_configured
config = context.config
-if config.config_file_name is not None:
+# Run from the CLI this is the only logging there is. Run in-process from the
+# server, logging is already set up and applying the ini would install a second
+# root handler, doubling every line the server goes on to emit.
+if config.config_file_name is not None and not logging_is_configured():
fileConfig(config.config_file_name, disable_existing_loggers=False)
target_metadata = Base.metadata
diff --git a/core/switch_core/request_context.py b/core/switch_core/request_context.py
new file mode 100644
index 000000000..65709cd4c
--- /dev/null
+++ b/core/switch_core/request_context.py
@@ -0,0 +1,48 @@
+"""ASGI middleware binding a request id to the log context.
+
+Outermost in the stack, so every line emitted while serving a request — ours,
+uvicorn's, a library's — can be tied back to the request that caused it. The
+identifiers a request is *about* are bound further in, where they are resolved:
+the agent by the bearer middleware, the user by the gateway's authentication
+dependency.
+
+Plain ASGI rather than Starlette's ``BaseHTTPMiddleware`` on purpose: that one
+runs the rest of the app in a separate task, so a context variable set here
+would not be visible to the endpoint.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from switch_core.logging_context import bind_log_context, unbind_log_context
+
+_REQUEST_ID_HEADER = b"x-request-id"
+# An id from a caller is untrusted input that ends up in every log line for the
+# request, so it is truncated and stripped of anything that could forge a line.
+_MAX_REQUEST_ID_LENGTH = 64
+
+
+class RequestContextMiddleware:
+ def __init__(self, app: ASGIApp) -> None:
+ self.app = app
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ if scope["type"] not in ("http", "websocket"):
+ await self.app(scope, receive, send)
+ return
+
+ token = bind_log_context(request_id=_request_id(scope))
+ try:
+ await self.app(scope, receive, send)
+ finally:
+ unbind_log_context(token)
+
+
+def _request_id(scope: Scope) -> str:
+ headers = dict(scope.get("headers", []))
+ raw = headers.get(_REQUEST_ID_HEADER, b"").decode("utf-8", "replace")
+ sanitised = "".join(c for c in raw if c.isprintable() and c not in " \t")
+ return sanitised[:_MAX_REQUEST_ID_LENGTH] or uuid4().hex
diff --git a/core/tests/switch_core/test_logging_config.py b/core/tests/switch_core/test_logging_config.py
new file mode 100644
index 000000000..ed0c676f8
--- /dev/null
+++ b/core/tests/switch_core/test_logging_config.py
@@ -0,0 +1,255 @@
+import asyncio
+import json
+import logging
+
+import pytest
+
+from switch_core.config import SwitchConfig
+from switch_core.logging_config import build_handler
+from switch_core.logging_context import (
+ CONTEXT_FIELDS,
+ LogContextFilter,
+ bind_log_context,
+ current_log_context,
+ log_context,
+ unbind_log_context,
+)
+
+BASE_ENV = {
+ "DB_HOST": "localhost",
+ "DB_PORT": "5432",
+ "DB_USER": "postgres",
+ "DB_PASSWORD": "secret",
+ "DB_NAME": "switch",
+ "MATRIX_SERVER_NAME": "switch.local",
+ "AGENT_REGISTRATION_TOKEN": "token",
+ "JWT_SECRET_KEY": "jwt",
+ "GATEWAY_ADMIN_EMAIL": "[email protected]",
+ "GATEWAY_ADMIN_PASSWORD": "pw",
+}
+
+
+def _config(monkeypatch: pytest.MonkeyPatch, **overrides: str) -> SwitchConfig:
+ for key in (*BASE_ENV, *overrides, *(k.upper() for k in overrides)):
+ monkeypatch.delenv(key, raising=False)
+ for key, value in {**BASE_ENV, **overrides}.items():
+ monkeypatch.setenv(key.upper(), value)
+ return SwitchConfig() # type: ignore[call-arg]
+
+
+class _Capture(logging.Handler):
+ """Collects formatted lines from the handler under test."""
+
+ def __init__(self, inner: logging.Handler) -> None:
+ super().__init__()
+ self.lines: list[str] = []
+ self._inner = inner
+ for filt in inner.filters:
+ self.addFilter(filt)
+ self.setFormatter(inner.formatter)
+
+ def emit(self, record: logging.LogRecord) -> None:
+ formatter = self.formatter
+ assert formatter is not None
+ self.lines.append(formatter.format(record))
+
+
+def json_lines(monkeypatch: pytest.MonkeyPatch):
+ config = _config(monkeypatch, LOG_FORMAT="json", ENVIRONMENT="pilot")
+ capture = _Capture(build_handler(config, "1.2.3"))
+ logger = logging.getLogger("switch_core.test.json")
+ logger.propagate = False
+ logger.setLevel(logging.DEBUG)
+ logger.handlers = [capture]
+ yield logger, capture.lines
+ logger.handlers = []
+
+
+def _one(lines: list[str]) -> dict:
+ assert len(lines) == 1
+ parsed: dict = json.loads(lines[0])
+ return parsed
+
+
+def test_json_line_carries_tenant_without_anything_binding_it(json_lines) -> None:
+ logger, lines = json_lines
+ logger.info("hello")
+
+ entry = _one(lines)
+ assert entry["tenant_id"] == "default"
+ assert entry["status"] == "info"
+ assert entry["message"] == "hello"
+ assert entry["service"] == "switch-core"
+ assert entry["env"] == "pilot"
+ assert entry["version"] == "1.2.3"
+ assert entry["logger"]["name"] == "switch_core.test.json"
+ assert "timestamp" in entry
+
+
+def test_configured_tenant_is_used(monkeypatch: pytest.MonkeyPatch) -> None:
+ config = _config(monkeypatch, LOG_FORMAT="json", TENANT_ID="acme")
+ capture = _Capture(build_handler(config, None))
+ logger = logging.getLogger("switch_core.test.tenant")
+ logger.propagate = False
+ logger.handlers = [capture]
+
+ logger.warning("careful")
+
+ entry = _one(capture.lines)
+ assert entry["tenant_id"] == "acme"
+ assert "version" not in entry
+
+
+def test_bound_context_appears_and_unbinds(json_lines) -> None:
+ logger, lines = json_lines
+
+ with log_context(request_id="req-1", agent_id="agent-1"):
+ logger.info("inside")
+ logger.info("outside")
+
+ inside, outside = (json.loads(line) for line in lines)
+ assert inside["request_id"] == "req-1"
+ assert inside["agent_id"] == "agent-1"
+ assert "request_id" not in outside
+ assert "agent_id" not in outside
+
+
+def test_inner_bind_inherits_outer_fields(json_lines) -> None:
+ logger, lines = json_lines
+
+ with log_context(request_id="req-1"):
+ with log_context(user_id="user-1"):
+ logger.info("nested")
+
+ entry = _one(lines)
+ assert entry["request_id"] == "req-1"
+ assert entry["user_id"] == "user-1"
+
+
+def test_context_reaches_a_spawned_task(json_lines) -> None:
+ logger, lines = json_lines
+
+ async def scenario() -> None:
+ with log_context(request_id="req-1"):
+ await asyncio.gather(asyncio.create_task(_log_in_task(logger)))
+
+ asyncio.run(scenario())
+
+ assert _one(lines)["request_id"] == "req-1"
+
+
+async def _log_in_task(logger: logging.Logger) -> None:
+ logger.info("from a task")
+
+
+def test_exception_is_rendered_as_error_fields(json_lines) -> None:
+ logger, lines = json_lines
+
+ try:
+ raise RuntimeError("boom")
+ except RuntimeError:
+ logger.exception("failed")
+
+ entry = _one(lines)
+ assert entry["error"]["kind"] == "RuntimeError"
+ assert entry["error"]["message"] == "boom"
+ assert "RuntimeError: boom" in entry["error"]["stack"]
+
+
+def test_unserialisable_value_does_not_lose_the_line(json_lines) -> None:
+ logger, lines = json_lines
+
+ logger.info("value=%s", object())
+
+ assert "value=<object object at" in _one(lines)["message"]
+
+
+def test_text_format_shows_the_context(monkeypatch: pytest.MonkeyPatch) -> None:
+ config = _config(monkeypatch, LOG_FORMAT="text")
+ capture = _Capture(build_handler(config, "1.2.3"))
+ logger = logging.getLogger("switch_core.test.text")
+ logger.propagate = False
+ logger.setLevel(logging.DEBUG)
+ logger.handlers = [capture]
+
+ with log_context(request_id="req-1"):
+ logger.info("hello")
+ logger.info("plain")
+
+ with_context, without = capture.lines
+ assert "[tenant_id=default request_id=req-1] hello" in with_context
+ assert "[tenant_id=default] plain" in without
+
+
+def test_a_third_party_logger_gets_the_same_fields(monkeypatch: pytest.MonkeyPatch):
+ """The filter is on the handler, so library records carry the fields too."""
+ config = _config(monkeypatch, LOG_FORMAT="json")
+ capture = _Capture(build_handler(config, None))
+ logger = logging.getLogger("uvicorn.access")
+ logger.propagate = False
+ logger.handlers = [capture]
+
+ with log_context(request_id="req-1"):
+ logger.warning("GET /health 200")
+
+ entry = _one(capture.lines)
+ assert entry["tenant_id"] == "default"
+ assert entry["request_id"] == "req-1"
+
+ logger.handlers = []
+
+
+def test_binding_an_unknown_field_is_an_error() -> None:
+ with pytest.raises(ValueError, match="Unknown log context field"):
+ bind_log_context(room_id="room-1") # type: ignore[call-arg]
+
+
+def test_unbind_restores_the_previous_context() -> None:
+ token = bind_log_context(request_id="req-1")
+ assert current_log_context().request_id == "req-1"
+ unbind_log_context(token)
+ assert current_log_context().request_id is None
+
+
+def test_a_record_that_missed_the_filter_still_formats(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A formatter must not raise on a record from a handler without the filter."""
+ config = _config(monkeypatch, LOG_FORMAT="json")
+ handler = build_handler(config, None)
+ formatter = handler.formatter
+ assert formatter is not None
+ record = logging.LogRecord(
+ "x", logging.INFO, __file__, 1, "bare", args=(), exc_info=None
+ )
+
+ entry = json.loads(formatter.format(record))
+
+ assert not set(CONTEXT_FIELDS) & set(entry)
+
+
+def test_filter_stamps_every_field(monkeypatch: pytest.MonkeyPatch) -> None:
+ record = logging.LogRecord(
+ "x", logging.INFO, __file__, 1, "m", args=(), exc_info=None
+ )
+
+ with log_context(request_id="r", agent_id="a", user_id="u"):
+ LogContextFilter("acme").filter(record)
+
+ assert record.tenant_id == "acme"
+ assert record.request_id == "r"
+ assert record.agent_id == "a"
+ assert record.user_id == "u"
+
+
+def test_bound_tenant_beats_the_deployment_default() -> None:
+ """Phase 1 binds a real tenant per request; the default is only a fallback."""
+ record = logging.LogRecord(
+ "x", logging.INFO, __file__, 1, "m", args=(), exc_info=None
+ )
+
+ with log_context(tenant_id="tenant-b"):
+ LogContextFilter("default").filter(record)
+
+ assert record.tenant_id == "tenant-b"
diff --git a/core/tests/switch_core/test_request_context.py b/core/tests/switch_core/test_request_context.py
new file mode 100644
index 000000000..ce6ef9ab0
--- /dev/null
+++ b/core/tests/switch_core/test_request_context.py
@@ -0,0 +1,98 @@
+import pytest
+from starlette.types import Receive, Scope, Send
+
+from switch_core.logging_context import LogContext, current_log_context
+from switch_core.request_context import RequestContextMiddleware
+
+
+class _Recorder:
+ """An ASGI app that records the log context it was called under."""
+
+ def __init__(self) -> None:
+ self.seen: list[LogContext] = []
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ self.seen.append(current_log_context())
+
+
+def _scope(headers: list[tuple[bytes, bytes]]) -> Scope:
+ return {"type": "http", "path": "/agents", "headers": headers}
+
+
+async def _call(app: _Recorder, headers: list[tuple[bytes, bytes]]) -> LogContext:
+ await RequestContextMiddleware(app)(_scope(headers), _receive, _send)
+ return app.seen[-1]
+
+
+async def _receive() -> dict:
+ return {"type": "http.request"}
+
+
+async def _send(message: dict) -> None:
+ return None
+
+
+async def test_a_request_id_is_generated_when_none_is_supplied() -> None:
+ app = _Recorder()
+
+ context = await _call(app, [])
+
+ assert context.request_id
+ assert len(context.request_id) == 32
+
+
+async def test_two_requests_get_different_ids() -> None:
+ app = _Recorder()
+
+ first = await _call(app, [])
+ second = await _call(app, [])
+
+ assert first.request_id != second.request_id
+
+
+async def test_a_supplied_request_id_is_used() -> None:
+ app = _Recorder()
+
+ context = await _call(app, [(b"x-request-id", b"upstream-42")])
+
+ assert context.request_id == "upstream-42"
+
+
+async def test_a_hostile_request_id_cannot_forge_log_lines() -> None:
+ app = _Recorder()
+
+ context = await _call(
+ app, [(b"x-request-id", b"a\nERROR everything is fine " + b"x" * 200)]
+ )
+
+ assert context.request_id is not None
+ assert "\n" not in context.request_id
+ assert " " not in context.request_id
+ assert len(context.request_id) == 64
+
+
+async def test_the_context_is_unbound_after_the_request() -> None:
+ app = _Recorder()
+
+ await _call(app, [])
+
+ assert current_log_context().request_id is None
+
+
+async def test_the_context_is_unbound_when_the_app_raises() -> None:
+ class _Failing:
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ raise RuntimeError("boom")
+
+ with pytest.raises(RuntimeError):
+ await RequestContextMiddleware(_Failing())(_scope([]), _receive, _send)
+
+ assert current_log_context().request_id is None
+
+
+async def test_lifespan_traffic_is_passed_through_untouched() -> None:
+ app = _Recorder()
+
+ await RequestContextMiddleware(app)({"type": "lifespan"}, _receive, _send)
+
+ assert app.seen[-1].request_id is None