vybekiit 0.7.26 → 0.7.27

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

@@ -1,10 +1,6 @@
 > AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
 
-# Python - Docs
-
-Copy page
-
-# Python - Docs
+# Python
 
 The Python SDK makes it easy to capture events, evaluate feature flags, track errors, and more in your Python apps.
 
@@ -14,8 +10,6 @@ The Python SDK makes it easy to capture events, evaluate feature flags, track er
 
 Terminal
 
-PostHog AI
-
 ```bash
 pip install posthog
 ```
@@ -28,10 +22,9 @@ In your app, import the `posthog` library and set your project token and host **
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import Posthog
+
 posthog = Posthog('<ph_project_token>', host='https://us.i.posthog.com')
 ```
 
@@ -39,6 +32,101 @@ posthog = Posthog('<ph_project_token>', host='https://us.i.posthog.com')
 
 You can find your project token and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog.
 
+## Use the asyncio client
+
+The Python SDK includes an asyncio-native client in version `7.45.0` and later. Continue to use `Posthog` in synchronous apps. For an asyncio app, install the optional async dependencies:
+
+Terminal
+
+```bash
+pip install "posthog[async]>=7.45.0"
+```
+
+Import `AsyncPosthog`, the customer-facing name for `AsyncClient`. Both names provide the same async context manager and lifecycle methods. Keep one client for the lifetime of your app. For example, use a FastAPI lifespan handler:
+
+Python
+
+```python
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from posthog import AsyncPosthog
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with AsyncPosthog(
+        os.environ["POSTHOG_PROJECT_TOKEN"],
+        host=os.environ["POSTHOG_HOST"],
+        secret_key=os.environ.get("POSTHOG_FEATURE_FLAGS_SECURE_API_KEY"),
+    ) as posthog:
+        app.state.posthog = posthog
+        yield
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Exiting the context calls `shutdown()`. This flushes buffered events, waits for in-flight operations, stops the workers, and closes the HTTP transport. If you don't use the context manager, call `await posthog.shutdown()` during app shutdown. `await posthog.join()` has the same effect.
+
+### Capture events without blocking the event loop
+
+`capture()` queues an event and returns without waiting for a network request. Don't await it:
+
+Python
+
+```python
+posthog.capture(
+    "event_name",
+    distinct_id="user-distinct-id",
+    properties={"source": "fastapi"},
+)
+```
+
+Use `capture_immediate()` when your code must wait for that event's delivery attempt:
+
+Python
+
+```python
+capture_id = await posthog.capture_immediate(
+    "event_name",
+    distinct_id="user-distinct-id",
+)
+```
+
+### Evaluate feature flags
+
+Await `evaluate_flags()` once, then use its snapshot with synchronous in-memory accessors. Pass the same snapshot to `capture()` to attach the exact values used for branching without another feature flag request:
+
+Python
+
+```python
+flags = await posthog.evaluate_flags("user-distinct-id")
+
+if flags.is_enabled("new-checkout"):
+    # Show the new checkout
+    pass
+
+posthog.capture(
+    "checkout started",
+    distinct_id="user-distinct-id",
+    flags=flags,
+)
+```
+
+The snapshot provides synchronous `is_enabled()`, `get_flag()`, and `get_flag_payload()` accessors. The awaited `evaluate_flags()` call also accepts `groups`, `person_properties`, `group_properties`, `disable_geoip`, `flag_keys`, and `device_id` arguments.
+
+### Fetch remote config
+
+Initialize the client with a server-side [feature flags secure API key](/docs/feature-flags/remote-config.md#step-1-find-your-feature-flags-secure-api-key) as `secret_key`, then await the remote config request:
+
+Python
+
+```python
+config = await posthog.get_remote_config_payload("landing-page-config")
+```
+
+See [Remote config](/docs/feature-flags/remote-config.md) for setup and security details.
+
 ## Identifying users
 
 > **Identifying users is required.** Backend events need a `distinct_id` to associate events with the correct user.
@@ -47,10 +135,9 @@ You can find your project token and instance address in the [project settings](h
 >
 > Python
 >
-> PostHog AI
->
 > ```python
 > from posthog import new_context, identify_context, capture
+>
 > @app.get("/foo")
 > def foo(current_user: User = Depends(get_current_user)):
 >     with new_context(): # Set context at the top of a route
@@ -67,12 +154,12 @@ You can send custom events using `capture`:
 
 Python
 
-PostHog AI
-
 ```python
 # Events captured with no context or explicit distinct_id are marked as personless and have an auto-generated distinct_id:
 posthog.capture('some-anon-event')
+
 from posthog import identify_context, new_context
+
 # Use contexts to manage user identification across multiple capture calls
 with new_context():
     identify_context('distinct_id_of_the_user')
@@ -92,8 +179,6 @@ Optionally, you can include additional information with the event by including a
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture(
     "user_signed_up",
@@ -111,20 +196,16 @@ If you're aiming for a backend-only implementation of PostHog and won't be captu
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture('$pageview', distinct_id="distinct_id_of_the_user", properties={'$current_url': 'https://example.com'})
 ```
 
 ## Person profiles and properties
 
-The Python SDK captures identified events if the current context is identified or if you pass a distinct ID explicitly. These create [person profiles](/docs/data/persons.md). To set [person properties](/docs/data/user-properties.md) in these profiles, include them when capturing an event:
+The Python SDK captures identified events if the current context is identified or if you pass a distinct ID explicitly. These create [person profiles](/docs/data/persons.md). To set [person properties](/docs/product-analytics/person-properties.md) in these profiles, include them when capturing an event:
 
 Python
 
-PostHog AI
-
 ```python
 # Passing a distinct id explicitly
 posthog.capture(
@@ -135,6 +216,7 @@ posthog.capture(
         '$set_once': {'initial_url': '/blog'}
     }
 )
+
 # Using contexts
 from posthog import new_context, identify_context
 with new_context():
@@ -142,14 +224,12 @@ with new_context():
     posthog.capture('event_name')
 ```
 
-For more details on the difference between `$set` and `$set_once`, see our [person properties docs](/docs/data/user-properties.md#what-is-the-difference-between-set-and-set_once).
+For more details on the difference between `$set` and `$set_once`, see our [person properties docs](/docs/product-analytics/person-properties.md#what-is-the-difference-between-set-and-set_once).
 
 To capture [anonymous events](/docs/data/anonymous-vs-identified-events.md) without person profiles, set the event's `$process_person_profile` property to `False`. Events captured with no context or explicit distinct\_id are marked as personless, and will have an auto-generated distinct\_id:
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture(
     event='event_name',
@@ -167,8 +247,6 @@ In this case, you can use `alias` to assign another distinct ID to the same user
 
 Python
 
-PostHog AI
-
 ```python
 posthog.alias(previous_id='distinct_id', distinct_id='alias_id')
 ```
@@ -185,18 +263,20 @@ You can enter a context using the `with` statement:
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, tag, set_context_session, identify_context
+
 with new_context():
     tag("transaction_id", "abc123")
     tag("some_arbitrary_value", {"tags": "can be dicts"})
+
     # Sessions are UUIDv7 values and used to track a sequence of events that occur within a single user session
     # See https://posthog.com/docs/data/sessions
     set_context_session(session_id)
+
     # Setting the context-level distinct ID. See below for more details.
     identify_context(user_id)
+
     # This event is captured with the distinct ID, session ID, and tags set above
     posthog.capture("order_processed")
 ```
@@ -205,13 +285,14 @@ Contexts are persisted across function calls. If you enter one and then call a f
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, tag
+
 def some_function():
     # When called from `outer_function`, this event is captured with the property some-key="value-4"
     posthog.capture("order_processed")
+
+
 def outer_function():
     with new_context():
         tag("some-key", "value-4")
@@ -222,10 +303,9 @@ Contexts are nested, so tags added to a parent context are inherited by child co
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, tag
+
 with new_context():
     tag("some-key", "value-1")
     tag("some-other-key", "another-value")
@@ -233,6 +313,7 @@ with new_context():
         tag("some-key", "value-2")
         # This event is captured with some-key="value-2" and some-other-key="another-value"
         posthog.capture("order_processed")
+
     # This event is captured with some-key="value-1" and some-other-key="another-value"
     posthog.capture("order_processed")
 ```
@@ -241,10 +322,9 @@ You can disable this nesting behavior by passing `fresh=True` to `new_context`:
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, tag
+
 with new_context(fresh=True):
     tag("some-key", "value-2")
     # This event only has the property some-key="value-2" from the fresh context
@@ -259,10 +339,9 @@ Contexts can be associated with a distinct ID by calling `posthog.identify_conte
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import identify_context
+
 identify_context("distinct-id")
 ```
 
@@ -270,10 +349,9 @@ Within a context associated with a distinct ID, all events captured are associat
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, identify_context
+
 with new_context():
     identify_context("distinct-id")
     posthog.capture("order_processed") # will be associated with distinct-id
@@ -290,8 +368,6 @@ Contexts can be associated with a session ID by calling `posthog.set_context_ses
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, set_context_session
 with new_context():
@@ -317,13 +393,13 @@ By default exceptions raised within a context are captured and available in the
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import new_context, tag
+
 with new_context(capture_exceptions=False):
     tag("transaction_id", "abc123")
     tag("some_arbitrary_value", {"tags": "can be dicts"})
+
     # This event will be captured with the tags set above
     posthog.capture("order_processed")
     # This exception will not be captured
@@ -336,10 +412,9 @@ The SDK exposes a function decorator. It takes the same `fresh` and `capture_exc
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import scoped, identify_context
+
 @scoped(fresh=True)
 def process_order(user, order_id):
     identify_context(user.distinct_id)
@@ -357,8 +432,6 @@ To capture an event and associate it with a group:
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture('some_event', groups={'company': 'company_id_in_your_db'})
 ```
@@ -367,8 +440,6 @@ To update properties on a group:
 
 Python
 
-PostHog AI
-
 ```python
 posthog.group_identify('company', 'company_id_in_your_db', {
     'name': 'Awesome Inc.',
@@ -380,6 +451,8 @@ The `name` is a special property which is used in the PostHog UI for the name of
 
 ## Feature flags
 
+The examples in this section use the synchronous `Posthog` client. For `AsyncPosthog`, use the [awaited feature flag example](#evaluate-feature-flags). The returned snapshot uses the same accessors.
+
 PostHog's [feature flags](/docs/feature-flags.md) enable you to safely deploy and roll back new features as well as target specific users and groups with them.
 
 There are two steps to implement feature flags in Python:
@@ -392,10 +465,9 @@ Call `posthog.evaluate_flags()` once for the user, then read values from the ret
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags("distinct_id_of_your_user")
+
 if flags.is_enabled("flag-key"):
     # Do something differently for this user
     # Optional: fetch the payload
@@ -406,11 +478,11 @@ if flags.is_enabled("flag-key"):
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags("distinct_id_of_your_user")
+
 enabled_variant = flags.get_flag("flag-key")
+
 if enabled_variant == "variant-key":  # replace "variant-key" with the key of your variant
     # Do something differently for this user
     # Optional: fetch the payload
@@ -435,13 +507,13 @@ Pass the same `flags` object that you used for branching. This attaches the exac
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags("distinct_id_of_your_user")
+
 if flags.is_enabled("flag-key"):
     # Do something differently for this user
     pass
+
 posthog.capture(
     "event_name",
     distinct_id="distinct_id_of_your_user",
@@ -455,8 +527,6 @@ To reduce event property bloat, pass a filtered snapshot:
 
 Python
 
-PostHog AI
-
 ```python
 # Attach only flags accessed with is_enabled() or get_flag() before this call
 posthog.capture(
@@ -464,6 +534,7 @@ posthog.capture(
     distinct_id="distinct_id_of_your_user",
     flags=flags.only_accessed(),
 )
+
 # Attach only specific flags
 posthog.capture(
     "event_name",
@@ -480,8 +551,6 @@ In the event properties, include `$feature/feature_flag_name: variant_key`:
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture(
     "event_name",
@@ -499,8 +568,6 @@ By default, `posthog.evaluate_flags()` evaluates every flag for the user. If you
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags(
     "distinct_id_of_your_user",
@@ -526,8 +593,6 @@ For example:
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags(
     "distinct_id_of_the_user",
@@ -541,6 +606,7 @@ flags = posthog.evaluate_flags(
         "another_group_type": {"group_property_name": "value"},
     },
 )
+
 if flags.is_enabled("flag-key"):
     # Do something differently for this user
 ```
@@ -578,8 +644,6 @@ You can configure the `feature_flags_request_timeout_seconds` parameter when ini
 
 Python
 
-PostHog AI
-
 ```python
 posthog = Posthog(
     "<ph_project_token>",
@@ -602,19 +666,20 @@ In multi-worker or edge environments, you can implement custom caching for flag
 
 ## Experiments (A/B tests)
 
-Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code:
+Since [experiments](/docs/experiments/start-here.md) use feature flags, the code for running an experiment is very similar to the feature flags code. This example uses the synchronous `Posthog` client:
 
 Python
 
-PostHog AI
-
 ```python
 flags = posthog.evaluate_flags("user_distinct_id")
 variant = flags.get_flag("experiment-feature-flag-key")
+
 if variant == "variant-name":
     # Do something
 ```
 
+With `AsyncPosthog`, await the evaluation: `flags = await posthog.evaluate_flags("user_distinct_id")`. The remaining snapshot access is the same.
+
 It's also possible to [run experiments without using feature flags](/docs/experiments/running-experiments-without-feature-flags.md).
 
 ## AI Observability
@@ -627,10 +692,9 @@ You can [autocapture exceptions](/docs/error-tracking/installation.md) by settin
 
 Python
 
-PostHog AI
-
 ```python
 from posthog import Posthog
+
 posthog = Posthog("<ph_project_token>", enable_exception_autocapture=True, ...)
 ```
 
@@ -638,8 +702,6 @@ You can also manually capture exceptions using the `capture_exception` method:
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture_exception(e, distinct_id='user_distinct_id', properties=additional_properties)
 ```
@@ -652,8 +714,6 @@ The Python SDK can automatically capture the state of local variables when an ex
 
 Python
 
-PostHog AI
-
 ```python
 posthog = Posthog(
     "<ph_project_token>",
@@ -664,6 +724,246 @@ posthog = Posthog(
 
 You can configure which variables are captured, masked, or ignored. See the [code variables documentation](/docs/error-tracking/code-variables/python.md) for detailed configuration options.
 
+## Distributed tracing
+
+> Requires `posthog` version 7.58.0 or later.
+
+**The span API is experimental**
+
+Tracing is new in the Python SDK and its API can still change in a minor release. Spans you send are kept – it's the SDK surface that isn't frozen yet.
+
+Tracing records **spans** – timed units of work – so you can see where time went in a request and how work fans out across your services. Spans created inside a [context](#contexts) automatically carry the person and session they belong to, so a slow trace links back to the person who experienced it.
+
+Tracing is off until you set the `traces` option. No OpenTelemetry dependency is required. For what you can do with spans once they arrive, see [Distributed tracing](/docs/distributed-tracing/start-here.md).
+
+Python
+
+```python
+from posthog import Posthog
+
+posthog = Posthog(
+    "<ph_project_token>",
+    host="https://us.i.posthog.com",
+    traces={"service_name": "checkout-api"},
+)
+```
+
+If you use the module-level API instead, set `posthog.traces = {"service_name": "checkout-api"}` alongside your other options, before you start the first span.
+
+Set `service_name` – PostHog groups operations by service and span name.
+
+Tracing is available on the synchronous `Posthog` client and the module-level API. `AsyncPosthog` doesn't support it yet.
+
+### Creating spans
+
+`start_span` returns a span. Use it in a `with` block to make it the active span for the block and end it when the block exits. Spans started inside the block nest underneath it automatically.
+
+Python
+
+```python
+with posthog.start_span("POST /checkout", kind="server") as span:
+    span.set_attribute("plan", user.plan)
+
+    with posthog.start_span("create-order"):
+        order = create_order(cart)
+    with posthog.start_span("charge-card"):
+        stripe.charge(order)
+```
+
+If an exception escapes the block, the span records it, its status is set to `error`, and the exception propagates unchanged. `KeyboardInterrupt`, `GeneratorExit`, and `asyncio.CancelledError` still end the span but aren't recorded as failures.
+
+The recorded exception includes the stack trace, which contains file paths from your server. If you'd rather those didn't leave your process, remove `exception.stacktrace` in [`before_span_send`](#scrubbing-and-dropping-spans).
+
+For work that can't wrap a block, call `start_span` without `with`. **A span started this way isn't active**, so spans started afterwards aren't its children unless you pass `parent` explicitly – and you must call `end()` yourself.
+
+Python
+
+```python
+span = posthog.start_span("background-sync", attributes={"queue": "emails"})
+try:
+    # Explicitly parent a child to a span that isn't active.
+    child = posthog.start_span("send-batch", parent=span)
+    child.end()
+finally:
+    span.end()
+```
+
+`get_active_span()` returns the span active in the current context, or `None` when there isn't one.
+
+The active span is tracked with [`contextvars`](https://docs.python.org/3/library/contextvars.html), so it carries across `await` in asyncio code. Threads don't reliably inherit it – pass `parent=span` to continue the trace in a thread you start or a `ThreadPoolExecutor` task. A forked child process starts with no active span, so pass `parent` there too.
+
+`start_span` always returns a usable span, even when tracing is off, so your code never needs to check whether tracing is enabled.
+
+### Span names and attributes
+
+Span names should be low-cardinality operation names – `GET /users/:id`, not `GET /users/123`. Variable values belong in attributes. Strings, booleans, integers, and floats keep their type. Lists and dictionaries are sent as arrays and maps, but PostHog stores them as serialized strings. Setting an attribute to `None` removes it, and any other value is converted to a string.
+
+Python
+
+```python
+with posthog.start_span("GET /users/:id", kind="server") as span:
+    span.set_attributes({"user.id": user_id, "db.rows": len(rows)})
+    span.add_event("cache-miss")
+
+    if not rows:
+        span.set_status("error", "user not found")
+```
+
+| Method | Description |
+| --- | --- |
+| `set_attribute(key, value)` | Set a single attribute |
+| `set_attributes(attributes)` | Merge several attributes at once |
+| `add_event(name, attributes=None, timestamp=None)` | Record a timestamped event within the span |
+| `set_status(code, message=None)` | Set the outcome: `"ok"` or `"error"`. `"ok"` is final – an exception raised later in the `with` block doesn't override it |
+| `record_exception(exception)` | Attach an exception event carrying the type, message, and – for a raised exception – stack trace, and set status to `error`. Use it for exceptions you catch and handle |
+| `update_name(name)` | Replace the span name, e.g. once a route template resolves |
+| `traceparent()` | This span's W3C `traceparent` header value, or `None` |
+| `tracestate()` | This span's W3C `tracestate` value, or `None` when it has none |
+| `end(end_time=None)` | End the span and queue it for export. A `with` block does this for you |
+
+Every method except `traceparent()`, `tracestate()`, and `end()` returns the span, so calls chain. Calls after `end()` are ignored.
+
+`start_span` takes these keyword arguments:
+
+| Argument | Description |
+| --- | --- |
+| `kind` | What the work is: `"internal"` (default), `"server"` for an inbound request, `"client"` for an outbound call, `"producer"` or `"consumer"` for queue work |
+| `attributes` | Attributes to set at span start |
+| `parent` | A span, or an inbound W3C `traceparent` string to continue a trace another service started. Defaults to the active span |
+| `tracestate` | The W3C `tracestate` accompanying a `traceparent` string. Ignored when `parent` is a span, which inherits its parent's |
+| `start_time` | Backdate the span's start, as a `datetime` or seconds since the epoch. The server clamps a start more than 24 hours old to receive time; with `debug` on, the SDK prints a debug message when you pass one |
+
+### Tracing across services
+
+Spans use [W3C Trace Context](https://www.w3.org/TR/trace-context/), so a trace can span several services. Pass an inbound `traceparent` header as `parent` to continue a trace another service started, and send `span.traceparent()` onward when you call out.
+
+app.py
+
+```python
+import requests
+from flask import request
+
+
+@app.post("/checkout")
+def checkout():
+    with posthog.start_span(
+        "POST /checkout",
+        kind="server",
+        parent=request.headers.get("traceparent"),
+    ) as span:
+        traceparent = span.traceparent()
+
+        requests.post(
+            "https://payments.internal/charge",
+            headers={"traceparent": traceparent} if traceparent else {},
+        )
+
+        return {"status": "ok"}
+```
+
+A malformed `traceparent` starts a new trace rather than raising. A missing one (`None`) falls back to the active span, if there is one.
+
+A continued trace propagates the sampled flag it was handed, so a downstream sampler sees the decision the head service made. PostHog itself doesn't sample – a span is recorded and exported whichever way that flag is set.
+
+### Linking traces to people and sessions
+
+Spans created inside a [context](#contexts) that has a distinct ID or session ID automatically carry `posthogDistinctId` and `sessionId` attributes, which is what makes a trace reachable from a person or a Session Replay recording. In Django, the [contexts middleware](/docs/libraries/django.md#django-contexts-middleware) sets these for every request. Elsewhere, set them yourself:
+
+Python
+
+```python
+from posthog import new_context, identify_context, set_context_session
+
+with new_context():
+    identify_context(user.id)
+    set_context_session(session_id)
+
+    with posthog.start_span("POST /checkout"):
+        process_order()
+```
+
+Spans created outside a context with those values omit the attributes.
+
+### Scrubbing and dropping spans
+
+`before_span_send` runs on every finished span before it's queued for export. It receives the span as a dict with `name`, `kind`, `status`, `attributes`, `events`, `start_time_ns`, `end_time_ns`, `trace_id`, `span_id`, and `parent_span_id`. Edit it and return it, or return `None` to drop the span entirely.
+
+Python
+
+```python
+def scrub_spans(span):
+    if span["attributes"].get("http.route") == "/health":
+        return None
+
+    span["attributes"].pop("http.request.header.authorization", None)
+    return span
+
+
+posthog = Posthog(
+    "<ph_project_token>",
+    host="https://us.i.posthog.com",
+    traces={
+        "service_name": "checkout-api",
+        "before_span_send": scrub_spans,
+    },
+)
+```
+
+Attributes are plain Python values, not the OTLP wire encoding. The hook runs after PostHog attaches `posthogDistinctId` and `sessionId`, so those are visible to the hook and can be scrubbed too. An exception's stack trace is on its event, under `event["attributes"]["exception.stacktrace"]`.
+
+-   `trace_id`, `span_id`, and `parent_span_id` are read-only. Rewriting them would orphan child spans that have already been exported, so changes are reverted.
+-   A hook that raises drops the span rather than exporting it without scrubbing.
+-   Pass a list to run several hooks in order. The first one to return `None` stops the chain.
+-   The hook must be a regular function. An `async` hook drops every span.
+-   If an entry isn't callable, tracing turns off for the client rather than exporting spans the hook was meant to scrub.
+
+### Span limits
+
+A span is capped at 128 attributes and 128 events, each event at 128 attributes, and each string attribute value at 8192 characters. The endpoint rejects a span that's too large, and a rejected span is lost whole rather than truncated, so the caps bound a span before it gets there.
+
+Past the cap, the earliest attributes and events are kept and the number dropped is reported alongside the span, so a truncated span reads as truncated rather than as quietly incomplete. The attributes PostHog attaches itself – `posthogDistinctId` and `sessionId` – don't count toward the cap and are never dropped, so a span at the limit still links back to its person and session.
+
+The event cap is absolute: an `exception` event the SDK records for you spends an ordinary slot like any other. A span that fills its events and then raises keeps its `error` status but not the exception detail, and reports the loss as a dropped event. Raise `max_events_per_span` on spans that record many events and can also fail.
+
+The length bound reaches inside a value, including strings nested in lists and dictionaries, and applies to `exception.stacktrace` like any other attribute – a long stack trace keeps its last 8192 characters. All four caps are re-applied after `before_span_send`, so a hook that enriches a span can't push it back over.
+
+### Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `service_name` | – | Name of the service producing spans. Set this |
+| `service_version` | – | Version of the service |
+| `environment` | – | Deployment environment, e.g. `production` |
+| `resource_attributes` | – | Extra OTLP resource attributes. Takes precedence over the fields above |
+| `flush_interval` | `5` | Seconds between exports of queued spans |
+| `max_export_batch_size` | `512` | Maximum spans per request |
+| `max_queue_size` | `2048` | Maximum spans held in memory. Spans beyond this are dropped |
+| `max_live_spans` | `10000` | Maximum spans open at once. At the limit `start_span` returns a span that isn't recorded |
+| `max_span_age` | `3600` | Once `max_live_spans` is reached, spans open longer than this many seconds are treated as leaked and never exported |
+| `before_span_send` | – | Edit or drop each finished span before export. Return `None` to drop it |
+| `max_attributes_per_span` | `128` | Maximum attributes you set on one span |
+| `max_events_per_span` | `128` | Maximum events on one span |
+| `max_attribute_value_length` | `8192` | Maximum characters in a string attribute value |
+
+An invalid value falls back to its default with a warning. The exception is `before_span_send`: an entry that isn't callable turns tracing off.
+
+### Shutdown and short-lived processes
+
+Spans are exported on a background interval, even with `sync_mode` on. Both `flush()` and `shutdown()` export spans that have already ended. A span still open at `flush()` is exported once it ends; a span still open at `shutdown()` is discarded with a warning, so end your spans before shutting down – a `with` block does this for you. `shutdown()` gives queued spans up to 30 seconds to send.
+
+In a serverless handler, call `flush()` before returning. Events and spans are flushed concurrently, so it costs one round trip, not two.
+
+Python
+
+```python
+def handler(event, context):
+    with posthog.start_span("handler"):
+        do_work()
+    posthog.flush()
+```
+
+A script that exits without calling `shutdown()` still gets a brief best-effort flush at exit, but don't rely on it for spans you need.
+
 ## GeoIP properties
 
 Before posthog-python v3.0, we added GeoIP properties to all incoming events by default. We also used these properties for feature flag evaluation, based on the IP address of the request. This isn't ideal since they are created based on your server IP address, rather than the user's, leading to incorrect location resolution.
@@ -674,8 +974,6 @@ You can go back to previous behavior by doing setting the `disable_geoip` argume
 
 Python
 
-PostHog AI
-
 ```python
 posthog = Posthog('api_key', disable_geoip=False)
 ```
@@ -694,8 +992,6 @@ You can also explicitly chose to enable or disable GeoIP for a single capture re
 
 Python
 
-PostHog AI
-
 ```python
 posthog.capture('test_event', disable_geoip=True|False)
 ```
@@ -708,8 +1004,6 @@ You can enable debug mode by setting the `debug` option to `True` in the `PostHo
 
 Python
 
-PostHog AI
-
 ```python
 posthog.debug = True
 ```
@@ -720,8 +1014,6 @@ You can disable requests during tests by setting the `disabled` option to `True`
 
 Python
 
-PostHog AI
-
 ```python
 if settings.TEST:
     posthog.disabled = True
@@ -739,10 +1031,9 @@ TCP keepalive probes help prevent idle connections from being dropped by network
 
 Python
 
-PostHog AI
-
 ```python
 import posthog
+
 posthog.enable_keep_alive()
 ```
 
@@ -754,10 +1045,9 @@ If you need each request to use a fresh connection, you can disable connection r
 
 Python
 
-PostHog AI
-
 ```python
 import posthog
+
 posthog.disable_connection_reuse()
 ```
 
@@ -767,11 +1057,10 @@ For advanced use cases, you can configure arbitrary socket options on the underl
 
 Python
 
-PostHog AI
-
 ```python
 import socket
 import posthog
+
 posthog.set_socket_options([
     (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1),
     # Add additional socket options as needed
@@ -786,19 +1075,25 @@ Use `before_send` to modify or drop events before they are queued for delivery.
 
 Python
 
-PostHog AI
-
 ```python
 from typing import Any
+
 import posthog
+
+
 def scrub_pii(event: dict[str, Any]) -> dict[str, Any] | None:
     properties = event.get("properties", {})
+
     if "email" in properties:
         email = properties["email"]
         properties["email"] = f"***@{email.split('@', 1)[1]}" if "@" in email else "***"
+
     if event.get("event") == "test_event":
         return None
+
     return event
+
+
 client = posthog.Client(
     "<ph_project_api_key>",
     before_send=scrub_pii,
@@ -811,48 +1106,50 @@ If your callback raises an exception, the SDK logs the error and continues with
 
 You can use the Python or Node SDK to run [historical migrations](/docs/migrate.md) of data into PostHog. To do so, set the `historical_migration` option to `true` when initializing the client.
 
-PostHog AI
-
 ### Python
 
 ```python
 from posthog import Posthog
 from datetime import datetime
+
 posthog = Posthog(
     '<ph_project_token>',
     host='https://us.i.posthog.com',
     debug=True,
     historical_migration=True
 )
+
 events = [
   {
     "event": "batched_event_name",
-    "properties": {
-      "distinct_id": "user_id",
-      "timestamp": datetime.fromisoformat("2024-04-02T12:00:00")
-    }
+    "distinct_id": "user_id",
+    "timestamp": datetime.fromisoformat("2024-04-02T12:00:00+00:00"),
+    "properties": {"account_type": "pro"}
   },
   {
     "event": "batched_event_name",
-    "properties": {
-      "distinct_id": "used_id",
-      "timestamp": datetime.fromisoformat("2024-04-02T12:00:00")
-    }
+    "distinct_id": "user_id",
+    "timestamp": datetime.fromisoformat("2024-04-03T09:30:00+00:00"),
+    "properties": {"account_type": "pro"}
   }
 ]
+
 for event in events:
   posthog.capture(
-    distinct_id=event["properties"]["distinct_id"],
-    event=event["event"],
+    event["event"],
+    distinct_id=event["distinct_id"],
     properties=event["properties"],
-    timestamp=event["properties"]["timestamp"],
+    timestamp=event["timestamp"],
   )
+
+posthog.shutdown()
 ```
 
 ### Node.js
 
 ```javascript
 import { PostHog } from 'posthog-node'
+
 const client = new PostHog(
     '<ph_project_token>',
     {
@@ -860,28 +1157,40 @@ const client = new PostHog(
       historicalMigration: true
     }
 )
+
 client.debug()
+
 client.capture({
     event: "batched_event_name",
     distinctId: "user_id",
     properties: {},
-    timestamp: "2024-04-03T12:00:00Z"
+    timestamp: new Date("2024-04-03T12:00:00Z")
 })
+
 client.capture({
     event: "batched_event_name",
     distinctId: "user_id",
     properties: {},
-    timestamp: "2024-04-03T13:00:00Z"
+    timestamp: new Date("2024-04-03T13:00:00Z")
 })
+
 await client.shutdown()
 ```
 
 ## Serverless environments (Render/Lambda/...)
 
-By default, the library buffers events before sending them to the capture endpoint, for better performance. This can lead to lost events in serverless environments, if the Python process is terminated by the platform before the buffer is fully flushed. To avoid this, you can either:
+### Synchronous `Posthog`
+
+By default, the synchronous `Posthog` client buffers events before sending them to the capture endpoint. This can lead to lost events if the platform terminates the Python process before the buffer is fully flushed. To avoid this, you can either:
+
+-   Call `posthog.shutdown()` before the process ends. This blocking call attempts to deliver queued events and cleans up the client.
+-   Enable `sync_mode` when initializing the client so each `posthog.capture()` call attempts delivery before it returns.
+
+If you use [distributed tracing](#distributed-tracing), `sync_mode` doesn't apply to spans. Call `posthog.flush()` before the handler returns – see [Shutdown and short-lived processes](#shutdown-and-short-lived-processes).
+
+### Asyncio `AsyncPosthog`
 
--   Ensure that `posthog.shutdown()` is called after processing every request by adding a middleware to your server. This allows `posthog.capture()` to remain asynchronous for better performance. `posthog.shutdown()` is blocking.
--   Enable the `sync_mode` option when initializing the client, so that all calls to `posthog.capture()` become synchronous.
+Keep one `AsyncPosthog` client for the lifetime of your application. Use buffered `capture()` by default, or `await capture_immediate()` when one invocation must wait for an event's delivery attempt. Call `await posthog.shutdown()` once during application cleanup. Don't shut down the client after each request.
 
 ## Django