vybekiit 0.7.26 → 0.7.28

package/dist/global-skills/instrument-product-analytics/references/posthog-python.md

@@ -2,7 +2,7 @@
 
 # PostHog Python SDK
 
-**SDK Version:** 7.39.2
+**SDK Version:** 7.60.0
 
 Integrate PostHog into any python application.
 
@@ -13,6 +13,7 @@ Integrate PostHog into any python application.
 - Capture
 - Error Tracking
 - Feature flags
+- Tracing
 - Contexts
 - Events
 - Client management
@@ -41,7 +42,7 @@ Initialize a new PostHog client instance.
 - **`flush_interval`** (`float`) - Maximum seconds a background consumer waits before         flushing a partial batch.
 - **`gzip`** (`bool`) - Whether to gzip event upload payloads.
 - **`max_retries`** (`int`) - Number of upload retries. Values below 0 are treated as 0.
-- **`sync_mode`** (`bool`) - If True, send each event synchronously instead of using         background worker threads.
+- **`sync_mode`** (`bool`) - If True, send each event synchronously instead of using         background worker threads. This blocks the calling thread; in         asyncio applications such as FastAPI, use ``AsyncPosthog``         instead.
 - **`timeout`** (`int`) - HTTP request timeout in seconds for event uploads.
 - **`thread`** (`int`) - Number of background consumer threads.
 - **`poll_interval`** (`int`) - Seconds between local feature flag definition refreshes.
@@ -76,8 +77,10 @@ Initialize a new PostHog client instance.
 - **`secret_key`** (`any`) - A Personal API Key or Project Secret API Key, used to         authenticate local feature flag evaluation, remote config         payloads, and decrypted flag payloads. Example::              posthog.Client(project_api_key, secret_key="phx_...")
 - **`metrics?`** (`dict`)
 - **`enable_full_ai_capture`** (`bool`) - Route PostHog AI wrapper events through         the dedicated AI capture endpoint and capture full AI content:         skips string truncation and passes media (base64/data URIs)         through unredacted. ``privacy_mode`` always wins. Defaults to         False.
+- **`capture_trace_context`** (`bool`) - When OpenTelemetry is installed and a valid span is         active at capture time, add its trace and span IDs as ``$trace_id`` and         ``$span_id`` properties to events captured with ``capture()`` and         ``capture_ai()``, so they can be correlated with backend traces. Explicit         ``$trace_id``/``$span_id`` values passed in ``properties`` win. Exception         events (``capture_exception``) always attach these IDs regardless of this         setting. Defaults to False.
 - **`_use_ai_lane`** (`bool`)
 - **`_enable_multimodal_capture`** (`bool`)
+- **`traces?`** (`dict`) - Config dict for distributed tracing: ``service_name``,         ``service_version``, ``environment``, ``resource_attributes``,         ``flush_interval`` (5 s), ``max_queue_size`` (2048),         ``max_export_batch_size`` (512), ``max_live_spans`` (10000),         ``max_span_age`` (3600 s), ``max_attributes_per_span`` (128),         ``max_events_per_span`` (128), ``max_attribute_value_length``         (8192). ``before_span_send`` is a callable, or a         list run in order, that receives each finished span as a dict         (``trace_id``, ``span_id`` and ``parent_span_id`` are read-only)         and returns it, edited, or ``None`` to drop it; a hook that         raises drops the span. Tracing is off until this is provided.         Spans export on a background timer even with ``sync_mode``;         serverless handlers should call ``flush()`` before returning.         Defaults to None.
 
 ### Returns
 
