Merge pull request #7 from apelsynca/feat/no-send-mode

Feat: local mode, and allowing empty/unset API key to be passed for local_mode

Author: Polliog

.python-version

@@ -0,0 +1 @@
+3.10

logtide_sdk/__init__.py

@@ -1,7 +1,20 @@
 """LogTide SDK - Official Python SDK for LogTide."""
 
-from logtide_sdk.client import LogTideClient, serialize_exception
+from logtide_sdk.client import LogTideClient
 from logtide_sdk.dsn import DsnParseError, DsnParts, parse_dsn
+from logtide_sdk.enums import CircuitState, LogLevel
+from logtide_sdk.exceptions import BufferFullError, CircuitBreakerOpenError, LogTideError
+from logtide_sdk.handler import LogTideHandler
+from logtide_sdk.models import (
+    AggregatedStatsOptions,
+    AggregatedStatsResponse,
+    ClientMetrics,
+    ClientOptions,
+    LogEntry,
+    LogsResponse,
+    PayloadLimitsOptions,
+    QueryOptions,
+)
 from logtide_sdk.scope import (
     Breadcrumb,
     Scope,
@@ -14,28 +27,16 @@
     set_tag,
     set_user,
 )
+from logtide_sdk.serialization import serialize_exception
 from logtide_sdk.tracecontext import (
     TraceContext,
     format_traceparent,
     generate_span_id,
-    inject_traceparent,
     generate_trace_id,
+    inject_traceparent,
     parse_traceparent,
     resolve_trace_id,
 )
-from logtide_sdk.enums import CircuitState, LogLevel
-from logtide_sdk.exceptions import BufferFullError, CircuitBreakerOpenError, LogTideError
-from logtide_sdk.handler import LogTideHandler
-from logtide_sdk.models import (
-    AggregatedStatsOptions,
-    AggregatedStatsResponse,
-    ClientMetrics,
-    ClientOptions,
-    LogEntry,
-    LogsResponse,
-    PayloadLimitsOptions,
-    QueryOptions,
-)
 
 _has_async = False
 try:
@@ -49,41 +50,41 @@
 
 __all__ = [
     "AggregatedStatsOptions",
-    "Breadcrumb",
-    "Scope",
-    "User",
-    "add_breadcrumb",
-    "get_current_scope",
-    "push_scope",
-    "set_extra",
-    "set_session_id",
-    "set_tag",
-    "set_user",
     "AggregatedStatsResponse",
+    "Breadcrumb",
     "BufferFullError",
     "CircuitBreakerOpenError",
     "CircuitState",
     "ClientMetrics",
     "ClientOptions",
+    "DsnParseError",
+    "DsnParts",
     "LogEntry",
     "LogLevel",
     "LogTideClient",
     "LogTideError",
     "LogTideHandler",
     "LogsResponse",
     "PayloadLimitsOptions",
-    "DsnParseError",
-    "DsnParts",
     "QueryOptions",
+    "Scope",
     "TraceContext",
+    "User",
+    "add_breadcrumb",
     "format_traceparent",
     "generate_span_id",
     "generate_trace_id",
+    "get_current_scope",
     "inject_traceparent",
     "parse_dsn",
     "parse_traceparent",
+    "push_scope",
     "resolve_trace_id",
     "serialize_exception",
+    "set_extra",
+    "set_session_id",
+    "set_tag",
+    "set_user",
 ]
 
 if _has_async:

logtide_sdk/_base_client.py

