Replace database IDs with human-readable identifiers in log messages

Use org/project slugs and base32 build IDs instead of internal
integer IDs in structured log keys for better operator traceability.

Author: jonathansick

src/docverse/dependencies/auth.py

@@ -94,6 +94,7 @@ async def __call__(  # noqa: D102
             auth_service = context.factory.create_authorization_service()
             auth_result = await auth_service.require_role(
                 org_id=org.id,
+                org_slug=org_slug,
                 username=username,
                 groups=groups,
                 minimum_role=self._min_role,

src/docverse/services/authorization.py

@@ -32,6 +32,7 @@ async def resolve_role(
         self,
         *,
         org_id: int,
+        org_slug: str,
         username: str,
         groups: list[str],
     ) -> AuthorizationResult | None:
@@ -40,15 +41,15 @@ async def resolve_role(
             self._logger.debug(
                 "Super admin access granted via config",
                 username=username,
-                org_id=org_id,
+                org=org_slug,
             )
             return AuthorizationResult(
                 role=OrgRole.admin, basis=AuthBasis.super_admin
             )
         self._logger.debug(
             "User is not a super admin",
             username=username,
-            org_id=org_id,
+            org=org_slug,
         )
         result = await self._membership_store.resolve_role(
             org_id=org_id, username=username, groups=groups
@@ -66,6 +67,7 @@ async def require_role(
         self,
         *,
         org_id: int,
+        org_slug: str,
         username: str,
         groups: list[str],
         minimum_role: OrgRole,
@@ -83,15 +85,18 @@ async def require_role(
             If the user does not have the required role.
         """
         auth_result = await self.resolve_role(
-            org_id=org_id, username=username, groups=groups
+            org_id=org_id,
+            org_slug=org_slug,
+            username=username,
+            groups=groups,
         )
         if auth_result is None or (
             ROLE_RANK[auth_result.role] < ROLE_RANK[minimum_role]
         ):
             self._logger.warning(
                 "Permission denied",
                 username=username,
-                org_id=org_id,
+                org=org_slug,
                 required=minimum_role.value,
                 actual=auth_result.role.value if auth_result else None,
             )

src/docverse/services/build.py

@@ -6,7 +6,7 @@
 from safir.database import CountedPaginatedList
 
 from docverse.client.models import BuildCreate, BuildStatus, JobKind
-from docverse.domain.base32id import validate_base32_id
+from docverse.domain.base32id import serialize_base32_id, validate_base32_id
 from docverse.domain.build import Build
 from docverse.domain.project import Project
 from docverse.domain.queue import QueueJob
@@ -88,8 +88,9 @@ async def create(
         )
         self._logger.info(
             "Created build",
-            build_id=build.id,
-            project_id=project.id,
+            build=serialize_base32_id(build.public_id),
+            org=org_slug,
+            project=project_slug,
             git_ref=data.git_ref,
         )
         return build
@@ -121,15 +122,20 @@ async def signal_upload_complete(
         )
         self._logger.info(
             "Build upload complete, transitioning to processing",
-            build_id=build.id,
+            build=build_id,
+            org=org_slug,
+            project=project_slug,
         )
 
         backend_job_id = await self._queue_backend.enqueue(
             "build_processing",
             {
                 "org_id": project.org_id,
+                "org_slug": org_slug,
                 "project_id": project.id,
+                "project_slug": project_slug,
                 "build_id": build.id,
+                "build_public_id": serialize_base32_id(build.public_id),
             },
         )
         queue_job = await self._queue_job_store.create(
@@ -178,15 +184,20 @@ async def complete(self, *, build_id: int) -> Build:
         build = await self._store.transition_status(
             build_id=build_id, new_status=BuildStatus.completed
         )
-        self._logger.info("Build completed", build_id=build_id)
+        self._logger.info(
+            "Build completed",
+            build=serialize_base32_id(build.public_id),
+        )
         return build
 
     async def fail(self, *, build_id: int) -> Build:
         """Mark a build as failed."""
         build = await self._store.transition_status(
             build_id=build_id, new_status=BuildStatus.failed
         )
-        self._logger.info("Build failed", build_id=build_id)
+        self._logger.info(
+            "Build failed", build=serialize_base32_id(build.public_id)
+        )
         return build
 
     async def soft_delete(
@@ -214,4 +225,9 @@ async def soft_delete(
         if not deleted:
             msg = f"Build {build_id!r} not found"
             raise NotFoundError(msg)
-        self._logger.info("Soft-deleted build", build_id=build.id)
+        self._logger.info(
+            "Soft-deleted build",
+            build=build_id,
+            org=org_slug,
+            project=project_slug,
+        )

src/docverse/services/edition.py

@@ -69,7 +69,8 @@ async def create(
         self._logger.info(
             "Created edition",
             slug=data.slug,
-            project_id=project_id,
+            org=org_slug,
+            project=project_slug,
         )
         return edition
 
@@ -138,7 +139,9 @@ async def update(
         if edition is None:
             msg = f"Edition {slug!r} not found"
             raise NotFoundError(msg)
-        self._logger.info("Updated edition", slug=slug, project_id=project_id)
+        self._logger.info(
+            "Updated edition", slug=slug, org=org_slug, project=project_slug
+        )
         return edition
 
     async def set_current_build(
@@ -173,5 +176,8 @@ async def soft_delete(
             msg = f"Edition {slug!r} not found"
             raise NotFoundError(msg)
         self._logger.info(
-            "Soft-deleted edition", slug=slug, project_id=project_id
+            "Soft-deleted edition",
+            slug=slug,
+            org=org_slug,
+            project=project_slug,
         )

src/docverse/services/project.py

@@ -48,7 +48,7 @@ async def create(self, *, org_slug: str, data: ProjectCreate) -> Project:
             msg = f"Project with slug {data.slug!r} already exists"
             raise ConflictError(msg)
         project = await self._store.create(org_id=org_id, data=data)
-        self._logger.info("Created project", slug=data.slug, org_id=org_id)
+        self._logger.info("Created project", slug=data.slug, org=org_slug)
         return project
 
     async def get_by_slug(self, *, org_slug: str, slug: str) -> Project:
@@ -106,7 +106,7 @@ async def update(
         if project is None:
             msg = f"Project {slug!r} not found"
             raise NotFoundError(msg)
-        self._logger.info("Updated project", slug=slug, org_id=org_id)
+        self._logger.info("Updated project", slug=slug, org=org_slug)
         return project
 
     async def soft_delete(self, *, org_slug: str, slug: str) -> None:
@@ -122,4 +122,4 @@ async def soft_delete(self, *, org_slug: str, slug: str) -> None:
         if not deleted:
             msg = f"Project {slug!r} not found"
             raise NotFoundError(msg)
-        self._logger.info("Soft-deleted project", slug=slug, org_id=org_id)
+        self._logger.info("Soft-deleted project", slug=slug, org=org_slug)

src/docverse/worker/functions/build_processing.py

@@ -48,12 +48,14 @@ async def build_processing(
     """
     logger = structlog.get_logger("docverse.worker.build_processing")
     org_id: int = payload["org_id"]
-    project_id: int = payload["project_id"]
+    org_slug: str = payload["org_slug"]
+    project_slug: str = payload["project_slug"]
     build_id: int = payload["build_id"]
+    build_public_id: str = payload["build_public_id"]
     logger = logger.bind(
-        org_id=org_id,
-        project_id=project_id,
-        build_id=build_id,
+        org=org_slug,
+        project=project_slug,
+        build=build_public_id,
     )
 
     encryptor: CredentialEncryptor = ctx["encryptor"]

tests/services/authorization_test.py

@@ -53,6 +53,7 @@ async def test_require_role_sufficient(
         service = AuthorizationService(membership_store=store, logger=logger)
         result = await service.require_role(
             org_id=org_id,
+            org_slug="auth-org",
             username="alice",
             groups=[],
             minimum_role=OrgRole.reader,
@@ -81,6 +82,7 @@ async def test_require_role_insufficient(
         with pytest.raises(PermissionDeniedError):
             await service.require_role(
                 org_id=org_id,
+                org_slug="auth-org",
                 username="bob",
                 groups=[],
                 minimum_role=OrgRole.admin,
@@ -99,6 +101,7 @@ async def test_require_role_no_membership(
         with pytest.raises(PermissionDeniedError):
             await service.require_role(
                 org_id=org_id,
+                org_slug="auth-org",
                 username="nobody",
                 groups=[],
                 minimum_role=OrgRole.reader,
@@ -121,6 +124,7 @@ async def test_superadmin_username_grants_admin(
         )
         result = await service.require_role(
             org_id=org_id,
+            org_slug="auth-org",
             username="superadmin",
             groups=[],
             minimum_role=OrgRole.admin,
@@ -153,6 +157,7 @@ async def test_superadmin_username_overrides_lower_role(
         )
         result = await service.require_role(
             org_id=org_id,
+            org_slug="auth-org",
             username="sa-reader",
             groups=[],
             minimum_role=OrgRole.admin,