@@ -320,7 +323,7 @@ Evaluate all feature flags for a user in a single call and return a :class:`Feat
 - **`group_properties?`** (`dict[str, dict[str, Any]]`) - Group properties keyed by group type.
 - **`only_evaluate_locally`** (`bool`) - If True, never fall back to remote evaluation —         flags that can't be evaluated locally are simply omitted from the snapshot.
 - **`disable_geoip?`** (`bool`) - Whether to disable GeoIP lookup.
-- **`flag_keys?`** (`list[str]`) - Optional list of flag keys to scope the underlying ``/flags``         request to a subset.
+- **`flag_keys?`** (`list[str]`) - Optional list that scopes local evaluation, the underlying         ``/flags`` request, and the returned snapshot. When omitted or ``None``, all         flags are evaluated. An empty list returns an empty snapshot without evaluating         flags. A requested key absent from loaded local definitions is included in one         remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is         True. If the server also does not know the key, it is omitted from the snapshot.
 - **`device_id?`** (`str`) - Optional device ID override. If not provided, falls back to the         context device_id (which may be set via tracing headers). Used by         experience-continuity flags to match users across distinct_id changes.
 
 ### Returns
@@ -479,6 +482,58 @@ if enabled_variant == 'variant-key': # replace 'variant-key' with the key of you
 
 ---
 
+#### get_feature_flag_evaluation_runtime()
+
+**Release Tag:** public
+
+Return where a locally loaded feature flag is meant to be evaluated.
+
+### Parameters
+
+- **`key?`** (`str`) - The feature flag key.
+
+### Returns
+
+- `Optional[FeatureFlagEvaluationRuntime]`
+
+### Examples
+
+```python
+from posthog import FeatureFlagEvaluationRuntime
+
+runtime = posthog.get_feature_flag_evaluation_runtime("my-flag")
+if runtime is FeatureFlagEvaluationRuntime.SERVER:
+    ...
+```
+
+---
+
+#### get_feature_flag_keys_by_evaluation_runtime()
+
+**Release Tag:** public
+
+Return the keys of locally loaded flags that a runtime can evaluate.  A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.
+
+### Parameters
+
+- **`evaluation_runtime?`** (`FeatureFlagEvaluationRuntime`) - The runtime to match, as a         ``FeatureFlagEvaluationRuntime`` or its string value.
+
+### Returns
+
+- `list[str]`
+
+### Examples
+
+```python
+from posthog import FeatureFlagEvaluationRuntime
+
+client_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(
+    FeatureFlagEvaluationRuntime.CLIENT
+)
+```
+
+---
+
 #### get_feature_flag_payload()
 
 **Release Tag:** public
@@ -547,7 +602,7 @@ result = posthog.get_feature_flags_and_payloads('<distinct_id>')
 
 **Release Tag:** public
 
-Get feature flag payloads for a user.
+Get feature flag payloads for a user, preserving valid serialized JSON.
 
 ### Parameters
 
@@ -561,7 +616,7 @@ Get feature flag payloads for a user.
 
 ### Returns
 
-- `dict[str, str]`
+- `dict[str, Optional[str]]`
 
 ### Examples
 
@@ -665,7 +720,7 @@ Force a flush from the internal queue to the server. Do not use directly, call `
 
 ### Parameters
 
-- **`timeout_seconds?`** (`float`) - Maximum seconds to wait for the queue to flush.         Defaults to 10 seconds. Pass ``None`` to wait indefinitely.
+- **`timeout_seconds?`** (`float`) - Maximum seconds to wait for the queue to flush.         Defaults to 10 seconds. Pass ``None`` to wait indefinitely.         Queued spans are sent at the same time, within the same
 
 ### Returns
 
@@ -736,7 +791,7 @@ posthog.join()
 
 **Release Tag:** public
 
-Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.  Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.
+Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.  Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.
 
 ### Returns
 
@@ -750,6 +805,61 @@ posthog.shutdown()
 
 ---
 
+### Tracing methods
+
+#### get_active_span()
+
+**Release Tag:** public
+
+The span that is active in the current context, or ``None``. Alpha.  Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.
+
+### Returns
+
+- `Optional[Span]`
+
+### Examples
+
+```python
+span = posthog.get_active_span()
+if span is not None:
+    headers["traceparent"] = span.traceparent()
+```
+
+---
+
+#### start_span()
+
+**Release Tag:** public
+
+Start a span for distributed tracing. Alpha.  Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.
+
+### Parameters
+
+- **`name?`** (`str`) - A low-cardinality operation name, e.g. ``GET /users/:id``.         Variable values belong in attributes, not the name.
+- **`kind?`** (`str`) - ``internal`` (default), ``server``, ``client``, ``producer``         or ``consumer``.
+- **`attributes?`** (`Mapping[str, Any]`) - Initial attributes.
+- **`parent`** (`Span`) - A span handle, or an inbound W3C ``traceparent`` header         value to continue a remote trace. Defaults to the active span.         A forked child starts with no active span; pass the parent         span to continue a trace across a fork.
+- **`tracestate?`** (`str`) - The inbound ``tracestate`` header accompanying a         ``traceparent`` string ``parent``; preserved and propagated.
+- **`start_time`** (`datetime`) - A ``datetime`` or epoch seconds, to backdate the span.
+
+### Returns
+
+- `Span`
+
+### Examples
+
+```python
+posthog = Posthog("<ph_project_api_key>", traces={"service_name": "checkout-api"})
+
+with posthog.start_span("POST /checkout", parent=request.headers.get("traceparent")) as span:
+    span.set_attribute("plan", user.plan)
+    with posthog.start_span("db.query", kind="client"):
+        ...
+    outgoing_headers = {"traceparent": span.traceparent()}
+```
+
+---
+
 ### Contexts methods
 
 #### get_tags()
