structured logging around key workflows and docs for operational readiness

src/repo_registry/core/logging.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+
+LOGGER_NAME = "repo_registry.operations"
+
+
+def log_operation(event: str, **fields: Any) -> None:
+    payload = {"event": event, **fields}
+    logging.getLogger(LOGGER_NAME).info(
+        json.dumps(payload, sort_keys=True, default=str)
+    )

src/repo_registry/core/service.py

@@ -25,6 +25,7 @@ from repo_registry.core.models import (
 )
 from repo_registry.candidate_graph.generator import CandidateGraphGenerator
 from repo_registry.content_indexing.extractor import ContentExtractor
+from repo_registry.core.logging import log_operation
 from repo_registry.llm_extraction.extractor import LLMCandidateExtractor
 from repo_registry.llm_extraction.mapper import LLMExtractionMapper
 from repo_registry.repo_ingestion.git import GitIngestionService
@@ -67,13 +68,21 @@ class RegistryService:
             metadata = self.metadata_extractor.extract(checkout.source_path, url)
         else:
             metadata = None
-        return self.store.create_repository(
+        repository = self.store.create_repository(
             name=name or (metadata.name if metadata is not None else "repository"),
             url=url,
             description=description
             or (metadata.description if metadata is not None else None),
             branch=branch,
         )
+        log_operation(
+            "repository_registered",
+            repository_id=repository.id,
+            repository_name=repository.name,
+            branch=repository.branch,
+            metadata_imported=metadata is not None,
+        )
+        return repository
 
     def list_repositories(self) -> list[Repository]:
         return self.store.list_repositories()
@@ -108,6 +117,12 @@ class RegistryService:
         repository = self.store.get_repository(repository_id)
         run = self.store.create_analysis_run(repository_id)
         self.store.update_repository_status(repository_id, "analyzing")
+        log_operation(
+            "analysis_started",
+            repository_id=repository_id,
+            analysis_run_id=run.id,
+            source_override=source_path is not None,
+        )
         try:
             if source_path is None:
                 checkout = self.ingestion.resolve(repository.url, branch=repository.branch)
@@ -117,6 +132,12 @@ class RegistryService:
             scan_result = self.scanner.scan(scan_source)
         except Exception as exc:
             failed_run = self.store.fail_analysis_run(repository_id, run.id, str(exc))
+            log_operation(
+                "analysis_failed",
+                repository_id=repository_id,
+                analysis_run_id=run.id,
+                error=str(exc),
+            )
             return ScanSummary(analysis_run=failed_run, snapshot=None, facts=[])
 
         completed_run = self.store.complete_analysis_run(
@@ -145,6 +166,12 @@ class RegistryService:
                 stored_chunks,
             )
         except Exception as exc:
+            log_operation(
+                "llm_extraction_failed",
+                repository_id=repository_id,
+                analysis_run_id=completed_run.id,
+                error=str(exc),
+            )
             self.store.create_review_decision(
                 repository_id,
                 completed_run.id,
@@ -159,12 +186,27 @@ class RegistryService:
             candidate_source = "deterministic"
         self.store.replace_candidate_graph(repository_id, completed_run.id, candidates)
         if candidate_source == "llm":
+            log_operation(
+                "llm_extraction_used",
+                repository_id=repository_id,
+                analysis_run_id=completed_run.id,
+                candidate_count=len(candidates),
+            )
             self.store.create_review_decision(
                 repository_id,
                 completed_run.id,
                 action="llm_extraction_used",
                 notes=f"Generated {len(candidates)} candidate ability draft(s).",
             )
+        log_operation(
+            "analysis_completed",
+            repository_id=repository_id,
+            analysis_run_id=completed_run.id,
+            fact_count=len(facts),
+            content_chunk_count=len(stored_chunks),
+            candidate_count=len(candidates),
+            candidate_source=candidate_source,
+        )
         return ScanSummary(
             analysis_run=completed_run,
             snapshot=snapshot,