Registry / communication / rudder-sdk-python

rudder-sdk-python

JSON →
library2.1.4pypypi✓ verified 89d ago

RudderStack's Python SDK (`rudder-sdk-python`) is an open-source client for tracking and sending server-side customer event data from Python applications. It acts as an open-source Segment alternative, enabling developers to collect and route event data to various downstream destinations. The library is currently at version 2.1.4 and is actively maintained with regular updates.

pip install rudder-sdk-python
INSTALL
IMPORT
SIG · RUDDER-SDK-PYTHON
R
rudder-sdk-python
communicationpythonv2.1.4
Install
2.7s avg
Import
823ms
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.1.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.870s · 23.4MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 2.7s · import 0.776s · 24MB
22MB installed
● package 22MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rudderstack.analytics
✓ import rudderstack.analytics as rudder_analytics
✗ import rudderstack.analytics
Aliasing as 'rudder_analytics' (or 'analytics') is a common convention in examples and helps distinguish it from other modules.

Initialize the RudderStack Python SDK with your source write key and data plane URL, then use `identify`, `track`, and `page` methods to send customer events. Remember to call `flush()` to ensure all buffered events are sent before your application exits.

import os import rudderstack.analytics as rudder_analytics # Set your RudderStack Write Key and Data Plane URL from environment variables # Replace with your actual values or use environment variables for production WRITE_KEY = os.environ.get('RUDDERSTACK_WRITE_KEY', 'YOUR_WRITE_KEY') DATA_PLANE_URL = os.environ.get('RUDDERSTACK_DATA_PLANE_URL', 'YOUR_DATA_PLANE_URL') rudder_analytics.write_key = WRITE_KEY rudder_analytics.dataPlaneUrl = DATA_PLANE_URL # Optional: Configure debug mode for verbose logging rudder_analytics.debug = True # Identify a user rudder_analytics.identify( user_id='user_123', traits={'name': 'John Doe', 'email': 'john.doe@example.com'} ) # Track an event rudder_analytics.track( user_id='user_123', event='Product Viewed', properties={'product_id': '456', 'product_name': 'Example Widget'} ) # You can also use anonymous_id if user_id is not available rudder_analytics.page( anonymous_id='anon_789', name='Homepage', category='Marketing' ) # Ensure all queued events are sent before exiting rudder_analytics.flush() print('Events sent to RudderStack.')
Debug
Known issues
gotchaThe Python SDK does not persist user state. You must explicitly provide either `user_id` or `anonymous_id` with every event API call (e.g., `track`, `identify`, `page`). Failing to do so will result in events not being processed correctly or being dropped.
fix
Always pass `user_id` or `anonymous_id` as an argument to event methods: `rudder_analytics.track('user_id_123', 'Event Name')`.
affects: All versions
gotchaThe SDK blocks the calling thread until all messages are flushed from the queue. Avoid using SDK calls directly within the critical path of a request lifecycle (e.g., in web server request handlers) to prevent performance bottlenecks.
fix
Consider using asynchronous processing (e.g., a background thread, a message queue, or a dedicated worker) for RudderStack event calls in performance-sensitive applications.
affects: All versions
gotchaThe Python SDK drops any event data larger than 32KB without logging a warning. Ensure your event payloads (including properties and context) do not exceed this size limit.
fix
Monitor event sizes and truncate or restructure large event payloads to stay within the 32KB limit. Split large events into multiple smaller events if necessary.
affects: All versions
Errors
Common errors & fixes
SDK returns success, but events are not visible in the destination.
Several potential causes: RudderStack server is in 'degraded' or 'maintenance' mode, incorrect data plane URL or write key, Control Plane is inaccessible, or the specific destination is not enabled or misconfigured in the RudderStack dashboard.
fix
1. Verify your `rudder_analytics.write_key` and `rudder_analytics.dataPlaneUrl` are correct. 2. Check the status of your RudderStack server/data plane (if self-hosted) or the RudderStack cloud dashboard. 3. Confirm the destination is enabled and configured correctly in your RudderStack workspace. 4. Enable `rudder_analytics.debug = True` for more verbose logging.
HTTPSConnectionPool(...): Max retries exceeded with url: ... (Caused by ProxyError or ConnectionError)
Network connectivity issues preventing the SDK from reaching the RudderStack data plane, potentially due to firewall rules, proxy misconfiguration, or an unavailable data plane server. While this specific error often appears with `rudder-cli`, similar underlying network problems can affect the SDK.
fix
1. Check your network connection and proxy settings. 2. Ensure the `DATA_PLANE_URL` is accessible from your application's environment. 3. Verify that any firewalls are configured to allow outbound HTTP/HTTPS connections to your data plane URL. 4. Increase the `timeout` configuration option for the SDK if transient network issues are expected.
Events are being sent successfully but appear in the destination with significant delay.
This usually indicates a bottleneck in processing, either on the RudderStack backend side or the destination service itself. Possible reasons include a high rate of incoming events overwhelming the system or a temporary outage/degradation of the destination service.
fix
1. Check the status of your destination service (e.g., Google Analytics, S3). 2. If self-hosting RudderStack, monitor your server resources and consider scaling up if the incoming event rate consistently exceeds processing capacity. 3. Review RudderStack dashboard metrics for any alerts on pending events or degraded performance.
Upgrade
Version history
2.1.4latest on PyPI · released Sep 25, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
rudder-sdk-python — pip install rudder-sdk-python · libregistry