Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .sampo/changesets/module-capture-settings.md
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 30 additions & 0 deletions posthog/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
40 changes: 40 additions & 0 deletions posthog/test/test_module.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions references/public_api_snapshot.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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]]]
Expand Down