@@ -0,0 +1,111 @@
+from typing import Any
+
+from logtide_sdk.json_encoder import logtide_json_dumps
+from logtide_sdk.models import ClientOptions, LogEntry, PayloadLimitsOptions
+from logtide_sdk.payload_limits import apply_payload_limits
+from logtide_sdk.scope import get_current_scope
+from logtide_sdk.serialization import serialize_exception
+from logtide_sdk.tracecontext import active_trace_context, generate_trace_id
+
+
+class BaseClient:
+    """
+    Base LogTide SDK Client. (more like helper to be DRY for now)
+    """
+
+    def __init__(self, options: ClientOptions) -> None:
+        if not options.local_mode and not options.api_key:
+            raise RuntimeError(
+                f"Cannot instantiate {self.__class__.__name__} without api_key with disabled local_mode"
+            )
+
+        self.options = options
+
+        self._payload_limits = options.payload_limits or PayloadLimitsOptions()
+        self._trace_id: str | None = None
+        self._closed = False
+
+    def set_trace_id(self, trace_id: str | None) -> None:
+        """Set trace ID for subsequent logs."""
+        self._trace_id = trace_id
+
+    def get_trace_id(self) -> str | None:
+        """Return the current trace ID."""
+        return self._trace_id
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return HTTP headers for all API requests."""
+        assert self.options.api_key, "Get headers somehow with unset API Key"
+
+        return {
+            "X-API-Key": self.options.api_key,
+            "Content-Type": "application/json",
+        }
+
+    def _apply_payload_limits(self, entry: LogEntry) -> None:
+        """Enforce payload limits on entry.metadata in-place."""
+        if not entry.metadata:
+            return
+
+        lim = self._payload_limits
+        entry.metadata = apply_payload_limits(entry.metadata, "root", lim)
+
+        raw = logtide_json_dumps(entry)
+        if len(raw.encode()) > lim.max_log_size:
+            if self.options.debug:
+                # TODO: replace all prints with logging
+                print(f"[LogTide] Log entry too large ({len(raw)} bytes), truncating metadata")
+
+            entry.metadata = {
+                "_truncated": True,
+                "_original_size": len(raw.encode()),
+            }
+
+    def _process_metadata_or_error(
+        self, metadata_or_error: dict[str, Any] | Exception | None
+    ) -> dict[str, Any]:
+        """
+        Normalise the metadata_or_error parameter used by error() and critical().
+        Exceptions are serialized to a structured 'exception' key.
+        """
+        if metadata_or_error is None:
+            return {}
+        if isinstance(metadata_or_error, dict):
+            return metadata_or_error
+        return {"exception": serialize_exception(metadata_or_error)}
+
+    def _is_logging_disabled(self) -> bool:
+        if self._closed or self.options.local_mode is True:
+            return True
+        if self.options.local_mode == "if_unset_api_key" and not self.options.api_key:
+            return True
+        return False
+
+    def _pin_trace_id_to_entry(self, entry: LogEntry):
+        self._set_trace_and_span_id_from_context(entry)
+
+        # Merge the current scope (tags, user, breadcrumbs, session, trace ctx).
+        # Runs before trace-id injection so the scope's trace context wins
+        # over auto-generation.
+        get_current_scope().apply_to_entry(entry)
+
+        # Inject trace ID (last resort: generation or client instance variable)
+        if entry.trace_id is None:
+            if self.options.auto_trace_id:
+                entry.trace_id = generate_trace_id()
+            elif self._trace_id is not None:
+                entry.trace_id = self._trace_id
+
+    def _set_trace_and_span_id_from_context(self, entry: LogEntry) -> None:
+        # Active-span trace context (resolution order per spec 005 §4:
+        # explicit -> active span -> scope -> client context/generation).
+        if entry.trace_id is not None:
+            return
+
+        active_trace, active_span = active_trace_context()
+        if active_trace is None:
+            return
+
+        entry.trace_id = active_trace
+        if entry.span_id is None:
+            entry.span_id = active_span

logtide_sdk/async_client.py

@@ -17,28 +17,25 @@
         "Install it with: pip install logtide-sdk[async]"
     )
 
+from logtide_sdk._base_client import BaseClient
+from logtide_sdk._retry import classify_failure
+from logtide_sdk._version import SDK_NAME, VERSION
 from logtide_sdk.circuit_breaker import CircuitBreaker
-from logtide_sdk.client import _process_value, serialize_exception
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import CircuitBreakerOpenError
 from logtide_sdk.json_encoder import logtide_json_dumps
-from logtide_sdk._retry import classify_failure
-from logtide_sdk._version import SDK_NAME, VERSION
-from logtide_sdk.scope import get_current_scope
-from logtide_sdk.tracecontext import active_trace_context, generate_trace_id
 from logtide_sdk.models import (
     AggregatedStatsOptions,
     AggregatedStatsResponse,
     ClientMetrics,
     ClientOptions,
     LogEntry,
     LogsResponse,
-    PayloadLimitsOptions,
     QueryOptions,
 )
 
 
-class AsyncLogTideClient:
+class AsyncLogTideClient(BaseClient):
     """
     Async LogTide SDK Client.
 
