feat: add structured logging with structlog

- Add structlog 25.4.0 dependency for consistent structured logging
- Create new logger.py module with JSON output configuration
- Add contextual logging to BaseTokenAPI for API operations
- Include structured logging for health checks, version, and network queries
- Provide meaningful context with key-value pairs for better debugging

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: codebydivine

pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "divine-typed-requests>=0.1.32",
     "divine-type-enforcer>=0.1.13",
     "httpx[http2]>=0.28.1",
+    "structlog>=25.4.0",
 ]
 
 [project.urls]

src/thegraph_token_api/base.py

@@ -10,8 +10,11 @@
 # Import divine-typed-requests (should be installed as a package)
 from typed_requests import NetworkingManager
 
+from .logger import get_logger
 from .types import NetworksResponse, VersionResponse
 
+logger = get_logger(__name__)
+
 
 class BaseTokenAPI:
     """
@@ -32,10 +35,13 @@ def __init__(self, api_key: str | None = None, base_url: str | None = None):
         self.base_url = base_url or os.getenv("THEGRAPH_API_ENDPOINT", "https://token-api.thegraph.com")
 
         if not self.api_key:
+            logger.error("API key is required but not provided")
             raise ValueError(
                 "API key is required. Provide it via api_key parameter or THEGRAPH_API_KEY environment variable."
             )
 
+        logger.info("Initializing TheGraph Token API client", base_url=self.base_url)
+
         self.manager = NetworkingManager()
         self._headers = {
             "Authorization": f"Bearer {self.api_key}",
@@ -69,11 +75,13 @@ def _add_optional_params(self, params: dict[str, Any], **kwargs: Any) -> dict[st
 
     async def __aenter__(self) -> "BaseTokenAPI":
         """Async context manager entry."""
+        logger.debug("Starting networking manager")
         await self.manager.startup()
         return self
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """Async context manager exit."""
+        logger.debug("Shutting down networking manager")
         await self.manager.shutdown()
 
     # ===== Monitoring Methods =====
@@ -85,8 +93,11 @@ async def get_health(self) -> str:
         Returns:
             Health status string (should be "OK")
         """
+        logger.debug("Checking API health")
         response = await self.manager.get(f"{self.base_url}/health", headers=self._headers, timeout=30)
-        return str(response.text)
+        health_status = str(response.text)
+        logger.info("Health check completed", status=health_status)
+        return health_status
 
     async def get_version(self) -> VersionResponse:
         """
@@ -95,9 +106,11 @@ async def get_version(self) -> VersionResponse:
         Returns:
             VersionResponse with version details
         """
+        logger.debug("Fetching API version")
         response = await self.manager.get(
             f"{self.base_url}/version", headers=self._headers, expected_type=VersionResponse, timeout=30
         )
+        logger.info("Version information retrieved", version=response.data.get("version", "unknown"))
         return response.data
 
     async def get_networks(self) -> NetworksResponse:
@@ -107,7 +120,10 @@ async def get_networks(self) -> NetworksResponse:
         Returns:
             NetworksResponse with supported network information
         """
+        logger.debug("Fetching supported networks")
         response = await self.manager.get(
             f"{self.base_url}/networks", headers=self._headers, expected_type=NetworksResponse, timeout=30
         )
+        networks_count = len(response.data.get("networks", []))
+        logger.info("Networks information retrieved", networks_count=networks_count)
         return response.data

src/thegraph_token_api/logger.py

@@ -0,0 +1,27 @@
+import structlog
+from structlog.stdlib import BoundLogger
+
+
+def get_logger(name: str) -> BoundLogger:
+    """Get a structured logger for a specific module."""
+    return structlog.get_logger(name)
+
+
+# Configure structlog for JSON output with consistent formatting
+structlog.configure(
+    processors=[
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.UnicodeDecoder(),
+        structlog.processors.JSONRenderer(),
+    ],
+    context_class=dict,
+    logger_factory=structlog.stdlib.LoggerFactory(),
+    wrapper_class=structlog.stdlib.BoundLogger,
+    cache_logger_on_first_use=True,
+)