add before_send hook and sampling

Author: Polliog

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.6] - 2026-06-11
+
+### Added
+
+- `ClientOptions.before_send`: hook called before buffering — mutate the entry or return `None` to drop it. A raising hook never loses the entry
+- `ClientOptions.sample_rate` (0.0–1.0, default 1.0): per-entry sampling applied after `before_send`
+
 ## [0.9.5] - 2026-06-11
 
 ### Changed

logtide_sdk/_version.py

@@ -4,5 +4,5 @@
 import it without circular imports. Bump together with ``pyproject.toml``.
 """
 
-VERSION = "0.9.5"
+VERSION = "0.9.6"
 SDK_NAME = "logtide-python"

logtide_sdk/async_client.py

@@ -3,6 +3,7 @@
 import asyncio
 import dataclasses
 import json
+import random
 import time
 from collections.abc import Callable
 from threading import Lock as ThreadingLock
@@ -176,6 +177,23 @@ async def log(self, entry: LogEntry) -> None:
         if "sdk" not in entry.metadata:
             entry.metadata["sdk"] = {"name": SDK_NAME, "version": VERSION}
 
+        # before_send hook: may mutate or drop the entry. A buggy hook must
+        # never lose the entry or raise to the caller.
+        if self.options.before_send is not None:
+            try:
+                result = self.options.before_send(entry)
+            except Exception as hook_error:
+                if self.options.debug:
+                    print(f"[LogTide] before_send raised, keeping entry: {hook_error}")
+            else:
+                if result is None:
+                    return
+                entry = result
+
+        # Sampling (applied after before_send, spec 005 §5)
+        if self.options.sample_rate < 1.0 and random.random() > self.options.sample_rate:
+            return
+
         self._apply_payload_limits(entry)
 
         should_flush = False

logtide_sdk/client.py

@@ -3,6 +3,7 @@
 import atexit
 import dataclasses
 import json
+import random
 import re
 import time
 import traceback
@@ -271,6 +272,23 @@ def log(self, entry: LogEntry) -> None:
         if "sdk" not in entry.metadata:
             entry.metadata["sdk"] = {"name": SDK_NAME, "version": VERSION}
 
+        # before_send hook: may mutate or drop the entry. A buggy hook must
+        # never lose the entry or raise to the caller.
+        if self.options.before_send is not None:
+            try:
+                result = self.options.before_send(entry)
+            except Exception as hook_error:
+                if self.options.debug:
+                    print(f"[LogTide] before_send raised, keeping entry: {hook_error}")
+            else:
+                if result is None:
+                    return
+                entry = result
+
+        # Sampling (applied after before_send, spec 005 §5)
+        if self.options.sample_rate < 1.0 and random.random() > self.options.sample_rate:
+            return
+
         # Apply payload limits before buffering
         self._apply_payload_limits(entry)
 

logtide_sdk/models.py

@@ -1,5 +1,6 @@
 """Data models for LogTide SDK."""
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any
@@ -79,8 +80,12 @@ class ClientOptions:
     payload_limits: PayloadLimitsOptions | None = None
     dsn: str | None = None
     service: str | None = None
+    before_send: Callable[["LogEntry"], "LogEntry | None"] | None = None
+    sample_rate: float = 1.0
 
     def __post_init__(self) -> None:
+        if not 0.0 <= self.sample_rate <= 1.0:
+            raise ValueError("sample_rate must be between 0.0 and 1.0")
         if self.dsn:
             parts = parse_dsn(self.dsn)
             if not self.api_url:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logtide-sdk"
-version = "0.9.5"
+version = "0.9.6"
 description = "Official Python SDK for LogTide - Self-hosted log management with async client, logging integration, batching, retry, circuit breaker, and middleware"
 readme = "README.md"
 license = { text = "MIT" }

tests/test_hooks.py

@@ -0,0 +1,93 @@
+"""before_send hook and sampling (conformance C22/C23)."""
+
+import pytest
+
+from logtide_sdk import ClientOptions, LogTideClient
+
+
+def make_client(**kwargs):
+    return LogTideClient(
+        ClientOptions(api_url="http://localhost:8080", api_key="lp_k", service="svc", **kwargs)
+    )
+
+
+def test_before_send_can_mutate(mocker):
+    def scrub(entry):
+        entry.metadata["password"] = "[redacted]"
+        return entry
+
+    client = make_client(before_send=scrub)
+    try:
+        client.info("login", {"password": "hunter2"})
+        assert client._buffer[-1].metadata["password"] == "[redacted]"
+    finally:
+        client._closed = True
+
+
+def test_before_send_can_drop():
+    client = make_client(before_send=lambda entry: None)
+    try:
+        client.info("dropped")
+        assert len(client._buffer) == 0
+        assert client.get_metrics().logs_sent == 0
+    finally:
+        client._closed = True
+
+
+def test_before_send_exception_does_not_break_capture():
+    def broken(entry):
+        raise RuntimeError("hook bug")
+
+    client = make_client(before_send=broken)
+    try:
+        client.info("survives")
+        # a buggy hook must not lose the entry or raise to the caller
+        assert len(client._buffer) == 1
+    finally:
+        client._closed = True
+
+
+def test_sample_rate_zero_sends_nothing():
+    client = make_client(sample_rate=0.0)
+    try:
+        for _ in range(20):
+            client.info("nope")
+        assert len(client._buffer) == 0
+    finally:
+        client._closed = True
+
+
+def test_sample_rate_one_sends_everything():
+    client = make_client(sample_rate=1.0)
+    try:
+        for _ in range(5):
+            client.info("yes")
+        assert len(client._buffer) == 5
+    finally:
+        client._closed = True
+
+
+def test_sample_rate_validation():
+    with pytest.raises(ValueError):
+        ClientOptions(api_url="x://h", api_key="k", sample_rate=1.5)
+    with pytest.raises(ValueError):
+        ClientOptions(api_url="x://h", api_key="k", sample_rate=-0.1)
+
+
+@pytest.mark.asyncio
+async def test_async_before_send_and_sampling():
+    from logtide_sdk.async_client import AsyncLogTideClient
+
+    client = AsyncLogTideClient(
+        ClientOptions(
+            api_url="http://localhost:8080",
+            api_key="lp_k",
+            service="svc",
+            before_send=lambda e: None,
+        )
+    )
+    try:
+        await client.info("dropped")
+        assert len(client._buffer) == 0
+    finally:
+        client._closed = True