diff --git a/.sampo/changesets/module-capture-settings.md b/.sampo/changesets/module-capture-settings.md new file mode 100644 index 000000000..b9d9c83ac --- /dev/null +++ b/.sampo/changesets/module-capture-settings.md @@ -0,0 +1,5 @@ +--- +posthog: minor +--- + +Add module-level `max_queue_size`, `max_retries`, `timeout`, `capture_ai_max_queue_size` and `capture_ai_timeout` settings, so the global client can size and tune its analytics and AI capture lanes like an explicit `Posthog` client. diff --git a/posthog/__init__.py b/posthog/__init__.py index eafc2a3ac..7d2493321 100644 --- a/posthog/__init__.py +++ b/posthog/__init__.py @@ -466,6 +466,17 @@ def get_context_options() -> Dict[str, Any]: each exception type's bucket. exception_autocapture_refill_interval_seconds: Seconds between token refills for autocaptured exception rate limiting. + max_queue_size: Maximum number of analytics events buffered before upload. + ``None`` keeps the client default. AI events use + ``capture_ai_max_queue_size``. + max_retries: Number of upload retries on both capture lanes. ``None`` keeps + the client default. + timeout: Seconds allowed for one analytics upload request. ``None`` keeps the + client default. AI uploads use ``capture_ai_timeout``. + capture_ai_max_queue_size: Maximum number of AI events buffered before upload. + ``None`` keeps the client default. + capture_ai_timeout: Seconds allowed for one AI upload request. ``None`` keeps + the client default. """ # Deprecated legacy alias for project_api_key. Kept for backwards compatibility. api_key = None # type: Optional[str] @@ -502,6 +513,13 @@ def get_context_options() -> Dict[str, Any]: # Captures full AI content in AI SDK wrapper events: skips truncation and # passes media unredacted. `privacy_mode` always wins. enable_full_ai_capture = False # type: bool +# Queue, retry and timeout settings for the global client's two capture lanes. +# `None` keeps the client's own default. +max_queue_size = None # type: Optional[int] +max_retries = None # type: Optional[int] +timeout = None # type: Optional[float] +capture_ai_max_queue_size = None # type: Optional[int] +capture_ai_timeout = None # type: Optional[float] # Deprecated aliases for `enable_full_ai_capture`. _use_ai_lane = False # type: bool _enable_multimodal_capture = False # type: bool @@ -1512,8 +1530,20 @@ def setup() -> Client: global default_client if not default_client: configured_api_key = (project_api_key or "").strip() or (api_key or "").strip() + capture_settings: Dict[str, Any] = { + "max_queue_size": max_queue_size, + "max_retries": max_retries, + "timeout": timeout, + "capture_ai_max_queue_size": capture_ai_max_queue_size, + "capture_ai_timeout": capture_ai_timeout, + } default_client = Client( configured_api_key, + **{ + name: value + for name, value in capture_settings.items() + if value is not None + }, host=host, debug=debug, on_error=on_error, diff --git a/posthog/test/test_module.py b/posthog/test/test_module.py index e9d634dc3..7495ecbda 100644 --- a/posthog/test/test_module.py +++ b/posthog/test/test_module.py @@ -68,8 +68,27 @@ def test_module_capture_exception_forwards_level(self): ) +CAPTURE_SETTINGS = ( + "max_queue_size", + "max_retries", + "timeout", + "capture_ai_max_queue_size", + "capture_ai_timeout", +) + + +def lane_settings(client): + return { + lane.name: (lane.queue.maxsize, lane.timeout, lane.max_retries) + for lane in (client._analytics_lane, client._ai_lane) + } + + class TestModuleLevelSetup(unittest.TestCase): def setUp(self): + for setting in CAPTURE_SETTINGS: + self.addCleanup(setattr, posthog, setting, getattr(posthog, setting)) + setattr(posthog, setting, None) self._original_default_client = posthog.default_client self._original_api_key = posthog.api_key self._original_project_api_key = posthog.project_api_key @@ -171,6 +190,27 @@ def test_setup_propagates_config(self, setting, value): self.assertEqual(getattr(client, setting), value) + def test_setup_sizes_each_capture_lane_from_the_module_settings(self): + posthog.api_key = "phc_test" + posthog.max_queue_size = 7 + posthog.max_retries = 0 + posthog.timeout = 4 + posthog.capture_ai_max_queue_size = 3 + posthog.capture_ai_timeout = 9 + + client = posthog.setup() + + analytics, ai = lane_settings(client).values() + self.assertEqual(analytics, (7, 4, 0)) + self.assertEqual(ai, (3, 9, 0)) + + def test_setup_keeps_the_client_defaults_for_unset_capture_settings(self): + posthog.api_key = "phc_test" + explicit = Posthog("phc_test", send=False) + self.addCleanup(explicit.shutdown) + + self.assertEqual(lane_settings(posthog.setup()), lane_settings(explicit)) + def test_setup_propagates_and_updates_privacy_mode(self): posthog.api_key = "phc_test" posthog.privacy_mode = True diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index c9e0b430e..63bf803be 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -789,6 +789,8 @@ attribute posthog.before_send = None attribute posthog.bucketed_rate_limiter.Number = Union[int, float] attribute posthog.bucketed_rate_limiter.ONE_DAY_IN_SECONDS = 86400.0 attribute posthog.bucketed_rate_limiter.log = logging.getLogger('posthog') +attribute posthog.capture_ai_max_queue_size = None +attribute posthog.capture_ai_timeout = None attribute posthog.capture_compression.CAPTURE_COMPRESSION_ENV_VAR = 'POSTHOG_CAPTURE_COMPRESSION' attribute posthog.capture_compression.CaptureCompression.DEFLATE = 'deflate' attribute posthog.capture_compression.CaptureCompression.GZIP = 'gzip' @@ -1043,6 +1045,8 @@ attribute posthog.integrations.flask.PosthogFlaskIntegration.request_filter = re attribute posthog.integrations.flask.PosthogFlaskIntegration.trust_tracing_headers: bool attribute posthog.is_server = True attribute posthog.log_captured_exceptions = False +attribute posthog.max_queue_size = None +attribute posthog.max_retries = None attribute posthog.mcp.asgi.PostHogMcpStatelessSessionMiddleware.app = app attribute posthog.mcp.constants.POSTHOG_MCP_ANALYTICS_SOURCE = 'posthog_mcp_analytics' attribute posthog.mcp.constants.PostHogMCPAnalyticsEvent.CUSTOM = '$mcp_custom' @@ -1203,6 +1207,7 @@ attribute posthog.send = True attribute posthog.super_options = None attribute posthog.super_properties = None attribute posthog.sync_mode = False +attribute posthog.timeout = None attribute posthog.traces = None attribute posthog.types.BeforeSendCallback = Callable[[dict[str, Any]], Optional[dict[str, Any]]] attribute posthog.types.BeforeSpanSendCallback = Callable[[dict[str, Any]], Optional[dict[str, Any]]]