@@ -1166,9 +1276,9 @@ Evaluate all feature flags for a user in a single call and return a :class:`Feat
 - **`groups?`** (`Mapping[str, Union[str, int]]`) - Mapping of group type to group key.
 - **`person_properties?`** (`dict[str, Any]`) - Person properties to use for evaluation.
 - **`group_properties?`** (`dict[str, dict[str, Any]]`) - Group properties keyed by group type.
-- **`only_evaluate_locally`** (`bool`) - If ``True``, never fall back to remote evaluation.
+- **`only_evaluate_locally`** (`bool`) - If ``True``, never fall back to remote evaluation and         omit flags that cannot be evaluated locally.
 - **`disable_geoip?`** (`bool`) - Whether to disable GeoIP lookup.
-- **`flag_keys?`** (`list[str]`) - Optional list of flag keys. When provided, only these flags are         evaluated — the underlying ``/flags`` request asks the server for just         this subset, which makes the response smaller and the request cheaper.         Use this when you only need a handful of flags out of many.
+- **`flag_keys?`** (`list[str]`) - Optional list that scopes local evaluation, the underlying ``/flags``         request, and the returned snapshot. When omitted or ``None``, all flags are evaluated.         An empty list returns an empty snapshot without evaluating flags. A requested key         absent from loaded local definitions is included in one remote fallback per         ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server         also does not know the key, it is omitted from the snapshot.
 - **`device_id?`** (`str`) - Optional device ID override. If not provided, falls back to the         context device_id (which may be set via tracing headers). Used by         experience-continuity flags to match users across distinct_id changes.
 
 ### Returns
@@ -1344,6 +1454,60 @@ if enabled_variant == 'variant-key':
 
 ---
 
+#### get_feature_flag_evaluation_runtime()
+
+**Release Tag:** public
+
+Return where a locally loaded feature flag is meant to be evaluated.
+
+**Notes:**
+
+Reads the `evaluation_runtime` each flag definition carries, so no extra     request is made. Returns `None` when local evaluation has not loaded a     definition for this key. A definition that carries no runtime reports     `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.
+
+### Parameters
+
+- **`key?`** (`str`)
+
+### Returns
+
+- `Optional[FeatureFlagEvaluationRuntime]`
+
+### Examples
+
+```python
+from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime
+runtime = get_feature_flag_evaluation_runtime("my-flag")
+```
+
+---
+
+#### get_feature_flag_keys_by_evaluation_runtime()
+
+**Release Tag:** public
+
+Return the keys of locally loaded flags that a runtime can evaluate.
+
+**Notes:**
+
+A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so     it is returned for `CLIENT` and for `SERVER`. Use this to decide which     flags to hand to a browser when a backend serves flags to its own     frontend.
+
+### Parameters
+
+- **`evaluation_runtime?`** (`FeatureFlagEvaluationRuntime`)
+
+### Returns
+
+- `list[str]`
+
+### Examples
+
+```python
+from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime
+client_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)
+```
+
+---
+
 #### get_feature_flag_payload()
 
 **Release Tag:** public
@@ -1451,6 +1615,62 @@ shutdown()
 
 ---
 
+### Tracing methods
+
+#### get_active_span()
+
+**Release Tag:** public
+
+The span that is active in the current context, or ``None``. Alpha.  Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.
+
+### Returns
+
+- `Optional[Span]`
+
+### Examples
+
+```python
+span = posthog.get_active_span()
+if span is not None:
+    headers["traceparent"] = span.traceparent()
+```
+
+---
+
+#### start_span()
+
+**Release Tag:** public
+
+Start a span for distributed tracing. Alpha.  Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.
+
+### Parameters
+
+- **`name?`** (`str`) - A low-cardinality operation name, e.g. ``GET /users/:id``.         Variable values belong in attributes, not the name.
+- **`kind?`** (`str`) - ``internal`` (default), ``server``, ``client``, ``producer`` or         ``consumer``.
+- **`attributes?`** (`Mapping[str, Any]`) - Initial attributes.
+- **`parent`** (`Span`) - A span handle, or an inbound W3C ``traceparent`` header value         to continue a remote trace. Defaults to the active span.
+- **`tracestate?`** (`str`) - The inbound ``tracestate`` header accompanying a         ``traceparent`` string ``parent``; preserved and propagated.
+- **`start_time`** (`datetime`) - A ``datetime`` or epoch seconds, to backdate the span.
+
+### Returns
+
+- `Span`
+
+### Examples
+
+```python
+import posthog
+posthog.traces = {"service_name": "checkout-api"}
+
+with posthog.start_span("POST /checkout", parent=request.headers.get("traceparent")) as span:
+    span.set_attribute("plan", user.plan)
+    with posthog.start_span("db.query", kind="client"):
+        ...
+    outgoing_headers = {"traceparent": span.traceparent()}
+```
+
+---
+
 ### Other methods
 
 #### get_feature_flag_result()