@@ -65,9 +62,9 @@ def __init__(self, options: ClientOptions) -> None:
         Args:
             options: Client configuration options (same as LogTideClient)
         """
-        self.options = options
+        super().__init__(options=options)
+
         self._buffer: list[LogEntry] = []
-        self._trace_id: str | None = None
         self._buffer_lock: asyncio.Lock | None = None  # created lazily in first async call
         self._metrics_lock = ThreadingLock()
         self._metrics = ClientMetrics()
@@ -76,7 +73,6 @@ def __init__(self, options: ClientOptions) -> None:
             reset_timeout_ms=options.circuit_breaker_reset_ms,
         )
         self._latency_window: list[float] = []
-        self._payload_limits = options.payload_limits or PayloadLimitsOptions()
         self._session: aiohttp.ClientSession | None = None
         self._flush_task: Any | None = None  # asyncio.Task[None]
         self._closed = False
@@ -130,18 +126,6 @@ async def close(self) -> None:
         if self.options.debug:
             print("[LogTide] Async client closed")
 
-    # -----------------------------------------------------------------------
-    # Trace ID helpers
-    # -----------------------------------------------------------------------
-
-    def set_trace_id(self, trace_id: str | None) -> None:
-        """Set trace ID for subsequent logs."""
-        self._trace_id = trace_id
-
-    def get_trace_id(self) -> str | None:
-        """Return the current trace ID."""
-        return self._trace_id
-
     # -----------------------------------------------------------------------
     # Logging methods
     # -----------------------------------------------------------------------
@@ -153,31 +137,10 @@ async def log(self, entry: LogEntry) -> None:
         Args:
             entry: Pre-built log entry
         """
-        if self._closed:
+        if self._is_logging_disabled():
             return
 
-        if entry.metadata is None:
-            entry.metadata = {}
-
-        # Active-span trace context (resolution order per spec 005 §4:
-        # explicit -> active span -> scope -> client context/generation).
-        if entry.trace_id is None:
-            active_trace, active_span = active_trace_context()
-            if active_trace is not None:
-                entry.trace_id = active_trace
-                if entry.span_id is None:
-                    entry.span_id = active_span
-
-        # Merge the current scope (tags, user, breadcrumbs, session, trace ctx).
-        # Runs before trace-id injection so the scope's trace context wins
-        # over auto-generation.
-        get_current_scope().apply_to_entry(entry)
-
-        if entry.trace_id is None:
-            if self.options.auto_trace_id:
-                entry.trace_id = generate_trace_id()
-            elif self._trace_id is not None:
-                entry.trace_id = self._trace_id
+        self._pin_trace_id_to_entry(entry)
 
         if self.options.global_metadata:
             entry.metadata = {**self.options.global_metadata, **entry.metadata}
@@ -507,12 +470,6 @@ def _get_session(self) -> aiohttp.ClientSession:
             self._session = aiohttp.ClientSession()
         return self._session
 
-    def _get_headers(self) -> dict[str, str]:
-        return {
-            "X-API-Key": self.options.api_key,
-            "Content-Type": "application/json",
-        }
-
     async def _flush_loop(self) -> None:
         """Background coroutine: flush on a fixed interval until closed."""
         interval = self.options.flush_interval / 1000.0
@@ -602,29 +559,7 @@ async def _send_logs(self, logs: list[LogEntry]) -> None:
         ) as response:
             response.raise_for_status()
 
-    def _process_metadata_or_error(
-        self, metadata_or_error: dict[str, Any] | Exception | None
-    ) -> dict[str, Any]:
-        if metadata_or_error is None:
-            return {}
-        if isinstance(metadata_or_error, dict):
-            return metadata_or_error
-        return {"exception": serialize_exception(metadata_or_error)}
-
-    # NOTE: this is twice. (both in async and regular clients, maybe need base class)
-    def _apply_payload_limits(self, entry: LogEntry) -> None:
-        """Enforce payload limits on entry.metadata in-place."""
-        if not entry.metadata:
-            return
-        lim = self._payload_limits
-        entry.metadata = _process_value(entry.metadata, "root", lim)
-
-        raw = logtide_json_dumps(entry)
-        if len(raw.encode()) > lim.max_log_size:
-            if self.options.debug:
-                print(f"[LogTide] Log entry too large ({len(raw)} bytes), truncating metadata")
-            entry.metadata = {"_truncated": True, "_original_size": len(raw.encode())}
-
+    # TODO: refactor update latency code repeat
     def _update_latency(self, latency: float) -> None:
         with self._metrics_lock:
             self._latency_window.append(latency)